How jgdev/clean-architecture-backend works
Main Components
• Client / Request Source: This could be a UI application (or any HTTP client) that sends requests to the API. Additionally, there’s a CLI tool (src/bin/create-user.ts) used for user creation.
• API Gateway / HTTP Server:
– The API layer is handled in the “src/infrastructure/api” directory, which contains bootstrap files, controllers, middlewares, and route definitions (with different versions in the routes/v1 and routes/v2 directories).
– Include the serverless configuration (serverless.yml) for deployments on AWS, plus the HTTP server (npm run dev:http) when running in development mode.
• Business Logic / Core Layer:
– Found in “src/core”, this layer encapsulates domain entities (User, Record, Operation), error handling and primary use-cases (such as CreateRecordUseCase, CreateUserSessionUseCase, etc.).
– This layer forms the heart of the calculator functionality and the cost deduction mechanism.
• Data Persistence Layer:
– The “prisma” directory contains schema definitions and migrations that set up the database structure.
– In “src/infrastructure/database”, repositories integrate with the database using Prisma (for operations, records, and users).
• Caching Layer:
– Redis is used for caching, with a specific implementation found in “src/infrastructure/database/RedisCacheRepository.ts”. This can be illustrated as a separate component to support faster data retrieval.
• Operation Services:
– Located in “src/lib/services/operations”, these components (such as OperationAdditionImpl, OperationDivisionImpl, etc.) encapsulate the specific logic for each calculator operation and are wired into the business logic side.
• Optional External Services:
– If any operations (for instance, the random string generation) rely on external APIs (like RandomORG), highlight those integration points.
Relationships and Interactions
• Clients send HTTP requests to the API Gateway/HTTP Server.
• The API layer (controllers) processes requests, delegates to the corresponding use-cases in the core layer, and makes calls to the repositories (data persistence) or cache as needed.
• The core layer enforces business rules (e.g., checking user credit before performing an operation) and orchestrates the necessary operations.
• When persistence is required, the core interacts with the database layer, and caching can be used to optimize frequent lookups.
• For the serverless deployment, note that the API layer is wrapped with serverless functions — indicating that the same interactions occur but in the context of AWS Lambda (or equivalent) via the serverless framework.
Architectural Patterns and Design Principles
• Layered Architecture: Clear separation into API/infrastructure, domain/business logic (core), and data access (prisma/database).
• Dependency Inversion: The “src/core” defines interfaces and domain contracts while the “src/infrastructure” provides concrete implementations (e.g., for repositories and caching).
• Microservice-readiness: Although currently a single service, its components (API, business logic, database, and caching) are modular enough to be separated if needed.
• Serverless Deployment: A flexible design to run locally or on AWS with minimal changes.
Relevant Technologies and Frameworks
• Node.js with TypeScript as the programming platform.
• Prisma for database migration and ORM.
• Redis for caching operations.
• Docker Compose for easy local setup (as described in the README).
• Serverless Framework for AWS deployments.
• Testing frameworks (jest, as indicated by jest.config.js and the tests structure).
Detailed Component Separation
• API Layer:
– Controllers (e.g., CreateRecordController, RemoveRecordController)
– Routes (v1, v2)
– Middlewares (e.g., errorHandler, logger, session)
– HTTP bootstrapping and serverless integration.
• Business Logic/Core:
– Domain Entities (User, Record, Operation)
– Use-Cases (CreateRecord, ListRecords, etc.)
– Error handling (ValidationError, AuthorizationError, etc.)
• Infrastructure / Data:
– Database connectivity through Prisma (database migrations, schema.prisma)
– Redis caching (RedisCacheRepository)
– Repositories wrapping data access.
• Operations Library:
– A set of implementations to process each arithmetic operation, providing clear operation-specific logic.