# xbaank/madridtransporte-back architecture

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

- Interactive diagram: https://gitdiagram.com/xbaank/madridtransporte-back
- Repository: https://github.com/xbaank/madridtransporte-back

## Overview

##### Main Components
- API Service: This is the core component located in the “api” directory. It’s a ktor-based web service handling various REST endpoints. Within its source tree, you notice packages for routing (e.g., “lines”, “stops”, “notifications”) that separate the handling of different transportation modes (bus, EMT, metro, train). It also contains configuration and extension packages, which imply that a lot of shared behavior and configurations are abstracted out.
- Common Module: Found under “common”, this module hosts shared utilities, models (such as Stop, Route, Itinerary), queries, and exception handling code. This module likely provides the backbone data models and utility functions used by the API and other parts.
- Crtm Module: The “crtm” directory houses extensive Java SOAP client code. This integration is aimed at interfacing with external real-time or schedule-based transportation data sources from Madrid’s transportation system. The large number of SOAP-related classes indicates a rich integration using these services.
- Loader Service: Under the “loader” module, you have a separate Kotlin-based service (with its own Dockerfile) that appears to periodically load data (perhaps CSV files, as indicated by “StopsCsv.kt” and the provided entrypoint script) into the system’s datastore.
- Tests: The “tests” module contains integration and unit tests that cover endpoints for health check, lines, stops, various notifications, and utility functions. They help validate the API’s functionality.
- Infrastructure Components:
- MongoDB: As indicated in the README and docker-compose snippet, Mongo is used as the persistent datastore.
- Nginx: Serves as the reverse proxy, caching layer, and SSL terminator in front of the API service.
- Docker/Gradle: Deployment and build are managed using Docker (with specific Dockerfiles for API and loader) and Gradle build scripts throughout.

##### Out Relationships and Interactions
- MongoDB should be clearly depicted as the central datastore. Both API and loader (and any parts of common that manage database access) interact with Mongo.

##### Architectural Patterns and Design Principles
- Modularity: The project is effectively broken down into separate modules (api, common, crtm, loader). Emphasize how separation of concerns is maintained.
- Integration Patterns: SOAP APIs in the “crtm” module indicate an external integration layer. The RESTful API in “api” decouples the external API delivery from internal data gathering.
- Containerization: Using Dockerfiles and a docker-compose configuration reveals an infrastructure design aimed at containerized microservices (even if they run in a cohesive deployment).
- Periodic Data Loading: The use of a loader service that continuously runs in a loop (as shown in the entrypoint script) implies a background batch process.
- Testing: A well-organized “tests” module ensures that integration and unit tests validate the business logic across endpoints.

##### Implementation Advice for the Principal Software Engineer
- Use the provided docker-compose snippet and entrypoint script as hints for deployment structure.
- Stay detailed – capturing as many components as possible is key to accurately represent how the system works.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    Nginx["Nginx Reverse Proxy (SSL & Caching)"]:::external
    Mongo["MongoDB"]:::external

    %% Internal Application Modules
    API["API Service (Ktor - Routing, Config, Extensions, Notifications)"]:::internal
    Common["Common Module (Models, Queries, Utils)"]:::internal
    Crtm["Crtm Integration (SOAP Clients)"]:::internal
    Loader["Loader Service (Data Loader & CSV Processing)"]:::internal
    Tests["Tests (Unit & Integration)"]:::internal

    %% Deployment Infrastructure
    Deploy["Deployment Infrastructure (Docker, Gradle)"]:::deployment

    %% Connections
    Nginx -->|"HTTP/HTTPS"| API
    API -->|"Utilizes"| Common
    API -->|"SOAPCalls"| Crtm
    API -->|"DataRW"| Mongo
    Loader -->|"DataIngestion"| Mongo
    Deploy -->|"ContainerBuild"| API
    Deploy -->|"ContainerBuild"| Loader
    Tests -->|"Validates"| API

    %% Click Events
    click API "https://github.com/xbaank/madridtransporte-back/tree/master/api"
    click Common "https://github.com/xbaank/madridtransporte-back/tree/master/common"
    click Crtm "https://github.com/xbaank/madridtransporte-back/tree/master/crtm"
    click Loader "https://github.com/xbaank/madridtransporte-back/tree/master/loader"
    click Tests "https://github.com/xbaank/madridtransporte-back/tree/master/tests"
    click Deploy "https://github.com/xbaank/madridtransporte-back/tree/master/Dockerfile-api"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px
    classDef deployment fill:#98FB98,stroke:#000,stroke-width:2px
```
