# dzungtran/echo-rest-api architecture

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

- Interactive diagram: https://gitdiagram.com/dzungtran/echo-rest-api
- Repository: https://github.com/dzungtran/echo-rest-api

## Overview

##### Main Components
- API Service: This is located in the cmd/api directory. It serves as the entry point of the application.
- Business/Domain Modules: The project is organized into separate modules found in the "modules" directory (e.g., “core”, “projects”, and “shared”). These are responsible for core domain logic like handling users, organizations, and projects.
- Configuration and Dependency Injection: The "config" directory manages application settings, and dependency injection is implemented via uber-go/dig (see cmd/api/di).
- Infrastructure and Persistence:
- The “infrastructure” folder, along with the “migrations” directory, includes components for data access and database migrations.
- Under “infrastructure/datastore” you have SQL and Redis integrations.
- Shared Libraries and Utils: The “pkg” directory contains utilities, middleware, authorization (Rego files), constants, and helper functions that are used across the application.
- Tools: Tools for module generation (tools/mod) and route generation (tools/routes) assist in scaffolding and managing the project structure.
- External Services:
- Firebase is used for authentication.
- The Open Policy Agent is used to enforce role-based access control (RBAC) as seen in “pkg/authz”.

##### Relationships and Interactions
- The API service (cmd/api) accepts HTTP requests, which are routed to specific handlers in the modules (e.g., modules/core/handlers, modules/projects/handlers).
- Handlers then invoke usecases and business logic that reside within their respective module directories.
- These usecases interact with repository layers to perform database operations, as outlined in both the infrastructure and modules sections.
- The dependency injection mechanism (in cmd/api/di) wires the components together at startup.
- External integrations are encapsulated:
- Authentication flows interact with Firebase.
- RBAC is enforced through OPA policies (present in pkg/authz).
- Tools and migration frameworks link the development/deployment pipelines with the core application code.

##### Architectural Patterns and Technologies
- Clear Separation of Concerns: The project is organized into layers (API, business logic, data access) typical in an MVC/MVP architectural style even if not strictly following MVC.
- Module-Based Architecture: Using separate modules for different domains (core, projects, shared) enhances maintainability and scalability.
- Dependency Injection: Managed by uber-go/dig, ensuring loose coupling and easier testing.
- Use of External Services: Integration with Firebase for user authentication and OPA for authorization.
- Containerization: With Docker and docker-compose for local development and environment consistency.
- CLI-based code generation: Simplifies creating new modules or routes using tools in the “tools” directory.

##### Instructing the Principal Software Engineer
- Clear Labels: Ensure each component (API layer, modules, infrastructure, external services, etc.) is clearly labeled.
- Rectangles for service components (API server, modules).
- Cloud symbols for external services like Firebase and OPA.

##### Detailed Component Breakdown
- Top Layer: Client applications interacting via HTTP.
- Middle Layer: The API Gateway/Server represented by cmd/api.
- Handlers (request processing)
- Use Cases (business logic)
- Repositories (data access)
- Data & Infrastructure Layer: Containers for SQL/Redis (infrastructure/datastore, migrations) and shared utilities (pkg).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client Layer
    subgraph "Client Layer"
        Client("Client Application"):::client
    end

    %% API Layer
    subgraph "API Layer"
        API("REST API Service"):::service
        DI("Dependency Injection"):::service
        Config("Configuration Management"):::config
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Core("Core Module\n(Handlers, Usecases, Repositories)"):::module
        Projects("Projects Module\n(Handlers, Usecases, Repositories)"):::module
        Shared("Shared Module\n(Domain, DTO, Repositories)"):::module
    end

    %% Infrastructure & Persistence Layer
    subgraph "Infrastructure & Persistence"
        DBAccess("Database Access"):::infra
        Migrations("Database Migrations"):::infra
        SharedLib("Shared Libraries & Utilities"):::infra
    end

    %% External Services
    subgraph "External Services"
        Firebase("Firebase Authentication"):::external
        OPA("Open Policy Agent"):::external
    end

    %% Tools
    subgraph "Tools"
        ModTools("Module Generation Tools"):::tool
        RouteTools("Route Generation Tools"):::tool
    end

    %% Connections
    Client -->|"HTTP request"| API

    API -->|"wires dependencies"| DI
    API -->|"loads settings"| Config

    API -->|"routes to"| Core
    API -->|"routes to"| Projects
    API -->|"routes to"| Shared

    DI -->|"injects dependency"| Core
    DI -->|"injects dependency"| Projects
    DI -->|"injects dependency"| Shared
    DI -->|"injects dependency"| DBAccess

    Core -->|"calls repository"| DBAccess
    Projects -->|"calls repository"| DBAccess
    Shared -->|"calls repository"| DBAccess

    Core -->|"uses"| SharedLib
    Projects -->|"uses"| SharedLib
    Shared -->|"uses"| SharedLib

    API -->|"auth via"| Firebase
    API -->|"authorization via"| OPA

    %% Tools are used in development workflows
    ModTools ---|"scaffolds modules"| API
    RouteTools ---|"scaffolds routes"| API

    %% Database Migrations supports DBAccess
    DBAccess -->|"schema guided by"| Migrations

    %% Class Definitions
    classDef service fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef module fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef infra fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef external fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef tool fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef client fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;

    %% Click Events
    click API "https://github.com/dzungtran/echo-rest-api/tree/main/cmd/api"
    click DI "https://github.com/dzungtran/echo-rest-api/tree/main/cmd/api/di"
    click Config "https://github.com/dzungtran/echo-rest-api/tree/main/config"
    click Core "https://github.com/dzungtran/echo-rest-api/tree/main/modules/core"
    click Projects "https://github.com/dzungtran/echo-rest-api/tree/main/modules/projects"
    click Shared "https://github.com/dzungtran/echo-rest-api/tree/main/modules/shared"
    click DBAccess "https://github.com/dzungtran/echo-rest-api/tree/main/infrastructure/datastore"
    click Migrations "https://github.com/dzungtran/echo-rest-api/tree/main/migrations"
    click SharedLib "https://github.com/dzungtran/echo-rest-api/tree/main/pkg"
    click Firebase "https://github.com/dzungtran/echo-rest-api/blob/main/pkg/middlewares/firebase_auth.go"
    click OPA "https://github.com/dzungtran/echo-rest-api/tree/main/pkg/authz"
    click ModTools "https://github.com/dzungtran/echo-rest-api/tree/main/tools/mod"
    click RouteTools "https://github.com/dzungtran/echo-rest-api/tree/main/tools/routes"
```
