# frozsgy/gezenti architecture

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

- Interactive diagram: https://gitdiagram.com/frozsgy/gezenti
- Repository: https://github.com/frozsgy/gezenti

## Overview

##### Project type and purpose
- This is a full-stack web application: a daily travel game (“Gezenti”) featuring Turkish cities.
- Frontend is a single-page, vanilla-JS UI with a map, autocomplete, and modal dialogs.
- Backend is a Python/Flask service that serves static assets and supplies game data via JSON.
- The “data” folder also contains preprocessing scripts that generate JSON input for the game.

##### File structure
Top-level files and folders:
- Procfile, build.sh – deployment configuration (Heroku).
- README.md, LICENSE – documentation.
- data/ – Python scripts + city and permutation data and JSON outputs.
- frontend/ – static web assets (HTML, CSS, JS).
data/ sub-structure:
- backend.py – Flask application entry point (serves API and static files).
- calculate.py, shuffle_permutations.py, etc. – data-generation scripts.
- *.json, *.txt – preprocessed city lists, distances, permutations.
frontend/ sub-structure:
- index.html – main UI.
- css/ – style, autocomplete, SVG-map styles.
- js/ – game logic, map interactions, autocomplete integration.

##### Insights from README
- Backend: Python + Flask.
- Frontend: vanilla JS, using three external libs:
- svg-turkiye-haritasi (map).
- autoComplete.js (autocomplete).
- tingle (modal).
- build.sh automates bundling of frontend + backend.py + dependencies for Heroku.

##### Main components
A. Browser / Client
- index.html, style.css, game.js, svg-turkiye-haritasi.js, autocomplete.js, tingle.js.
- User interactions: map clicks, text input, submissions.
B. Web Server / API Layer
- Flask app (data/backend.py).
- Routes:
– GET / → serves index.html and static assets.
– GET /api/game or similar → returns today’s city-pair data JSON.
C. Data Layer
- Preprocessed JSON under data/ (cities.json, permutations.json, etc.).
- Python model classes (city.py, distance.py, game.py) used both for preprocessing and live logic.
D. Build & Deployment
- build.sh bundles everything under a deployable directory.
- Procfile instructs Heroku to run: “python backend.py”.
- Rendering library.
- Autocomplete library.
- Modal/dialog library.

##### Relationships and interactions
- The Browser requests index.html from Flask → Flask serves static file.
- Browser loads CSS and JS assets → renders UI.
- On page load or on button click, Browser sends AJAX request to Flask (/api/game).
- Flask reads JSON data, applies any game-logic via game.py, returns JSON response.
- Browser updates UI (map, suggestions, modal) based on JSON.
- build.sh reads frontend/ and data/backend.py + requirements.txt → produces final bundle.
- Deployment on Heroku uses Procfile to start the Flask process.

##### Architectural patterns and principles
- Monolithic architecture: a single Flask application handling both static assets and API.
- Layered separation:
- Presentation layer (frontend).
- Application/API layer (Flask).
- Data layer (JSON files + Python models).
- Preprocessing step decouples heavy data generation from runtime.

##### Elements
- From Browser → Flask (HTTP GET/POST).
- From Flask → JSON files (read).
- From build.sh → bundle directory.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client (Browser)"
        direction TB
        UI[index.html]:::frontend
        Style1[style.css]:::frontend
        Style2[autocomplete.css]:::frontend
        Style3[svg-turkiye-haritasi.css]:::frontend
        Logic1[game.js]:::frontend
        Logic2[svg-turkiye-haritasi.js]:::frontend
        ExternalMap["Map Library"]:::external
        ExternalAuto["Autocomplete Library"]:::external
        ExternalModal["Modal Library"]:::external
    end

    %% Server/API Tier
    subgraph "Server/API (Flask)"
        direction TB
        FlaskApp[backend.py]:::backend
        ReqFile[requirements.txt]:::backend
        API["/api/game"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer (Preprocessing & JSON)"
        direction TB
        CalcScript[calculate.py]:::data
        ShuffleScript[shuffle_permutations.py]:::data
        Model1[city.py]:::data
        Model2[city_pair.py]:::data
        Model3[distance.py]:::data
        Model4[game.py]:::data
        Raw1[cities.txt]:::data
        Raw2[neighbours.txt]:::data
        JSON1[cities.json]:::data
        JSON2[permutations.json]:::data
        JSON3[permutations_shuffled.json]:::data
    end

    %% Build & Deployment
    subgraph "Build & Deployment Pipeline"
        direction TB
        BuildScript[build.sh]:::pipeline
        ProcfileNode[Procfile]:::pipeline
        Bundle["Deployable Bundle"]:::pipeline
    end

    %% Runtime Interactions
    UI -->|"GET /"| FlaskApp
    FlaskApp -->|serves| UI
    UI --> Style1
    UI --> Style2
    UI --> Style3
    UI --> Logic1
    UI --> Logic2
    UI --> ExternalMap
    UI --> ExternalAuto
    UI --> ExternalModal

    UI -->|"AJAX /api/game"| API
    API --> FlaskApp
    FlaskApp -->|reads| JSON1
    FlaskApp -->|reads| JSON2
    FlaskApp -->|reads| JSON3
    FlaskApp -->|uses models| Model1
    FlaskApp -->|uses models| Model2
    FlaskApp -->|uses models| Model3
    FlaskApp -->|uses models| Model4
    FlaskApp -->|reads raw| Raw1
    FlaskApp -->|reads raw| Raw2

    %% Preprocessing Workflow
    CalcScript --> JSON1
    CalcScript --> JSON2
    ShuffleScript --> JSON3
    Model1 --> CalcScript
    Model2 --> CalcScript
    Model3 --> CalcScript
    Model4 --> CalcScript

    %% Build & Deploy Workflow
    BuildScript -->|bundles| UI
    BuildScript -->|bundles| FlaskApp
    BuildScript -->|bundles| ReqFile
    BuildScript -->|outputs| Bundle
    ProcfileNode -->|starts| FlaskApp

    %% Click Events
    click UI "https://github.com/frozsgy/gezenti/blob/main/frontend/index.html"
    click Style1 "https://github.com/frozsgy/gezenti/blob/main/frontend/css/style.css"
    click Style2 "https://github.com/frozsgy/gezenti/blob/main/frontend/css/autocomplete.css"
    click Style3 "https://github.com/frozsgy/gezenti/blob/main/frontend/css/svg-turkiye-haritasi.css"
    click Logic1 "https://github.com/frozsgy/gezenti/blob/main/frontend/js/game.js"
    click Logic2 "https://github.com/frozsgy/gezenti/blob/main/frontend/js/svg-turkiye-haritasi.js"
    click FlaskApp "https://github.com/frozsgy/gezenti/blob/main/data/backend.py"
    click ReqFile "https://github.com/frozsgy/gezenti/blob/main/data/requirements.txt"
    click CalcScript "https://github.com/frozsgy/gezenti/blob/main/data/calculate.py"
    click ShuffleScript "https://github.com/frozsgy/gezenti/blob/main/data/shuffle_permutations.py"
    click Model1 "https://github.com/frozsgy/gezenti/blob/main/data/city.py"
    click Model2 "https://github.com/frozsgy/gezenti/blob/main/data/city_pair.py"
    click Model3 "https://github.com/frozsgy/gezenti/blob/main/data/distance.py"
    click Model4 "https://github.com/frozsgy/gezenti/blob/main/data/game.py"
    click Raw1 "https://github.com/frozsgy/gezenti/blob/main/data/cities.txt"
    click Raw2 "https://github.com/frozsgy/gezenti/blob/main/data/neighbours.txt"
    click JSON1 "https://github.com/frozsgy/gezenti/blob/main/data/cities.json"
    click JSON2 "https://github.com/frozsgy/gezenti/blob/main/data/permutations.json"
    click JSON3 "https://github.com/frozsgy/gezenti/blob/main/data/permutations_shuffled.json"
    click BuildScript "https://github.com/frozsgy/gezenti/blob/main/build.sh"
    click ProcfileNode "https://github.com/frozsgy/gezenti/tree/main/Procfile"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef backend fill:#90ee90,stroke:#333,stroke-width:1px
    classDef data fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef pipeline fill:#ffe4b5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#f0e68c,stroke:#333,stroke-width:1px
```
