# benjamintd/chronotrains architecture

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

- Interactive diagram: https://gitdiagram.com/benjamintd/chronotrains
- Repository: https://github.com/benjamintd/chronotrains

## Overview

Based on our analysis of the file tree and the README, Chronotrains is a Next.js-based full-stack application that delivers an interactive mapping experience for exploring train isochrones (reachable areas in up to 5 hours). The project leverages a modern serverless architecture (deployed on Vercel) with significant components including a frontend built with Next.js and React, backend API endpoints also in Next.js, pre-processing scripts (both Node.js and SQL) which compute isochrones via a Postgres database managed with Prisma, and internationalization support via next-i18next.

- Frontend Client:
- Represented by Next.js pages in the src/pages folder.
- Components (in src/components) such as adBlock and meta, and styling integrations via Tailwind.
- Internationalization provided by next-i18next (configured in next-i18next.config.js) and locale files in public/locales.
- Mapping interaction via Mapbox GL, as mentioned in the README.

- Backend/API Layer:
- API endpoints housed in src/pages/api.
- A clear separation between regular Next.js pages (rendered on the server/edge) and specific API routes that deliver data (e.g., isochrones, station information).
- Deployment on Vercel leverages edge caching for faster delivery of precomputed GeoJSON isochrones.

- Data Processing and Pre-computation:
- Node.js scripts in src/scripts which include compute-isochrones.ts, scrape.ts, and various SQL scripts.
- These scripts pre-process raw data (from external APIs such as the Deutsche Bahn data via Drittanbieter like Direkt Bahn Guru) by building and querying a graph of train stations to compute reachable areas.
- Scheduled or manually triggered computation processes that compute and store GeoJSON isochrones.

- Database and ORM:
- Database migration and management handled via the Prisma ORM (files in the prisma directory, including migrations and the schema.prisma).
- The production database is a Postgres instance hosted at Supabase, where all journey data, station graphs, and computed isochrones are stored.

- External Dependencies and Data Sources:
- Integration with an external API that wraps Deutsche Bahn data.
- Dependency on Mapbox GL for interactive mapping on the client-side.
- Vercel deployment settings and potential caching strategies.

##### Out Relationships and Interactions
- User Interaction Flow:
- The user initiates a request from their browser, which is routed to the Next.js frontend hosted on Vercel.
- The frontend page uses Mapbox GL to display the interactive map and shows isochrones. It retrieves data from the backend API (e.g., routes like api/closest-station or api/stations).

- API and Data Flow:
- API endpoints fetch or send data to the Postgres database via Prisma.
- Data flows from the database to the API layer, then to the frontend to render isochrone visuals.

- Pre-Processing Flow:
- Separately, Node.js and SQL scripts pre-compute isochrones based on scraped raw data.
- The computed isochrones (as GeoJSON) are stored in the database and subsequently served via the API.

- Internationalization:
- The frontend integrates with next-i18next to load localized JSON files from the public/locales directory ensuring a multilingual map experience.

##### Architectural Patterns and Design Principles
- Serverless and Edge Architecture:
- Leveraging Next.js’s serverless functions and Vercel’s Edge caching to ensure fast response times.

- Separation of Concerns:
- Clear distinction between the frontend UI, backend API endpoints, and data processing scripts.
- Use of Prisma for managing database operations illustrates a clear ORM usage pattern.

- Microservice-like Segregation:
- Though it’s a monorepo, different parts of the system (user interface, API endpoints, pre-processing scripts) function independently – a popular design strategy in modern full-stack applications.

- Modular and Internationalized Approach:
- Modularized components and localization support illustrate a design aimed at scalability and easy maintenance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Client"
        FE_Pages["Next.js Pages"]:::frontend
        FE_Components["React Components"]:::frontend
        FE_Style["Styling & Tailwind"]:::frontend
    end

    subgraph "Internationalization"
        I18n_Config["next-i18next Config"]:::intl
        I18n_Locales["Locale Files"]:::intl
    end

    subgraph "Backend/API Layer"
        API["Next.js API Endpoints"]:::api
    end

    subgraph "Data Processing"
        DP_Node["Node.js Scripts"]:::processing
        DP_SQL["SQL Scripts"]:::processing
    end

    subgraph "Database and ORM"
        PSP["Prisma Setup"]:::db
        PC["Prisma Client"]:::db
        DB["Postgres (Supabase)"]:::db
    end

    subgraph "External Dependencies"
        EXT_MB["Mapbox GL"]:::external
        EXT_DB["Deutsche Bahn API"]:::external
        EXT_Vercel["Vercel (Edge & Caching)"]:::external
    end

    %% Relationships
    FE_Pages ---|"renders"| FE_Components
    FE_Pages ---|"integrates"| I18n_Config
    I18n_Config ---|"loads"| I18n_Locales
    FE_Pages ---|"fetchesDataFrom"| API
    FE_Components ---|"styledBy"| FE_Style

    API ---|"utilizes"| PSP
    PSP ---|"calls"| PC
    PC ---|"queries"| DB

    DP_Node ---|"precomputesIsochrones"| DP_SQL
    DP_Node ---|"storesDataIn"| DB
    DP_SQL ---|"executesOn"| DB

    FE_Pages ---|"displaysMapVia"| EXT_MB

    EXT_Vercel ---|"hostsAndCaches"| FE_Pages
    EXT_Vercel ---|"cachesAPIResponses"| API

    API ---|"retrievesTrainDataFrom"| EXT_DB

    %% Click Events
    click FE_Pages "https://github.com/benjamintd/chronotrains/tree/main/src/pages"
    click FE_Components "https://github.com/benjamintd/chronotrains/tree/main/src/components"
    click FE_Style "https://github.com/benjamintd/chronotrains/tree/main/src/styles"
    click I18n_Config "https://github.com/benjamintd/chronotrains/blob/main/next-i18next.config.js"
    click I18n_Locales "https://github.com/benjamintd/chronotrains/tree/main/public/locales"
    click API "https://github.com/benjamintd/chronotrains/tree/main/src/pages/api"
    click DP_Node "https://github.com/benjamintd/chronotrains/tree/main/src/scripts"
    click DP_SQL "https://github.com/benjamintd/chronotrains/tree/main/src/scripts"
    click PSP "https://github.com/benjamintd/chronotrains/tree/main/prisma"
    click PC "https://github.com/benjamintd/chronotrains/blob/main/src/lib/prisma.ts"

    %% Styling Classes
    classDef frontend fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef intl fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef api fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef processing fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef db fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
```
