How xalsie/clean-architecture-api-boilerplate works
Project Type and Purpose
• This is a backend API service written in TypeScript and Node.js, following Uncle Bob’s Clean Architecture.
• It provides CRUD operations for users (with roles), sign‑in with JWT + refresh tokens, and basic authorization.
Core Architectural Layers
a. Domain (Entities): business models (User, Role, Token, Sign‑In).
b. Application (Use Cases): orchestrates use cases (create‑user, sign‑in, refresh‑token, etc.) and defines ports/interfaces for controllers, repositories, validations, etc.
c. Presentation (Interface Adapters): concrete controllers, middleware adapters, and response serializers.
d. Infrastructure (Frameworks & Drivers): Express server, routing, Knex migrations/seeds, SQL repositories.
e. Common (Cross‑cutting Concerns): generic adapters (email validator, bcrypt, JWT, sanitizers), helpers.
f. Main (Composition Root): factory functions wiring together controllers, use cases, repositories, middlewares.
Main Components and Data Flow
• Client → HTTP → Express Routes (infrastructure)
• Receives request, hands off to Express‑route adapters
• Route Adapter → Controller (presentation)
• Transforms HTTP req/res into internal request model
• Controller → Use Case (application)
• Invokes a specific use‑case (e.g., CreateUserUseCase) via its interface
• Performs validation, error handling via application‑layer errors & validation composites
• Use Case ↔ Domain (entities)
• Executes business logic using domain models
• Delegates persistence to repository ports (interfaces in application→repositories)
• Repository Implementation (infrastructure)
• Concrete SQL repositories use Knex to query the database
• Returns domain models or primitives back to use case
• Use Case → Presenter (presentation)
• Returns a response model (status, data) to the controller
• Controller → HTTP Response (infrastructure)
• Serializes to JSON using generic response wrappers
External Services
• Postgres/MySQL/SQLite via Knex (SQL migrations and seeds)
• JWT for authentication tokens (common adapters)
• BCrypt for password hashing (common adapter)
Architectural Patterns & Principles
• Clean Architecture (layers, dependency inward)
• Ports & Adapters: inner layers define interfaces (“ports”), outer layers implement them (“adapters”)
• Factory pattern in Main layer to assemble dependencies
• Composite & Leaf validators in Application layer
• Single Responsibility & Separation of Concerns
Detailed Elements
• Express server and routes → adapter → controller → use case → repository → database
• JWT & password‑hashing security adapters plugged into sign‑in and user‑creation flows
• Validation composites in the application layer before executing use cases
• Factory layer wiring: show main/factories invoking Express setup, global middlewares, and route registration