# 4rgc/trellzo-backend architecture

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

- Interactive diagram: https://gitdiagram.com/4rgc/trellzo-backend
- Repository: https://github.com/4rgc/trellzo-backend

## Overview

##### Main Components
- API Service: This is contained within the “api” folder and provides the core business logic. It is divided into controllers, models, routes, schemas, and various utilities (e.g., JWT, crypt, mongoUrl).
- Database Service: Provided by the MongoDB container (under “mongo”) with seed scripts and configuration files.
- HTTPS Proxy: An Nginx-based proxy provided in the “https-proxy” folder. It acts as the entry point for secure client connections.
- Docker and Orchestration: Dockerfiles, docker-compose files, and scripts indicate that each service (API, MongoDB, Proxy) is containerized. These containers form the deployment unit when running the system.
- Deployment/CI Pipeline: The .github workflows show that continuous integration, delivery, and dependency management tasks are automated.

##### Relationships and Interactions
- Clients (web or mobile apps) will send requests to the secured endpoint (https://localhost). These requests are handled by the HTTPS proxy.
- The HTTPS proxy routes incoming traffic to the API server where the Routing layer (inside “api/src/routes”) directs requests to the appropriate controllers.
- Controllers use middleware for tasks like request validation (see “middleware/validateRequest.ts”), and delegate data operations to the data-controllers and models.
- The API service communicates with the MongoDB database (using connection settings from “api/src/util/mongoUrl.ts”) to read or write data.
- Docker-compose orchestrates starting/updating these services together, so the proxy, API, and MongoDB containers are connected in the network environment.

##### Architectural Patterns and Design Principles
- MVC-like Pattern: Although it’s an API, the project separates responsibilities between controllers (handling HTTP requests), models (business data representation), and schemas (data validation).
- Containerization & Microservice Approach: Services are built, deployed, and managed independently as Docker containers.
- Security: The use of HTTPS proxy and JWT-based authentication (see “api/src/util/jwt.ts”) is vital for secure communications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        client["Client (Web/Mobile)"]:::clientColor
    end

    %% Network Layer
    subgraph "Network Layer"
        httpsProxy["HTTPS Proxy (Nginx)"]:::network
    end

    %% Application Layer (API Service)
    subgraph "Application Layer (API Service)"
        apiService["API Service (Node.js/TypeScript)"]:::application
        subgraph "API Modules"
            controllers["Controllers"]:::internal
            routes["Routes"]:::internal
            models["Models"]:::internal
            schemas["Schemas"]:::internal
            middleware["Middleware"]:::internal
            utilities["Utilities (JWT, Crypt, mongoUrl)"]:::internal
        end
        %% Internal interactions (illustrative)
        controllers -->|"uses"| routes
        routes -->|"passes"| middleware
        middleware -->|"invokes"| models
        models -->|"validates with"| schemas
        utilities --- models
    end

    %% Data Layer
    subgraph "Data Layer"
        db["MongoDB Service<br/>(mongodb://localhost:27017)"]:::database
    end

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        subgraph "Docker & Orchestration"
            df_api["Dockerfile.api"]:::orchestration
            df_api_dev["Dockerfile.api-dev"]:::orchestration
            dc1["docker-compose.yml"]:::orchestration
            dc_remote["docker-compose.remote-seed.yml"]:::orchestration
            scriptsNode["Scripts Directory"]:::orchestration
        end
        cicd["CI/CD Pipeline (.github)"]:::cicd
    end

    %% Relationships
    client -->|"HTTPS_request"| httpsProxy
    httpsProxy -->|"Routes_Request"| apiService
    apiService -->|"Data_Operations"| db

    %% Deployment connections (illustrative)
    df_api --- apiService
    df_api_dev --- apiService
    dc1 --- apiService
    dc1 --- db
    dc_remote --- db
    scriptsNode --- apiService
    scriptsNode --- httpsProxy
    cicd --- df_api
    cicd --- dc1

    %% Click Events
    click apiService "https://github.com/4rgc/trellzo-backend/tree/main/api"
    click db "https://github.com/4rgc/trellzo-backend/tree/main/mongo"
    click httpsProxy "https://github.com/4rgc/trellzo-backend/tree/main/https-proxy"
    click df_api "https://github.com/4rgc/trellzo-backend/blob/main/Dockerfile.api"
    click df_api_dev "https://github.com/4rgc/trellzo-backend/blob/main/Dockerfile.api-dev"
    click dc1 "https://github.com/4rgc/trellzo-backend/blob/main/docker-compose.yml"
    click dc_remote "https://github.com/4rgc/trellzo-backend/blob/main/docker-compose.remote-seed.yml"
    click scriptsNode "https://github.com/4rgc/trellzo-backend/tree/main/scripts"
    click cicd "https://github.com/4rgc/trellzo-backend/blob/main/.github"

    %% Class Styles
    classDef clientColor fill:#bbf,stroke:#333,stroke-width:2px;
    classDef network fill:#fcf,stroke:#333,stroke-width:2px;
    classDef application fill:#cfc,stroke:#333,stroke-width:2px;
    classDef internal fill:#eef,stroke:#333,stroke-width:1px;
    classDef database fill:#ffa,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#fdd,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ddf,stroke:#333,stroke-width:2px;
```
