How rmanguinho/clean-ts-api works
Project Type and Purpose
• This is a backend API built with Node.js and TypeScript following Clean Architecture.
• It exposes both REST (Express) and GraphQL (Apollo Server) endpoints.
• It’s architected for TDD, SOLID, DDD and supports user signup/login, survey creation/listing, survey answers and results.
• MongoDB serves as the persistence layer.
Key Layers from the File Tree
• src/main – framework adapters, server bootstrap, routing, documentation (Swagger), GraphQL setup.
• src/presentation – controllers, HTTP helper, middleware, error types.
• src/validation / src/infra/validators – request validation adapters and rules.
• src/domain – core business models (Survey, SurveyResult, Account) and use-case interfaces.
• src/data – implementations of those use-case interfaces, plus repository protocols (DB, crypto).
• src/infra – concrete adapters for cryptography (bcrypt, JWT), MongoDB repositories, helpers, validators.
• tests – unit and integration tests for each layer.
a. Main Components
• Clients: REST clients (e.g. Postman), GraphQL clients.
• API Gateway Layer: Express server + middleware, Apollo Server.
• Presentation Layer: Route adapters → Controllers → HTTP Responses.
• Validation Layer: Validation composite → specific validators.
• Application/Use-Case Layer: Interactors that orchestrate business rules.
• Domain Layer: Entities and use-case interfaces.
• Data Layer (Ports & Adapters): Repository interfaces (addAccount, loadSurveys, etc.), cryptography interfaces.
• Infrastructure Layer: MongoDB adapters, bcrypt/jwt adapters, logger adapter.
• External Services: MongoDB, Swagger UI for docs, static file server.
b. Relationships & Data Flow
1. Client → HTTP/GraphQL request arrives at Express/Apollo (API Gateway).
2. Request passes through global and route-specific middleware (CORS, bodyParser, auth, validation).
3. Adapter transforms raw request into Controller input.
4. Controller invokes the corresponding Use-Case interactor via Factory.
5. Use-Case calls Domain Entities and Ports (repository and crypto interfaces).
6. Ports are implemented by Infrastructure adapters (MongoDB, Bcrypt, JWT).
7. Data flows back up: DB → Use-Case → Controller → Response.
c. Architectural Patterns & Principles
• Onion/Clean Architecture: strict layer separation, depend-inversion.
• Factory Pattern: wiring dependencies in src/main/factories.
• Adapter Pattern: protocol adapters for Express, Apollo, MongoDB, crypto.
• Decorator Pattern: log-controller-decorator wraps controllers for error logging.
• Middleware as chain of responsibility.
d. Key Technologies & Frameworks
• Express.js, Apollo Server Express for HTTP/GraphQL.
• TypeScript with tsconfig path aliases.
• MongoDB via native driver / custom query-builder.
• Bcrypt & JSON Web Token for hashing/auth.
• Swagger (openapi) for REST docs.
• Jest + in-memory-mongo for tests.
Essential Elements to Capture
• Entry points: Express routes, GraphQL schema/resolvers.
• Middleware chain (auth, validation, error-handling).
• Controller → Use-Case interactions.
• Ports (interfaces) vs Adapters (concrete repos, crypto).
• Factory/Composition Root at top level wiring everything.
• External dependencies: MongoDB, Bcrypt, JWT, Swagger UI.