# rduuke/isis-todo-serverless architecture

> Architecture diagram of the GitHub repository rduuke/isis-todo-serverless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rduuke/isis-todo-serverless
- Repository: https://github.com/rduuke/isis-todo-serverless

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    EC["External API Client"]:::external

    %% API Entry Point
    APS["API Entry Point"]:::presentation

    %% Presentation/Web Layer
    subgraph "Presentation/Web Layer"
        RT["HTTP Routes"]:::presentation
        MW["Middleware (API Key & DTO)"]:::presentation
        CT["Controllers"]:::presentation
    end

    %% Application/Use Cases Layer
    subgraph "Application Layer"
        UC["Use Cases"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        DR["Repository Interface (Domain)"]:::domain
        TM["Todo Model"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        DYN["DynamoDB Repository"]:::infrastructure
        MOCK["In-Memory Repository"]:::infrastructure
    end

    %% External Dependency (AWS DynamoDB)
    AWS["AWS DynamoDB"]:::external

    %% Testing
    TS["Testing Suite"]:::testing

    %% Connections
    EC -->|"HTTP request"| APS
    APS -->|"routes"| RT
    RT -->|"executes"| MW
    MW --> CT
    CT -->|"delegates"| UC
    UC -->|"invokes"| DR
    DR -->|"ifUSE_DYNAMO"| DYN
    DR -->|"default"| MOCK
    DYN -->|"CRUD operations"| AWS
    TS -->|"verifies"| UC

    %% Click Events for Components
    click APS "https://github.com/rduuke/isis-todo-serverless/blob/main/src/index.ts"
    click CT "https://github.com/rduuke/isis-todo-serverless/tree/main/src/web/controllers"
    click RT "https://github.com/rduuke/isis-todo-serverless/tree/main/src/web/routes"
    click MW "https://github.com/rduuke/isis-todo-serverless/tree/main/src/web/middleware"
    click DR "https://github.com/rduuke/isis-todo-serverless/tree/main/src/core/domain"
    click UC "https://github.com/rduuke/isis-todo-serverless/tree/main/src/core/application"
    click DYN "https://github.com/rduuke/isis-todo-serverless/tree/main/src/core/infrastructure/repository"
    click MOCK "https://github.com/rduuke/isis-todo-serverless/tree/main/src/core/infrastructure/repository"
    click TS "https://github.com/rduuke/isis-todo-serverless/tree/main/src/tests"

    %% Styles
    classDef presentation fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef application fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef domain fill:#F1F8E9,stroke:#558B2F,stroke-width:2px;
    classDef infrastructure fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px;
    classDef external fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef testing fill:#E1F5FE,stroke:#0277BD,stroke-width:2px;
```
