How rduuke/isis-todo-serverless works
Main Components
• API Entry Point & Server: This is represented by src/index.ts, which bootstraps the Express server.
• Web Layer (HTTP Interface):
• Controllers (e.g., create.controller.ts, delete.controller.ts, list.controller.ts, update.controller.ts)
• Routes (e.g., create.routes.ts, delete.routes.ts, list.routes.ts, upate.routes.ts)
• Middleware (e.g., API key authentication in api-key.middleware.ts and DTO validation in validate.dto.ts)
• Core Domain & Application Layer:
• Domain: Contains the Todo model and repository interfaces (todo.model.ts, todo.repository.ts).
• Use Cases: Business logic for creating, updating, listing, and deleting todos (create-todo.usecase.ts, etc.) along with DTO definitions.
• Infrastructure Layer:
• Repository Implementations for persistence, with two versions:
• In-memory/mock repository (todo.mock.repository.ts)
• DynamoDB-based repository (todo.dynamo.repository.ts)
• Testing:
• Unit tests for use cases in src/tests covering the core business logic.
• External Dependencies:
• AWS DynamoDB if configured (USE_DYNAMO true in .env).
• Postman collection for API testing.
• Environment configuration (.env) and deployment scripts.
Relationships and Interactions
• The entry point (src/index.ts) initializes the Express server.
• The Express server routes incoming HTTP requests to the appropriate Controllers via the defined Routes.
• Controllers in the web layer receive the HTTP calls, perform preliminary work (e.g., validating API keys with middleware), and delegate to relevant use cases in the Core Application.
• The Application Layer (Use Cases) accesses domain entities and interacts with repository interfaces defined in the Domain layer.
• At runtime, the infrastructure layer provides concrete implementations for repository access (either the in-memory or DynamoDB version) by adhering to the domain repository interface.
• Responses from use cases are routed back as HTTP responses via the Controllers.
Architectural Patterns and Design Principles
• Clean Architecture or Onion Architecture is clearly followed:
• The Core (Domain and Application) is independent of the web and infrastructure implementations.
• Dependency inversion is evident where repository interfaces are defined in the domain and implemented in the infrastructure.
• API Security is handled with custom middleware protecting endpoints (checking x-api-key in headers).
• Flexibility is achieved through configuration – the persistence strategy (mock vs. DynamoDB) is selected via environment variables.
Relevant Technologies and Frameworks
• Node.js and TypeScript for server-side runtime and static type checking.
• Express as the web framework managing HTTP endpoints.
• AWS DynamoDB for production-grade persistence (with an in-memory alternative for development/testing).
• Testing frameworks (e.g., Jest) for unit tests.
• Postman collection for external API testing.