ArchiTS CLI Documentation

Welcome to the complete documentation of ArchiTS CLI, your modern backend architecture generator for TypeScript.

  • Quick Installation

    Install ArchiTS in a few minutes and create your first project

  • Quick Start

    Step-by-step guide to create your first backend architecture

  • Architectures

    Discover the three supported architectural patterns

What is ArchiTS?

ArchiTS CLI is a command-line tool developed in Go that automatically generates robust and well-organized backend project structures. It supports three proven architectural patterns and generate modern TypeScript code.

  • 💡Philosophy: ArchiTS helps you start your backend projects with a solid architecture, best practices, and automated configuration, allowing you to focus quickely on your business logic.

  • Why use ArchiTS?

    • Advantages

      • Time-saving: Project creation in 30 seconds

      • Best practices: Proven architectures and recommended patterns

      • Automatic configuration: Pre-configured ESLint, Jest, TypeScript

      • Flexibility: TypeScript support and optional ExpressJS, typeORM

      • Maintainability: Clear structure and separation of responsibilities

    • Use Cases

      • Quick start for REST APIs

      • Backend projects with complex architectures

      • Well-structured microservices

      • Applications following SOLID principles

      • Projects requiring high testability

  • Main Features

    FeatureDescriptionSupport
    Architectures3 professional architectural patterns✅ Layered, Clean, Hexagonal
    LanguagesFull TypeScript support✅ TS with optimized configuration
    LibrariesOptional ExpressJS or native Node.js✅ Choice during creation
    ORMOptional TypeORM✅ Choice during creation
    ToolsPre-configured ESLint, Jest, Nodemon✅ Automatic configuration
    DependenciesAutomatic package installation✅ npm + pnpm

Installation

    • Prerequisites for contributors

      Before contributing to ArchiTS, make sure you have the following tools installed on your system:

      ToolMinimum VersionVerification
      Go1.18+go version
      NodeJS16+ (LTS recommended)node --version
      npm8+npm --version
      Git2.0+git --version

    • Prerequisites for usage

      Before installing ArchiTS, make sure you have the following tools installed on your system:

      ToolMinimum VersionVerification
      NodeJS(LTS recommended)node --version
      npm8+npm --version

    • Start Contributing

      Follow these steps to install ArchiTS source code on your system:

      BASH

      # 1. Clone the repository git clone https://github.com/thomas-bressel/archi-ts-cli.git cd archi-ts-cli # 2. Automatic installation make install # 3. Reload your shell # Or restart your terminal source ~/.bashrc

      • ⚠️Important Note: ArchiTS is currently optimized for Linux and WSL. Using it on native Windows requires WSL (Windows Subsystem for Linux).

    • Installation with npm

      Follow these steps to install ArchiTS on your system:

      BASH

      # 1. Go on the official npm web site and follow the instructions https://www.npmjs.com/package/archits-cli # 2. Automatic installation npm install -g archits-cli # 3. Create a symlink for easier access (if using nvm) ln -sf /home/[your-username]/.nvm/versions/node/v[your-node-version]/lib/node_modules/archits-cli/bin/archits /home/[your-username]/.nvm/versions/node/v[your-node-version]/bin/archi

    • Verification of Installation

      Once the installation is complete, verify that everything is working correctly:

      BASH

      # Check ArchiTS version archi --version # Expected output: archi version 1.10.0 # Display help archi --help # Test project creation archi create

      • ✅Installation successful! If all commands work, ArchiTS is ready to be used.

Quick Start

    • Create your first project

      Let's create your first backend project with ArchiTS together:

      BASH

      # Launch interactive creation archi create

    • ArchiTS will guide you through a series of questions:

      BASH

      🚀 ArchiTS CLI - Project Scaffolding Project Name: mon-api-backend Use the arrow keys to navigate: ↓ ↑ → ← Select an architecture: Layered Architecture ▸ Clean Architecture Hexagonal Architecture Choose a library in the list ?: ▸ No library needed Express.js Select an ORM: ▸ I don't need ORM TypeORM Port Number: 6666█ ✅ Project structure created successfully!

    • Basic Commands

      Once your project is created, here are the essential commands:

      BASH

      # Navigate to the project cd my-backend-api # Install dependencies (already done automatically) npm install # Development with automatic reloading npm run dev # Build the project (TypeScript only) npm run build # Start in production npm run start # Run tests npm run test # Lint the code npm run lint # Generate a migration script npm run migration:generate <MyMigrationName> # Run a migration npm run migration:run

    • Complete Example

      Here is a complete example of creating and starting a project:

      BASH

      # 1. Create the project archi create # → Choose: Clean Architecture, TypeScript, ExpressJS # 2. Navigate to the project cd my-backend-api # 3. Start the development server npm run dev # 4. Test the API curl http://localhost:3000 # JSON response with project information

      • 🎯Result: You now have a functional API with a Clean architecture, TypeScript, and ExpressJS, ready to receive your business logic!

Supported Architectures

ArchiTS offers three proven architectural patterns, each adapted to different types of projects and levels of complexity.

    • 1. Layered Architecture

      Generated Structure:

      Description: Traditional architecture organized in horizontal layers with clear separation of responsibilities.

      TEXT

      src/ ├── business/ # Business layer (application logic) │ ├── interfaces/ # Interfaces and contracts for typing │ ├── models/ # Business models (domain objects) │ └── services/ # Business services (rules and logic) │ ├── common/ # Common components / shared utilities │ ├── config/ # General configuration (app, DB, logger, etc.) │ ├── constants/ # Global constants │ ├── errors/ # Custom error handling │ ├── logging/ # Logging system │ └── utils/ # Utility functions & helpers │ ├── data/ # Data access and management layer │ ├── database/ # Database setup (schemas, initialization) │ ├── connection/ # Database connections │ ├── migrations/ # Database migration scripts │ ├── seeds/ # Test / seed data for initialization │ ├── models/ # Data models (ORM, Sequelize, etc.) │ └── repositories/ # Repositories (CRUD data access) │ ├── presentation/ # Presentation layer (API, controllers, middlewares) │ ├── controllers/ # Controllers (handle requests/responses) │ ├── middlewares/ # Global middlewares │ │ ├── auth/ # Authentication handling │ │ ├── security/ # Security (CORS, rate limiting, etc.) │ │ └── validation/ # Input data validation │ └── routes/ # Application routes definition │ └── index.ts # Main entry point for routes

    • Recommended Use Cases:

      • Simple to medium CRUD applications

      • Traditional REST APIs

      • Projects with junior teams

      • Rapid prototyping

      • 👍Advantages: Simple to understand, quick to develop, ideal for beginners

    • 2. Clean Architecture

      Generated Structure:

      Description: Modular architecture organized around the business domain, featuring strict separation between business logic and technical details (databases, frameworks, interfaces). Each layer has a specific role with unidirectional dependencies pointing toward the business core.

      TEXT

      src/ ├── application/ # Application layer (orchestration of use cases) │ ├── dtos/ # Data Transfer Objects (requests/responses) │ ├── interfaces/ # Interfaces (contracts for layer abstractions) │ └── use-cases/ # Use cases (business logic orchestration) │ ├── domain/ # Domain layer (pure business rules) │ ├── entities/ # Domain entities (core business objects) │ ├── errors/ # Domain-specific errors │ └── value-objects/ # Value Objects (immutable business objects) │ ├── infrastructure/ # Infrastructure layer (technical implementations) │ ├── cache/ # Cache management (e.g., Redis, in-memory) │ ├── database/ # Database setup and initialization │ │ ├── config/ # Database configuration files │ │ │ ├── create-database.ts # Script to create the database │ │ │ └── data-source.ts # Database source and ORM connection │ │ └── migrations/ # Database migration scripts │ ├── email/ # Email handling (SMTP, external providers) │ ├── mappers/ # Mappers (conversion between entities, DTOs, models) │ └── repositories/ # Repositories (concrete DB implementations) │ ├── presentation/ # Presentation layer (API exposure) │ ├── controllers/ # Controllers (HTTP request entry points) │ ├── middlewares/ # Middlewares (auth, validation, security, etc.) │ ├── routes/ # API route definitions │ └── validators/ # Input data validation │ └── shared/ # Shared modules/utilities across layers └── index.ts # Entry point for shared exports

    • Recommended Use Cases:

      • Applications with complex business domains

      • Projects requiring high testability

      • Experienced teams

      • Scalable applications

      • 👍Advantages: Technological independence, maximum testability, scalability

    • 3. Hexagonal Architecture (Ports & Adapters)

      Generated Structure:

      Description: Architecture that completely isolates the business core from technical details via ports and adapters.

      TEXT

      scripts/ # Utility scripts (e.g., migration generation) │ └── generate-migration.ts # Script to automatically generate a migration │ src/ ├── adapters/ # Adapters side (concrete implementations of ports) │ ├── primary/ # Primary adapters (exposure, system entry points) │ │ ├── cli/ # Command Line Interface │ │ ├── grpc/ # gRPC interface │ │ └── http/ # HTTP interface │ │ ├── controllers/ # HTTP controllers │ │ ├── middlewares/ # HTTP middlewares │ │ └── routes/ # Routes definitions │ │ │ ├── secondary/ # Secondary adapters (external infrastructure) │ │ ├── cache/ # Cache management (Redis, memory) │ │ ├── email/ # Email handling (sending, providers) │ │ ├── persistence/ # Data persistence │ │ │ ├── models/ # Models (ORM mapping) │ │ │ └── orm/ # ORM files (config, datasource, migrations) │ │ │ ├── create-database.ts # Script to create the database │ │ │ └── data-source.ts # Database source & connection │ │ └── repositories/ # Concrete repository implementations │ │ │ └── storage/ # External storage (files, cloud, etc.) │ ├── application/ # Application layer (use case orchestration) │ ├── dtos/ # Data Transfer Objects (requests/responses) │ ├── ports/ # Ports (abstraction interfaces) │ │ ├── in/ # Incoming ports (interfaces exposed by domain) │ │ └── out/ # Outgoing ports (interfaces to external systems) │ └── use-cases/ # Use cases (application logic) │ ├── config/ # Project configuration │ └── dependencies/ # Dependency declaration/injection │ ├── domain/ # Domain layer (pure business core, independent) │ ├── entities/ # Business entities │ ├── events/ # Domain events │ ├── exceptions/ # Business exceptions │ ├── services/ # Domain services (reusable logic) │ └── value-objects/ # Value Objects (immutable business objects) │ ├── index.ts # Main entry point of the application │ storage/ # Data & persistent resources storage ├── database/ # Database-related directories │ ├── backups/ # Database backups │ ├── migrations/ # Database migration scripts │ ├── schema/ # Database schema │ └── seeds/ # Test/seed data for initialization ├── logs/ # Application logs ├── uploads/ # User-uploaded files │ ├── avatars/ # User avatars │ └── documents/ # Uploaded documents │ tests/ # Automated tests (unit, integration, e2e)

    • Recommended Use Cases:

      CriteriaLayeredCleanHexagonal
      Complexity⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
      Testability⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
      Scalability⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
      Learning CurveGentleModerateSteep
      Ideal ForCRUD, Simple APIsComplex DomainMicroservices

      • Complex microservices

      • Applications requiring multiple interfaces

      • Projects with frequent infrastructure changes

      • Advanced modular architecture

      • 👍Advantages: Maximum isolation, adapter flexibility, perfect testability

Configuration

    • TypeScript vs JavaScript

      TypeScript (the best !)

      ArchiTS no longer supports JavaScript (since version 1.10.0) and now focuses exclusively on TypeScript, due to JavaScript’s limitations in handling data encapsulation within an object-oriented structure.

      • 👍TypeScript Advantages: Static typing, Improved IntelliSense, Compile-time error detection, Better code documentation

    • Generated Files:

      • tsconfig.json Optimized TypeScript configuration

      • src/index.ts TypeScript entry point

      • jest.config.ts Jest configuration for TypeScript

    • TypeScript: Generated npm Scripts:

      JSON

      { "scripts": { "start": "node dist/src/index.js", "dev": "nodemon src/index.ts", "build": "tsc", "watch": "tsc --watch", "lint": "eslint src/**/*.ts", "lint:fix": "eslint src/**/*.ts --fix" } }

    • ExpressJS Configuration

      You can choose to use ExpressJS or native Node.js when creating the project.

      TYPESCRIPT

      import express, { Express, Request, Response } from 'express'; const server = express(); const PORT = 3000; // Routes server.get('/', (req: Request, res: Response) => { res.json({ message: 'Welcome to Archi API', version: '1.0.0', status: 'running', stack: 'NodeJS, Typescript', library: 'ExpressJS' }); }); // Start server server.listen(PORT, () => { console.log('Server running on http://localhost:' + PORT); });

    • Environment Variables

      ArchiTS automatically generates a .env file with all essential variables:

      BASH

      # Environment NODE_ENV=development # Server LISTEN_PORT="3000" SERVER_NAME="ArchiTS API" VERSION="1.0.0" # Database DB_HOST="localhost" DB_PORT="3306" DB_NAME="archi_db" DB_USER="root" DB_PASSWORD="my-super-password" DB_CONNEXION_LIMIT="100" # Redis REDIS_PORT="6379" REDIS_HOST="localhost" REDIS_PASSWORD="my-super-password" REDIS_EXPIRES_IN="3600" # JWT JWT_SECRET_KEY="your-secret-key" JWT_REFRESH_SECRET_KEY="your-refresh-secret-key" JWT_DURATION="2h" JWT_REFRESH_TOKEN_TIME="20h" # CORS CORS_ALLOWED_ORIGINS="http://localhost:3000" CORS_CREDENTIALS="true" # SMTP MAIL_HOST="mail.domain.fr" MAIL_PORT="465" MAIL_SECURE="true" MAIL_AUTH_USER="exemple@domain.fr" MAIL_AUTH_PASSWORD="my-super-password"

      • 🔒Security: Don't forget to change the default values, especially passwords and secret keys before going to production!

CLI Reference

    • archi create

      Main command to create a new project with ArchiTS.

      BASH

      archi create

    • Interactive Process:

      • Project Name: Defines the folder and package name

      • Architecture: Choice between Layered, Clean, or Hexagonal

      • Language: TypeScript

      • ExpressJS: Include or not the Express framework

    • Automatic Actions:

      • Creation of folder structure

      • Generation of configuration files

      • Installation of npm dependencies

      • Installation of pnpm

      • Git initialization (if applicable)

    • archi generate entity

      Command for automatically generating an entity and all its associated layers (repository, service, controller, route), according to the selected architecture (Layered, Clean, or Hexagonal).

      BASH

      # Full generation archi generate entity user # Short alias archi g e user

    • Automatic file cration :

      • <name>.routes.ts

      • <name>.entity.ts

      • <name>.controller.ts

      • <name>.service.ts

      • <name>.repository.ts

    • Jest unit test generation :

      • tests/unit/repositories/<name>.repository.test.ts

      • tests/unit/services/<name>.service.test.ts

      • tests/unit/controllers/<name>.controller.test.ts

    • archi version

      Displays detailed information about the version and environment.

      BASH

      # Short version archi -v # or archi --version # Detailed information archi version

    • Troubleshooting

      Support

      If you encounter problems not covered here: