# harreshyohan/task-management-api architecture

> Architecture diagram of the GitHub repository harreshyohan/task-management-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harreshyohan/task-management-api
- Repository: https://github.com/harreshyohan/task-management-api

## Overview

##### Project Type and Purpose
- The project is a RESTful API for task management that uses Node.js and TypeScript.
- It provides CRUD operations for tasks, integrates with AWS services (DynamoDB for data persistence and S3 for file attachments), and includes an external API integration with caching.

##### Analysis of the File Structure
- Top-level source directory (“src”) organizes the architectural components:
- config: Contains environment and configuration settings (e.g., src/config/index.ts).
- controllers: Handles incoming requests (business logic coordination) including external API and task handling.
- middlewares: Contains express middlewares such as error handling, request validation, etc.
- models: Defines data models (e.g., taskModel.ts) which represent the schema and structure of tasks.
- routes: Maps API endpoints (e.g., /tasks, /users) to controller logic.
- services: Contains the core business logic; interacts with external AWS services, including DynamoDB (dynamoService.ts), S3 (s3Service.ts), and an external API.
- utils: Utility functions used across the application.
- server.ts: Application entry point that sets up the Express server.
- lambda.ts: Contains the AWS Lambda integration handler for serverless deployments.
- The presence of separate directories for tests (unit and integration) supports a modular development approach.
- Configuration files (.env.example, tsconfig.json, eslint.config.js, etc.) and GitHub workflows indicate modern development practices and CI/CD integration.

- And represent the following main components:
- Client / External Request Source: Represents the consumers (could be web client, mobile client, or API Gateway for Lambda deployment) sending HTTP requests.
- Express Server: The central point running in Node.js (server.ts) which routes requests to different parts of the system.
- Controllers: Two main groups (taskController and externalApiController) that handle incoming API routes.
- Routes: Represent how different endpoints (e.g., /tasks, /users) are mapped to controllers.
- Services: Highlight the service layer which includes:
- Task-related service logic that interacts with DynamoDB (dynamoService).
- External API integrations and caching (externalApiService).
- File attachment handling via S3 (s3Service).
- Models: Represent data models (taskModel) that define the data schema.
- Directional flow:
- Clients send requests (HTTP REST calls) that hit the Express server.
- Requests flow through the middleware layer before reaching the appropriate controller.
- Controllers call the service layer to perform business logic.
- Services interact with data persistence (DynamoDB) and file storage (S3), as well as external API services.
- Responses then travel back following a similar reverse path.
- Additional components for testing can be noted separately (unit tests and integration tests) to indicate that the system is well-validated.

##### Important Architectural Patterns and Technology Choices
- Separation of Concerns: The clear division between configuration, routes, controllers, middlewares, and services is an example of modular design.
- RESTful API design: Emphasize the use of HTTP verbs to manage CRUD operations.
- AWS Integration: Indicate how AWS services are abstracted via the service layer.
- Serverless Capabilities: The existence of lambda.ts suggests that one deployment model uses AWS Lambda with API Gateway.
- Technologies: Mention Node.js (v22 LTS), Express.js, TypeScript, AWS SDK, Jest for testing, and Joi for validation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients and API Gateway
    A["Client Request"]:::external
    B["API Gateway/Load Balancer"]:::external
    A -->|"sends HTTP request"| B

    %% Deployment Options Subgraph
    subgraph "Deployment Options"
        ES["Express Server"]:::internal
        L["AWS Lambda Integration"]:::internal
    end
    B --> ES
    B --> L

    %% Merge deployment flows into API Handler
    M["API Handler"]:::internal
    ES --> M
    L --> M

    %% API Routing Layer
    R["API Routing"]:::internal
    M --> R

    %% Middleware Layer Subgraph
    subgraph "Middleware Layer"
        MW1["Request Validator"]:::internal
        MW2["Error Handler"]:::error
    end
    R --> MW1
    MW1 --> MW2

    %% Controllers Layer Subgraph
    subgraph "Controllers"
        C1["Task Controller"]:::internal
        C2["External API Controller"]:::internal
    end
    MW2 --> C1
    MW2 --> C2

    %% Services Layer Subgraph
    subgraph "Business Logic & External Service Integration"
        S1["DynamoDB Service"]:::internal
        S2["S3 Service"]:::internal
        S3["External API Service"]:::internal
    end
    C1 --> S1
    C1 --> S2
    C2 --> S3

    %% External AWS and External API Components
    ED["AWS DynamoDB"]:::external
    ES3["AWS S3"]:::external
    EA["External API"]:::external
    S1 -->|"stores/retrieves data"| ED
    S2 -->|"handles attachments"| ES3
    S3 -->|"calls and caches"| EA

    %% Supporting components
    CS["Configuration Settings"]:::internal
    DM["Data Models"]:::internal
    UT["Utility Functions"]:::internal
    %% Show support relationships
    CS --- ES
    CS --- L
    DM --- S1
    DM --- S2
    UT --- S1
    UT --- S3

    %% Click Events
    click ES "https://github.com/harreshyohan/task-management-api/blob/master/src/server.ts"
    click L "https://github.com/harreshyohan/task-management-api/blob/master/src/lambda.ts"
    click CS "https://github.com/harreshyohan/task-management-api/blob/master/src/config/index.ts"
    click MW1 "https://github.com/harreshyohan/task-management-api/tree/master/src/middlewares"
    click MW2 "https://github.com/harreshyohan/task-management-api/tree/master/src/middlewares"
    click C1 "https://github.com/harreshyohan/task-management-api/tree/master/src/controllers"
    click C2 "https://github.com/harreshyohan/task-management-api/tree/master/src/controllers"
    click R "https://github.com/harreshyohan/task-management-api/tree/master/src/routes"
    click S1 "https://github.com/harreshyohan/task-management-api/tree/master/src/services"
    click S2 "https://github.com/harreshyohan/task-management-api/tree/master/src/services"
    click S3 "https://github.com/harreshyohan/task-management-api/tree/master/src/services"
    click DM "https://github.com/harreshyohan/task-management-api/blob/master/src/models/taskModel.ts"
    click UT "https://github.com/harreshyohan/task-management-api/blob/master/src/utils/index.ts"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef error fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
