ArchiTS CLI Documentation

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

  • 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 can generate modern TypeScript or JavaScript code.

  • 💡Philosophy: ArchiTS helps you start your backend projects with a solid architecture, best practices, and automated configuration, allowing you to focus 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/JavaScript support and optional ExpressJS

      • 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 and JavaScript support✅ TS/JS with optimized configuration
    FrameworkOptional ExpressJS or native Node.js✅ Choice during creation
    ToolsPre-configured ESLint, Jest, Nodemon✅ Automatic configuration
    DependenciesAutomatic package installation✅ npm + pnpm

Installation

    • Prerequisites

      Before installing 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

    • Installation on Linux/WSL

      Follow these steps to install ArchiTS 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).

    • 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.7.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 Select a language: ▸ TypeScript JavaScript (please don't, if you're a true developer) Do you want to use ExpressJS library? ▸ Yes, install Express No, I don't need Express ✅ 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 start # Run tests npm test # Lint the code npm run lint

    • 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/ ├── controllers/ # HTTP request handling │ └── base/ ├── services/ # Business logic │ └── base/ ├── repositories/ # Data access │ └── base/ ├── models/ # Entities and DTOs │ ├── entities/ │ ├── dtos/ │ ├── requests/ │ ├── responses/ │ └── database/ ├── middleware/ # Express Middlewares │ ├── auth/ │ ├── validation/ │ └── security/ ├── routes/ # Route definition │ ├── api/ │ └── web/ └── utils/ # Utilities

    • 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/ ├── domain/ # Pure business core │ └── entities/ ├── data/ # Data layer │ ├── repositories/ │ ├── data-sources/ │ │ └── local/ │ ├── services/ │ ├── dtos/ │ ├── models/ │ └── mappers/ ├── presentation/ # User interface │ ├── controllers/ │ ├── routes/ │ ├── middlewares/ │ └── models/ ├── infrastructure/ # External services │ ├── database/ │ ├── cache/ │ ├── email/ │ └── server/ └── shared/ # Shared code ├── utils/ └── constants/

    • 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

      src/ ├── core/ # Central hexagon │ ├── domain/ │ │ ├── entities/ │ │ ├── value-objects/ │ │ ├── services/ │ │ └── exceptions/ │ └── application/ │ ├── use-cases/ │ ├── commands/ │ ├── queries/ │ ├── handlers/ │ └── dtos/ ├── ports/ # Interfaces │ ├── inbound/ │ │ ├── http/ │ │ └── cli/ │ └── outbound/ │ ├── repositories/ │ ├── external-services/ │ └── infrastructure/ * ├── adapters/ # Implementations │ ├── inbound/ │ │ └── http/ │ │ ├── controllers/ │ │ ├── middleware/ │ │ └── routes/ │ └── outbound/ │ ├── repositories/ │ │ ├── mysql/ │ │ ├── redis/ │ │ └── mappers/ │ └── external-services/ ├── config/ # Configuration and DI │ ├── dependencies/ │ ├── database/ │ └── environment/ └── main/ # Entry point

    • 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 (Highly Recommended)

      ArchiTS fully supports TypeScript and JavaScript with optimized configurations for each language.

      • 👍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" } }

    • JavaScript: Generated npm Scripts:

      JSON

      { "scripts": { "start": "node src/index.js", "dev": "nodemon src/index.js", "lint": "eslint src/**/*.js", "lint:fix": "eslint src/**/*.js --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 or JavaScript

      • 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 version

      Displays detailed information about the version and environment.

      BASH

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

    • Troubleshooting

      Common Issues

      Displays detailed information about the version and environment.

      BASH

      ❌ Error: archi: command not found

      Solutions:

      # Reload the shell source ~/.bashrc # Or check the installation cd archi-ts-cli make install

      BASH

      ❌ Error: archi: command not found

      Solutions:

      # Reload the shell source ~/.bashrc # Or check the installation cd archi-ts-cli make install

      BASH

      ❌ Error: archi: command not found

      Solutions:

      # Give execution permissions chmod +x archi # Or reinstall make clean make install

    • Logs and Diagnostics

      To diagnose problems, you can:

      BASH

      # Check installation which archi # Test compilation make build # Clean and reinstall make clean make install

    • Support

      If you encounter problems not covered here: