# tonyzorin/cyprus-bus architecture

> Architecture diagram of the GitHub repository tonyzorin/cyprus-bus, 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/tonyzorin/cyprus-bus
- Repository: https://github.com/tonyzorin/cyprus-bus

## Overview

##### Main Components
- Data Ingestion and Management:
- update_db.js – main script for full updates, SQL backup generation, and data import.
- parseGTFS.js – processes GTFS files.
- database.js – contains connection and helper functions for database operations.
- gtfs-realtime.proto – defines protocols for real-time bus tracking data.
- Web Backend:
- backend.js – likely acts as the API server providing endpoints for data access.
- docs/openapi.yaml – provides API specifications (useful for designing API interactions).
- directions/generate.js – handles generation of route/direction data.
- Web Frontend:
- frontend.js – logic for client-side interactions.
- Files in the public directory (HTML, CSS, JavaScript, images & assets) – make up the user interface.
- Database Layer:
- Containerization and Deployment:
- Dockerfile and docker-compose.yml – indicate that the system is containerized and can be deployed using Docker.

##### Relationships and Interactions
- Data Update Flow:
- The update_db.js script is triggered (with various command-line options). It downloads GTFS data, utilizes parseGTFS.js to transform and validate the data, and then uses database.js to update or import data into the database.
- Backend API Flow:
- Frontend Interaction:
- The frontend components (frontend.js within public and index.html) provide user interaction. They make API calls to backend.js to retrieve real-time bus information, stop locations, route details, etc.
- Directions and Mapping:
- The directions/generate.js module should be shown as a special component that interfaces with the GTFS data—it might be used by either the backend to generate routes or by the frontend to display interactive mapping.
- Deployment Architecture:
- Container layer (Dockerfile/docker-compose.yml) which encapsulates the whole application. Indicate that the backend, frontend, and potentially the database are deployed in separate containers or services.

##### Architectural Patterns and Technologies
- Separation of Concerns:
- Distinct modules for updating data (ETL), serving APIs, and handling the frontend.
- Full-Stack Application Elements:
- Clear division between the frontend (static public assets served to users) and the backend API (Node.js likely, given the use of JavaScript files like backend.js).
- Use of Containerization:
- Docker and docker-compose files indicate that the system has been containerized, so note inter-container communication if multiple services (backend, database, etc.) are depicted.
- Data Flow Based on GTFS (batch and real-time data from gtfs-realtime.proto) which might be used for real-time bus updates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion and Management Layer
    subgraph "Data Ingestion Layer"
        A0["GTFS Data Source"]:::external
        A1["update_db.js"]:::etl
        A2["parseGTFS.js"]:::etl
        A3["database.js"]:::etl
        A4["gtfs-realtime.proto"]:::spec
    end

    %% Backend API Layer
    subgraph "Backend API"
        B1["backend.js"]:::backend
        B2["directions/generate.js"]:::backend
        B3["docs/openapi.yaml"]:::spec
    end

    %% Frontend Layer
    subgraph "Frontend"
        C1["frontend.js"]:::frontend
        C2["Public Assets"]:::frontend
    end

    %% Database Layer
    subgraph "Database"
        D1["Database\n(agency, calendar, stops, shapes, routes, trips, stop_times, calendar_dates, routes_by_city)"]:::database
    end

    %% Deployment/Containerization Layer
    subgraph "Deployment"
        E1["Dockerfile"]:::deployment
        E2["docker-compose.yml"]:::deployment
    end

    %% Data Ingestion Flow
    A0 -->|"triggers_update"| A1
    A1 -->|"calls_parser"| A2
    A2 -->|"updates_via_helper"| A3
    A3 -->|"populates"| D1

    %% Realtime Protocol Usage
    A4 -->|"defines_protocols_for"| B1

    %% Backend API Flow
    B1 -->|"queries"| D1
    B1 -->|"utilizes"| B2
    B1 -->|"documents_API_with"| B3

    %% Frontend Interaction
    C1 -->|"API_call"| B1
    C2 -->|"serves"| C1

    %% Deployment connections (containerization encapsulates components)
    E2 ---|"deploys"| A1
    E2 ---|"deploys"| B1
    E2 ---|"deploys"| C1
    E2 ---|"deploys"| D1

    %% Click Events
    click A1 "https://github.com/tonyzorin/cyprus-bus/blob/master//update_db.js"
    click A2 "https://github.com/tonyzorin/cyprus-bus/blob/master//parseGTFS.js"
    click A3 "https://github.com/tonyzorin/cyprus-bus/blob/master//database.js"
    click A4 "https://github.com/tonyzorin/cyprus-bus/blob/master//gtfs-realtime.proto"
    click B1 "https://github.com/tonyzorin/cyprus-bus/blob/master//backend.js"
    click B2 "https://github.com/tonyzorin/cyprus-bus/blob/master//directions/generate.js"
    click B3 "https://github.com/tonyzorin/cyprus-bus/blob/master//docs/openapi.yaml"
    click C1 "https://github.com/tonyzorin/cyprus-bus/blob/master//frontend.js"
    click C2 "https://github.com/tonyzorin/cyprus-bus/tree/master//public"
    click E1 "https://github.com/tonyzorin/cyprus-bus/tree/master//Dockerfile"
    click E2 "https://github.com/tonyzorin/cyprus-bus/blob/master//docker-compose.yml"

    %% Styles
    classDef etl fill:#FEEFB3,stroke:#B58900,stroke-width:2px;
    classDef backend fill:#DDF7E3,stroke:#2AA198,stroke-width:2px;
    classDef frontend fill:#E0F7FF,stroke:#268BD2,stroke-width:2px;
    classDef spec fill:#EFE1F5,stroke:#6C71C4,stroke-width:2px;
    classDef database fill:#FFF2CC,stroke:#B58900,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef deployment fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef external fill:#FCF6BD,stroke:#B58900,stroke-width:2px;
```
