# connor050-htw/accessible-map architecture

> Architecture diagram of the GitHub repository connor050-htw/accessible-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/connor050-htw/accessible-map
- Repository: https://github.com/connor050-htw/accessible-map

## Overview

##### Project type and purpose
- This is a full-stack web application with
- A rich, accessible Leaflet-based frontend (JavaScript, CSS, GeoJSON, plugins)
- A FastAPI Python backend (“map-to-speech-demo/api/”) that receives screenshots, forwards them to a local Vision-Language model (Ollama), and returns text/audio descriptions

##### File structure
- Top-level frontend folders:
- index.html, data.js, data/, images/
- src/ (modular JS code: core, controls, features, layers, ui, utils)
- plugins/ (Leaflet plugins: fullscreen, pinsearch)
- styles/ (base.css, components/, main.css)
- Separate demo app under map-to-speech-demo/app/ (static files)
- Backend under map-to-speech-demo/api/ with main.py (FastAPI), requirements.txt

##### Key components
a. Frontend (Browser/Client)
– Static resources served by a web server or file system:
- HTML (index.html)
- CSS (styles/)
- JS modules (src/, data.js)
- GeoJSON data (data/austriancastles.geojson)
- Plugins (plugins/)
– Map UI layers (tile server endpoints via Mapbox/OpenStreetMap)
– Controls & Features modules (3D, LOD, settings, compass, sidebar, accessibility)
– html2canvas integration for screenshot capture
– Web Speech API for TTS

b. Backend (FastAPI service)
– Endpoint POST /description/
– Reads JSON payload (data_url, speed, voice, etc.)
– Attempts /api/generate on Ollama, falls back to /api/chat
– Returns JSON { text_data, audio_data }

c. External Service (Ollama Vision-Language Model)
– Local host (default http://127.0.0.1:11434)
– Qwen-VL model (e.g., qwen3-vl:4b)

d. (Optional) Static file server
– Serves frontend assets and data/ folder

##### Relationships & data flows
1. User interact GUI → frontend code (Leaflet + custom modules)
2. “Get Description” button → html2canvas captures map viewport → base64 PNG
3. Frontend POSTs JSON to FastAPI `/description/`
4. FastAPI → HTTP call to Ollama `/api/generate` or `/api/chat`
5. Ollama returns text (and/or audio) → FastAPI wraps into JSON → sends back
6. Frontend receives response → updates UI, triggers browser speech synthesis

##### Architectural patterns & design principles
- Modular frontend: clear separation into core, controls, features, layers, UI, utils
- Single responsibility: each JS module handles one feature or control
- RESTful microservice: lightweight FastAPI backend for a single purpose
- External service integration: decouple business logic (description generation) into Ollama

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Tier (Browser)"
        direction TB
        A_html["index.html"]:::frontend
        A_data["data.js"]:::frontend
        A_geo["austriancastles.geojson"]:::frontend
        A_images["images/"]:::frontend
        subgraph "Core Modules"
            direction TB
            A_map["map.js"]:::frontend
            A_config["config.js"]:::frontend
        end
        subgraph "Controls"
            direction TB
            A_ai["ai-description.js"]:::frontend
            A_compass["compass.js"]:::frontend
        end
        subgraph "Features"
            direction TB
            A_3d["3d-mode.js"]:::frontend
            A_lod["lod-control.js"]:::frontend
            A_settings["settings.js"]:::frontend
        end
        subgraph "Layers"
            direction TB
            A_3dbuild["3d-buildings.js"]:::frontend
            A_basemap["basemaps.js"]:::frontend
            A_poi["poi-markers.js"]:::frontend
        end
        subgraph "UI Modules"
            direction TB
            A_sidebar["sidebar.js"]:::frontend
            A_access["accessibility.js"]:::frontend
            A_keys["shortcuts.js"]:::frontend
        end
        subgraph "Utilities"
            direction TB
            A_dom["dom-helpers.js"]:::frontend
            A_capture["map-capture.js"]:::frontend
        end
        subgraph "Plugins"
            direction TB
            A_full["FullScreen Plugin"]:::frontend
            A_pin["PinSearch Plugin"]:::frontend
        end
        subgraph "Styles"
            direction TB
            A_baseCSS["base.css"]:::frontend
            A_mainCSS["main.css"]:::frontend
            A_compCSS["components/"]:::frontend
        end
    end

    subgraph "Service Tier (FastAPI)"
        direction TB
        B_main["main.py (POST /description/)"]:::backend
        B_req["requirements.txt"]:::backend
    end

    subgraph "External Tier"
        direction TB
        C_ollama["Ollama VLM (qwen3-vl)"]:::external
        C_tiles["Tile Providers (Mapbox/OSM)"]:::external
    end

    %% Data Flows
    A_basemap -->|"Tile HTTP(S)"| C_tiles
    A_3dbuild -->|"Tile HTTP(S)"| C_tiles
    A_poi -->|"Tile HTTP(S)"| C_tiles
    A_ai -->|"POST /description/"| B_main
    B_main -->|"HTTP /api/generate or /api/chat"| C_ollama
    C_ollama -->|"text/audio JSON"| B_main
    B_main -->|"JSON {text_data,audio_data}"| A_ai

    %% Click Events
    click A_html "https://github.com/connor050-htw/accessible-map/blob/main/index.html"
    click A_data "https://github.com/connor050-htw/accessible-map/blob/main/data.js"
    click A_geo "https://github.com/connor050-htw/accessible-map/blob/main/data/austriancastles.geojson"
    click A_images "https://github.com/connor050-htw/accessible-map/tree/main/images/"
    click A_map "https://github.com/connor050-htw/accessible-map/blob/main/src/core/map.js"
    click A_config "https://github.com/connor050-htw/accessible-map/blob/main/src/core/config.js"
    click A_ai "https://github.com/connor050-htw/accessible-map/blob/main/src/controls/ai-description.js"
    click A_compass "https://github.com/connor050-htw/accessible-map/blob/main/src/controls/compass.js"
    click A_3d "https://github.com/connor050-htw/accessible-map/blob/main/src/features/3d-mode.js"
    click A_lod "https://github.com/connor050-htw/accessible-map/blob/main/src/features/lod-control.js"
    click A_settings "https://github.com/connor050-htw/accessible-map/blob/main/src/features/settings.js"
    click A_3dbuild "https://github.com/connor050-htw/accessible-map/blob/main/src/layers/3d-buildings.js"
    click A_basemap "https://github.com/connor050-htw/accessible-map/blob/main/src/layers/basemaps.js"
    click A_poi "https://github.com/connor050-htw/accessible-map/blob/main/src/layers/poi-markers.js"
    click A_sidebar "https://github.com/connor050-htw/accessible-map/blob/main/src/ui/sidebar.js"
    click A_access "https://github.com/connor050-htw/accessible-map/blob/main/src/ui/accessibility.js"
    click A_keys "https://github.com/connor050-htw/accessible-map/blob/main/src/ui/shortcuts.js"
    click A_dom "https://github.com/connor050-htw/accessible-map/blob/main/src/utils/dom-helpers.js"
    click A_capture "https://github.com/connor050-htw/accessible-map/blob/main/src/utils/map-capture.js"
    click A_full "https://github.com/connor050-htw/accessible-map/tree/main/plugins/fullscreen/"
    click A_pin "https://github.com/connor050-htw/accessible-map/tree/main/plugins/pinsearch/"
    click A_baseCSS "https://github.com/connor050-htw/accessible-map/blob/main/styles/base.css"
    click A_mainCSS "https://github.com/connor050-htw/accessible-map/blob/main/styles/main.css"
    click A_compCSS "https://github.com/connor050-htw/accessible-map/tree/main/styles/components/"
    click B_main "https://github.com/connor050-htw/accessible-map/blob/main/map-to-speech-demo/api/main.py"
    click B_req "https://github.com/connor050-htw/accessible-map/blob/main/map-to-speech-demo/api/requirements.txt"

    %% Styles
    classDef frontend fill:#D6E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D2F8D2,stroke:#333,stroke-width:1px
    classDef external fill:#FFE4B5,stroke:#333,stroke-width:1px
    class A_html,A_data,A_geo,A_images,A_map,A_config,A_ai,A_compass,A_3d,A_lod,A_settings,A_3dbuild,A_basemap,A_poi,A_sidebar,A_access,A_keys,A_dom,A_capture,A_full,A_pin,A_baseCSS,A_mainCSS,A_compCSS frontend
    class B_main,B_req backend
    class C_ollama,C_tiles external
```
