# kilencje/tori architecture

> Architecture diagram of the GitHub repository kilencje/tori, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kilencje/tori
- Repository: https://github.com/kilencje/tori

## Overview

This is a **server-rendered Node.js/Express web application** (monolith) that serves:
- **HTML pages rendered with EJS** (`views/*.ejs`, `views/partials/navbar.ejs`)
- **Static assets** (CSS, images, and a public `data.json`) from `public/`
- **Content/data from local JSON files** (`data.json`, `quiz.json`, `technology.json`)
- A **client-side embedded external experience** via **NUKEMAP iframe** (in the Technology page)
- A **data maintenance/sync pipeline** via `utils/update-data.js` (CSV <-> JSON, “Google Sheets integration” likely via axios or CSV export URLs)

##### Runtime request/response (Browser ↔ Express ↔ EJS ↔ JSON/static)
2) **Offline/admin data update flow** (Developer/Admin ↔ update-data.js ↔ CSV/Sheets ↔ JSON files)

##### Read the file tree as architecture hints (what to reflect as components)
From the tree:

##### Runtime (web app)
- `app.js` → **single Express entrypoint**: routes, middleware (compression, caching), view engine setup
- `views/` → **EJS server-side rendering** (SSR)
- `public/` → **static hosting** (style.css, pictures, and `public/data.json`)
- Root JSON files: `data.json`, `quiz.json`, `technology.json` → **local content store**
- `data.js` (present) → likely a **data access/helper module**; include it as an internal “Data Loader/Repository” component if it’s used by `app.js`.

##### Offline / tooling
- `utils/update-data.js` → CLI tool for **CSV import/export + sync**
- `package.json` dependencies: express, ejs, compression, axios → include:
- `compression` = response gzip
- `axios` = outbound HTTP requests (likely Sheets/CSV download, or remote sync)

##### External
- NUKEMAP (iframe) → external site loaded in client browser (not server-to-server)
- Google Sheets / CSV source → external data origin for the sync tool

##### Client (Browser)
- loads HTML
- loads CSS/images from `/public`
- sends navigation requests with language query param
##### Node.js Process (Express Server)
- Middleware: compression (gzip), caching headers
- Router/controller layer for each route
- View rendering via EJS
- Reads JSON from filesystem
##### File Storage (Local filesystem)
- `data.json`, `quiz.json`, `technology.json`
- `public/style.css`, `public/pictures/*`, `public/data.json`
##### (Optional but recommended) Reverse Proxy / Hosting Edge
- If deployed behind Nginx/Apache/Cloud proxy, show it as a separate container (even if not in repo). If unknown, annotate as “optional”.

**Key flows**
- Browser ⇄ Express:
- Requests pages → Express chooses route → loads data → renders EJS → returns HTML
- Browser → Express (static):
- Requests `/style.css`, `/pictures/*` → Express static middleware returns files with long cache headers
- Express → filesystem:
- Reads JSON content (battles/weapons/quiz/tech)
- Browser → NUKEMAP:
- iframe loads nukemap directly

- Express → Browser: “gzip compression”
- Express → Browser: “Cache-Control (HTML 1h, CSS/JS 7d, images 30d, API data 30m)” (from README)

Purpose: show the major modules inside the Node process. This is where you “separate into as many components as possible”.

Within the **Express App** boundary, split into:

##### Middleware Layer
- `compression` (gzip)
- “Static Assets Middleware” serving `public/`
- “Cache Policy Middleware” (per content type)
- “Error Handling / 404” rendering `views/error_404.ejs`

##### Routing / Controllers (group by feature)
- Home Controller: `GET /` → renders `views/index.ejs`
- Battles Controller:
- `GET /battles` → `views/battles.ejs` list
- `GET /battle/:id` → `views/battle.ejs` details
- Weapons Controller:
- `GET /weapons` → `views/weapons.ejs`
- `GET /weapon/:id` → `views/weapon.ejs`
- Quiz Controller:
- `GET /quiz` → `views/quiz.ejs` (difficulty, scoring logic)
- Technology Controller:
- `GET /technology` → `views/technology.ejs` (includes nukemap iframe)
- About Controller:
- `GET /about` → `views/about.ejs`

##### Localization / i18n Resolver
Even if it’s simple, model it:
- “Language Resolver” reads `?lang=` and selects fields like `name_en/name_hu/name_ro`, `description_*`, `question_*`, etc.
- Passes resolved strings into EJS templates

##### Data Access Layer (filesystem JSON)
As:
- “Battles & Weapons Repository” reading from `data.json`
- “Quiz Repository” reading from `quiz.json`
- “Technology Repository” reading from `technology.json`
- (If `data.js` exists as a helper, show it as the module implementing these reads/parses/caches.)

##### View Layer (EJS)
- EJS templates per page + shared partial: `views/partials/navbar.ejs`
- Static theme: `public/style.css`
- Images: `public/pictures/*`

- Controllers → Repositories (read data)
- Controllers → i18n Resolver (select language-specific fields)
- Controllers → EJS Views (render)
- EJS Views → Partials (navbar include)
- Views → Static assets (referenced by URL; browser fetches them)

##### Don’t forget the “data sync” architecture (it’s part of the system)

**Components**
- Admin/Developer (human)
- `utils/update-data.js` (Node CLI tool)
- CSV files in repo root (input/output)
- Google Sheets / Google Drive export endpoints (external)
- JSON stores: `data.json`, `quiz.json`, `technology.json` (outputs consumed by runtime server)

- update-data.js ↔ Google Sheets: HTTP fetch/upload (use axios)
- update-data.js ↔ CSV files: read/write
- update-data.js → JSON files: generate/update
- Express runtime → JSON files: read at runtime

##### Container: Browser / Node(Express) / Local FS / External systems
3) **Component (Express)**: middleware, controllers per route, i18n resolver, repositories, EJS views/partials
##### Data Pipeline: update-data.js ↔ Sheets/CSV → JSON → consumed by runtime

That set is detailed, accurate to the tree/README, and separates “serving the site” from “maintaining the content,” which is the key architectural reality of this project.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ========== Diagram 1: System Context (Level 1) ==========
  subgraph "System Context (Level 1)"
    EU["End User (Student/Visitor)"]:::external
    BR["Web Browser"]:::frontend
    APP["WWII History Web App\n(Node.js/Express + EJS SSR)"]:::backend
    NUK["NUKEMAP\n(External Website)"]:::external
    ADM["Admin/Developer\n(Content Maintainer)"]:::admin
    SHEETS["Google Sheets / CSV Export Endpoints"]:::external
    TOOL["Data Sync CLI\n(update-data.js)"]:::tooling

    EU -->|"uses"| BR
    BR -->|"HTTP GET pages\n/?lang=en,hu,ro\n/battles /weapons /quiz /technology /about"| APP
    BR -->|"iframe loads\n(technology page)"| NUK

    ADM -->|"runs CLI"| TOOL
    TOOL -->|"HTTP GET (CSV export)\nvia axios"| SHEETS
    TOOL -->|"writes/updates\nJSON content files"| APP
  end

  %% ========== Diagram 2: Container (Level 2) ==========
  subgraph "Container View (Level 2)"
    EDGE["Optional Hosting Edge\n(Reverse Proxy/CDN)"]:::edge
    BRC["Browser"]:::frontend

    subgraph "Node Runtime"
      NODE["Node.js Process\nExpress Server"]:::backend
      MW["Middleware\ncompression + caching + static"]:::backend
      SSR["EJS View Engine\n(SSR)"]:::backend
    end

    subgraph "Local Filesystem"
      FSJSON[("JSON Content Files\n(data/quiz/technology)")]:::datastore
      FSPUB[("Static Assets\n(public/*)")]:::datastore
    end

    NUK2["NUKEMAP (External)"]:::external

    BRC -->|"HTTP requests"| EDGE
    EDGE -->|"forwards HTTP"| NODE

    NODE -->|"applies\nCache-Control policies"| MW
    MW -->|"serves /public/*\n(Cache-Control: long-lived)"| FSPUB
    NODE -->|"renders pages\n(gzip compression)"| SSR
    SSR -->|"reads content"| FSJSON

    BRC -->|"GET /style.css /pictures/* /data.json"| EDGE
    BRC -->|"iframe request (client-side)"| NUK2
  end

  %% ========== Diagram 3: Component (Level 3) - Express internals ==========
  subgraph "Component View (Level 3) - Express App Internals"
    subgraph "Express App (app.js)"
      APPJS["Express App Entrypoint\n(app.js)"]:::backend

      subgraph "Middleware Layer"
        COMP["compression (gzip)"]:::backend
        STATIC["Static Assets Middleware\nserves public/"]:::backend
        CACHE["Cache Policy Middleware\n(per content type)"]:::backend
        ERR["404/Error Handler\n(renders error view)"]:::backend
      end

      subgraph "Routing / Controllers"
        R_HOME["Home Controller\nGET /"]:::backend
        R_BATTLES["Battles Controller\nGET /battles\nGET /battle/:id"]:::backend
        R_WEAP["Weapons Controller\nGET /weapons\nGET /weapon/:id"]:::backend
        R_QUIZ["Quiz Controller\nGET /quiz"]:::backend
        R_TECH["Technology Controller\nGET /technology"]:::backend
        R_ABOUT["About Controller\nGET /about"]:::backend
      end

      I18N["Language Resolver (i18n)\nreads ?lang=\nselects *_en/*_hu/*_ro"]:::backend

      subgraph "Data Access Layer"
        DATAJS["Data Loader / Repository Helper\n(data.js)"]:::backend
        REPO_D["Battles & Weapons Repository\nreads data.json"]:::datastore
        REPO_Q["Quiz Repository\nreads quiz.json"]:::datastore
        REPO_T["Technology Repository\nreads technology.json"]:::datastore
      end

      subgraph "View Layer (EJS)"
        VIEWS["EJS Views Directory\n(views/)"]:::view
        V_NAV["Navbar Partial\n(navbar.ejs)"]:::view
        V_IDX["index.ejs"]:::view
        V_BATL["battles.ejs"]:::view
        V_BATD["battle.ejs"]:::view
        V_WEAL["weapons.ejs"]:::view
        V_WEAD["weapon.ejs"]:::view
        V_QUIZ["quiz.ejs"]:::view
        V_TECH["technology.ejs\n(contains NUKEMAP iframe)"]:::view
        V_ABT["about.ejs"]:::view
        V_404["error_404.ejs"]:::view
      end

      subgraph "Public Assets"
        PUBROOT["public/"]:::static
        STYLE["style.css"]:::static
        PICS["pictures/*"]:::static
        PUBDATA["public/data.json"]:::static
      end

      EXTNUK["NUKEMAP (External)"]:::external

      %% Middleware wiring
      APPJS -->|"registers"| COMP
      APPJS -->|"registers"| CACHE
      APPJS -->|"registers"| STATIC
      APPJS -->|"registers"| ERR

      %% Routing wiring
      APPJS -->|"routes"| R_HOME
      APPJS -->|"routes"| R_BATTLES
      APPJS -->|"routes"| R_WEAP
      APPJS -->|"routes"| R_QUIZ
      APPJS -->|"routes"| R_TECH
      APPJS -->|"routes"| R_ABOUT

      %% Controller dependencies
      R_HOME -->|"resolve language"| I18N
      R_BATTLES -->|"resolve language"| I18N
      R_WEAP -->|"resolve language"| I18N
      R_QUIZ -->|"resolve language"| I18N
      R_TECH -->|"resolve language"| I18N
      R_ABOUT -->|"resolve language"| I18N

      R_BATTLES -->|"load data"| DATAJS
      R_WEAP -->|"load data"| DATAJS
      R_QUIZ -->|"load quiz"| DATAJS
      R_TECH -->|"load tech"| DATAJS

      DATAJS -->|"read file"| REPO_D
      DATAJS -->|"read file"| REPO_Q
      DATAJS -->|"read file"| REPO_T

      %% Render paths
      R_HOME -->|"render EJS"| V_IDX
      R_BATTLES -->|"render EJS"| V_BATL
      R_BATTLES -->|"render EJS"| V_BATD
      R_WEAP -->|"render EJS"| V_WEAL
      R_WEAP -->|"render EJS"| V_WEAD
      R_QUIZ -->|"render EJS"| V_QUIZ
      R_TECH -->|"render EJS"| V_TECH
      R_ABOUT -->|"render EJS"| V_ABT
      ERR -->|"render EJS"| V_404

      %% View composition
      VIEWS -->|"contains"| V_NAV
      V_IDX -->|"includes"| V_NAV
      V_BATL -->|"includes"| V_NAV
      V_BATD -->|"includes"| V_NAV
      V_WEAL -->|"includes"| V_NAV
      V_WEAD -->|"includes"| V_NAV
      V_QUIZ -->|"includes"| V_NAV
      V_TECH -->|"includes"| V_NAV
      V_ABT -->|"includes"| V_NAV
      V_404 -->|"includes"| V_NAV

      %% Static references
      STATIC -->|"serves"| PUBROOT
      PUBROOT -->|"contains"| STYLE
      PUBROOT -->|"contains"| PICS
      PUBROOT -->|"contains"| PUBDATA

      %% External embed
      V_TECH -->|"iframe URL referenced\n(client loads directly)"| EXTNUK
    end
  end

  %% ========== Diagram 4: Data Sync / Content Pipeline ==========
  subgraph "Data Sync / Content Pipeline (Offline/Admin)"
    HUMAN["Admin/Developer"]:::admin
    UPD["update-data.js\n(Node CLI tool)"]:::tooling
    AX["axios (HTTP client)"]:::tooling
    CSV["CSV Files\n(import/export)"]:::datafile
    GS["Google Sheets / Drive\n(CSV export endpoints)"]:::external

    JSOND[("data.json")]:::datastore
    JSONQ[("quiz.json")]:::datastore
    JSONT[("technology.json")]:::datastore

    RUNTIME["Express Runtime\n(consumes JSON at runtime)"]:::backend

    HUMAN -->|"runs CLI"| UPD
    UPD -->|"uses"| AX
    AX -->|"HTTP GET (CSV export)"| GS
    UPD -->|"read/write"| CSV
    UPD -->|"generate/update"| JSOND
    UPD -->|"generate/update"| JSONQ
    UPD -->|"generate/update"| JSONT
    RUNTIME -->|"read file at runtime"| JSOND
    RUNTIME -->|"read file at runtime"| JSONQ
    RUNTIME -->|"read file at runtime"| JSONT
  end

  %% ========== Click Events (from component_mapping) ==========
  click APPJS "https://github.com/kilencje/tori/blob/main/app.js"
  click DATAJS "https://github.com/kilencje/tori/blob/main/data.js"
  click REPO_D "https://github.com/kilencje/tori/blob/main/data.json"
  click REPO_Q "https://github.com/kilencje/tori/blob/main/quiz.json"
  click REPO_T "https://github.com/kilencje/tori/blob/main/technology.json"
  click VIEWS "https://github.com/kilencje/tori/tree/main/views/"
  click V_NAV "https://github.com/kilencje/tori/blob/main/views/partials/navbar.ejs"
  click V_IDX "https://github.com/kilencje/tori/blob/main/views/index.ejs"
  click V_BATL "https://github.com/kilencje/tori/blob/main/views/battles.ejs"
  click V_BATD "https://github.com/kilencje/tori/blob/main/views/battle.ejs"
  click V_WEAL "https://github.com/kilencje/tori/blob/main/views/weapons.ejs"
  click V_WEAD "https://github.com/kilencje/tori/blob/main/views/weapon.ejs"
  click V_QUIZ "https://github.com/kilencje/tori/blob/main/views/quiz.ejs"
  click V_TECH "https://github.com/kilencje/tori/blob/main/views/technology.ejs"
  click V_ABT "https://github.com/kilencje/tori/blob/main/views/about.ejs"
  click V_404 "https://github.com/kilencje/tori/blob/main/views/error_404.ejs"
  click PUBROOT "https://github.com/kilencje/tori/tree/main/public/"
  click STYLE "https://github.com/kilencje/tori/blob/main/public/style.css"
  click PICS "https://github.com/kilencje/tori/tree/main/public/pictures/"
  click PUBDATA "https://github.com/kilencje/tori/blob/main/public/data.json"
  click UPD "https://github.com/kilencje/tori/blob/main/utils/update-data.js"
  click TOOL "https://github.com/kilencje/tori/blob/main/utils/update-data.js"
  click AX "https://github.com/kilencje/tori/blob/main/package.json"
  click COMP "https://github.com/kilencje/tori/blob/main/package.json"
  click APP "https://github.com/kilencje/tori/blob/main/README.md"
  click EDGE "https://github.com/kilencje/tori/blob/main/README.md"
  click CACHE "https://github.com/kilencje/tori/blob/main/PERFORMANCE_OPTIMIZATION.md"
  click MW "https://github.com/kilencje/tori/blob/main/PERFORMANCE_OPTIMIZATION.md"

  %% ========== Styles ==========
  classDef frontend fill:#d6ecff,stroke:#1b6aa8,stroke-width:1.5px,color:#0b2b40
  classDef backend fill:#cfe6ff,stroke:#245b9e,stroke-width:1.5px,color:#0b2b40
  classDef view fill:#e3dcff,stroke:#5a3fc0,stroke-width:1.5px,color:#23124d
  classDef static fill:#d7f5e4,stroke:#1f8a4c,stroke-width:1.5px,color:#0f3b22
  classDef datastore fill:#c9f0d3,stroke:#1f8a4c,stroke-width:1.5px,color:#0f3b22
  classDef datafile fill:#dff7d6,stroke:#3d8b1f,stroke-width:1.5px,color:#1f3a12
  classDef external fill:#ffe1c7,stroke:#b45a16,stroke-width:1.5px,color:#4a2206
  classDef tooling fill:#f0d7ff,stroke:#7a2bb6,stroke-width:1.5px,color:#2c0f3f
  classDef admin fill:#ffd6e7,stroke:#b21e5b,stroke-width:1.5px,color:#4a0b25
  classDef edge fill:#e8e8e8,stroke:#666,stroke-width:1.5px,color:#222
```
