# carrismetropolitana/api architecture

> Architecture diagram of the GitHub repository carrismetropolitana/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/carrismetropolitana/api
- Repository: https://github.com/carrismetropolitana/api

## Overview

##### Project Type and Purpose
- The README clearly explains that this is an API service for providing transit information (lines, routes, stops, vehicles, alerts, and more) by processing an official GTFS feed.
- The project is structured as a multi-app (almost microservices-like) monorepo, with multiple applications under the “apps” folder that include the main API server as well as several “sync” and “switch” services.
- Its goal is to serve real-time and static transit data to client applications (e.g., web or mobile apps).

##### File Structure to Recognize Key Architectural Areas
- apps/sync-* folders (sync-alerts, sync-facilities, sync-gtfs, sync-locations, sync-metrics, sync-stores, sync-vehicles): These appear to be microservices or scheduled tasks responsible for synchronizing data, likely importing or updating data from the official GTFS feed or other sources.
- apps/switch: Although its exact purpose isn’t immediately obvious, its placement and the naming suggest it might be handling routing or toggling between different operational modes or data pipelines.
- packages folder: Contains shared libraries or modules such as “services” (for database or external service integrations like Redis, Mongo, Trino, etc.), “settings”, “types”, “utils” and common TypeScript configurations.
- CI/CD pipelines are defined as GitHub workflows (.github/workflows).

##### Main Components
a. API Server:
– Represent the “Server” component (apps/server) that manages the public API endpoints described in the README.
b. Sync Services:
c. Switch Service:
– Represent the “Switch” component (apps/switch) as a specialized handler that may manage additional processing or routing logic.
d. Shared Packages and Services:
– Include a block for shared libraries (from packages/services, packages/settings, packages/types, packages/utils) which provide common functionality (integration with external databases such as MongoDB, Redis, Trino, handling GTFS data, etc.).
e. Infrastructure and External Integrations:
– Include a Load Balancer / Reverse Proxy (nginx, as seen in the nginx folder) which fronts the API.
– Display external dependencies/resources:
- The official GTFS feed (data source from Carris Metropolitana GTFS GitHub repository).
- External databases or caches (if used in packages/services, e.g., redis.service.ts, mongo.service.ts, trino.service.ts).
f. Container and Deployment Elements:
– Add a container orchestration layer (docker-compose) that coordinates all microservices. Show how each app (server, sync services, switch) runs in its own Docker container.
– Indicate that CI/CD pipelines (using GitHub workflows) are used for building and deploying images.

##### Relationships and Interactions
– Clients send HTTP requests to the API server via the load balancer.
– The API Server queries shared services (via packages/services) or databases.
– Sync services running in parallel update the database or data storage which the API server then reads from to serve requests.
– The Switch service interacts with the API server and/or sync tasks to possibly manage data flows.
– External integrations (GTFS feed source, external databases) are connected to the sync services and/or shared service layer.

##### Architectural Patterns and Design Principles
- Microservices / Modular Design: The separation of the API server and multiple sync tasks suggests a microservices-like architecture.
- Containerization: Each app has its own Dockerfile which shows adherence to containerization best practices.
- Separation of Concerns: Different directories (endpoints, services, tasks) indicate a clear separation between API handling and background processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients and Frontend
    Client["Clients (Web/Mobile)"]:::external
    LoadBalancer["Load Balancer (nginx)"]:::external

    %% API Layer
    APIServer["API Server (apps/server)"]:::api

    %% Shared Libraries
    subgraph "Shared Libraries"
        SharedServices["Shared Services"]:::shared
        SharedSettings["Shared Settings"]:::shared
        SharedTypes["Shared Types"]:::shared
        Utilities["Utility Functions & Helpers"]:::shared
    end

    %% Sync Services
    subgraph "Sync Services"
        syncAlerts["Sync Alerts Service"]:::sync
        syncFacilities["Sync Facilities Service"]:::sync
        syncGTFS["Sync GTFS Service"]:::sync
        syncLocations["Sync Locations Service"]:::sync
        syncMetrics["Sync Metrics Service"]:::sync
        syncStores["Sync Stores Service"]:::sync
        syncVehicles["Sync Vehicles Service"]:::sync
    end

    %% Switch Service
    SwitchService["Switch Service (apps/switch)"]:::sync

    %% External and Data Integrations
    subgraph "External & Data"
        GTFSFeed["GTFS Feed (Official)"]:::external
        ExternalDB["External Databases/Caches"]:::external
    end

    %% Deployment and CI/CD
    subgraph "Deployment & Orchestration"
        CI_CD["CI/CD (GitHub Workflows)"]:::deployment
        ContainerOrch["Container Orchestration (docker-compose)"]:::deployment
    end

    %% Connections
    Client -->|"HTTP_Request"| LoadBalancer
    LoadBalancer -->|"Routes"| APIServer
    APIServer -->|"Queries"| SharedServices
    APIServer -->|"Reads_Data"| ExternalDB

    %% Sync Services Data Flow
    syncGTFS -->|"Ingests_GTFS"| GTFSFeed
    syncAlerts -->|"Sync_Updates"| ExternalDB
    syncFacilities -->|"Sync_Updates"| ExternalDB
    syncGTFS -->|"Sync_Updates"| ExternalDB
    syncLocations -->|"Sync_Updates"| ExternalDB
    syncMetrics -->|"Sync_Updates"| ExternalDB
    syncStores -->|"Sync_Updates"| ExternalDB
    syncVehicles -->|"Sync_Updates"| ExternalDB

    %% Switch Service Interactions
    SwitchService -->|"Manages_Routing"| APIServer
    SwitchService -->|"Interacts_with"| syncGTFS

    %% Shared Libraries Detail
    SharedServices --- SharedSettings
    SharedServices --- SharedTypes
    SharedServices --- Utilities

    %% Deployment connections to services
    ContainerOrch --- APIServer
    ContainerOrch --- syncAlerts
    ContainerOrch --- syncFacilities
    ContainerOrch --- syncGTFS
    ContainerOrch --- syncLocations
    ContainerOrch --- syncMetrics
    ContainerOrch --- syncStores
    ContainerOrch --- syncVehicles
    ContainerOrch --- SwitchService

    CI_CD --- ContainerOrch

    %% Styling Classes
    classDef api fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef sync fill:#99ff99,stroke:#333,stroke-width:2px;
    classDef shared fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef deployment fill:#cccccc,stroke:#333,stroke-width:2px;

    %% Click Events
    click APIServer "https://github.com/carrismetropolitana/api/tree/v2/apps/server"
    click syncAlerts "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-alerts"
    click syncFacilities "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-facilities"
    click syncGTFS "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-gtfs"
    click syncLocations "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-locations"
    click syncMetrics "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-metrics"
    click syncStores "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-stores"
    click syncVehicles "https://github.com/carrismetropolitana/api/tree/v2/apps/sync-vehicles"
    click SwitchService "https://github.com/carrismetropolitana/api/tree/v2/apps/switch"
    click SharedServices "https://github.com/carrismetropolitana/api/tree/v2/packages/services"
    click SharedSettings "https://github.com/carrismetropolitana/api/tree/v2/packages/settings"
    click SharedTypes "https://github.com/carrismetropolitana/api/tree/v2/packages/types"
    click Utilities "https://github.com/carrismetropolitana/api/tree/v2/packages/utils"
    click LoadBalancer "https://github.com/carrismetropolitana/api/tree/v2/nginx"
    click CI_CD "https://github.com/carrismetropolitana/api/tree/v2/.github/workflows"
    click ContainerOrch "https://github.com/carrismetropolitana/api/blob/v2/compose.yml"
```
