# dorox/ac36 architecture

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

- Interactive diagram: https://gitdiagram.com/dorox/ac36
- Repository: https://github.com/dorox/ac36

## Overview

##### Project type and purpose
- This is a full-stack Python web application (“AC36 statistics web app”) deployed on Heroku.
- It provides two sub-applications:
1. A “map” service for visualizing race data on an interactive map.
2. A “stats_app” service for displaying race statistics, augmented by Bokeh plots served via a standalone Bokeh server process (`bokeh_serve.py`).

##### File structure
- Top-level files:
- `.gitignore`, `requirements.txt`, `runtime.txt` – Heroku deployment config.
- `Procfile` – declares two dynos: one for the Flask web app(s) and one for Bokeh server.
- `bokeh_serve.py` – spins up a Bokeh server for interactive charts.
- Two parallel Flask apps under directories:
- `map/` – `main.py` (Flask app controller), `templates/` (Jinja2 HTML), `static/` (JS, CSS).
- `stats_app/` – `main.py`, `templates/`.
- No local database; data is fetched at runtime from external JSON/BIN feeds (AmericasCup.com, CloudFront).

##### README for additional insights
- Confirms data sources (race-ids.json, race data binaries, JSON stats endpoints).
- Mentions external services: YouTube feed, Virtual EYE, AC dashboard.

##### Main components
a. Client Browser (Web UI)
- Loads static assets (HTML, JS from `/map/static`, chart JS).
- Interacts via HTTP(S) with the Flask web app and directly with the Bokeh server’s WebSocket endpoint for live plots.
b. Heroku Router
- Routes incoming traffic to either the Web Dyno or the Bokeh Dyno based on URL (e.g., `/bokeh` path to Bokeh server).
c. Web Dyno (Flask)
- Hosts both `map/main.py` and `stats_app/main.py` (mounted on different URL prefixes).
- Renders templates, serves static files, orchestrates data fetch from external APIs.
d. Bokeh Dyno (bokeh_serve.py)
- Serves interactive charts over WebSocket; receives data updates pushed by Flask or scheduled callbacks.
e. External Data Providers (AmericasCup.com, CloudFront, YouTube)
- JSON/BIN race data feeds, YouTube embeds, Virtual EYE streams.

##### Relationships & interactions
1. Browser → Heroku Router (HTTP GET /map or /stats)
2. Router → Web Dyno (Flask) → fetch external JSON/BIN → render Jinja2 templates → HTTP response to browser
3. Browser loads frontend JS (e.g., map logic) which may fetch additional endpoints on Web Dyno or talk directly to External APIs
4. Browser ↔ Bokeh Dyno (WebSocket) for live chart updates

##### Architectural patterns & design principles
- Micro-services style: two Flask sub-apps + separate plotting service
- MVC pattern in each Flask app:
- Model: dynamic external data fetch modules
- View: Jinja2 templates + static JS
- Controller: `main.py` route handlers
- Separation of concerns:
- Presentation layer (templates/static) vs. application logic vs. data sources vs. plotting engine

##### Technologies & frameworks
- Python 3.x, Flask, Jinja2, Bokeh
- Heroku (Procfile, runtime.txt)
- JavaScript (Leaflet or similar in `map/static`, BokehJS)
- External REST/BIN APIs

##### Final checklist
- Components: Browser, Heroku Router, Web Dyno (Map + Stats apps), Bokeh Dyno, External APIs
- Data flows: HTTP GET/POST, WebSocket
- Labels: service names, ports or paths (e.g., `/map`, `/stats`, `/bokeh`)
- Notes on key frameworks (Flask, Bokeh, Jinja2, JS libraries)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Client Browser"]:::frontend
    Router["Heroku Router"]:::backend

    subgraph "Web Dyno (Flask)"
        MapApp["Flask Map App"]:::backend
        MapTempl["Map Templates"]:::frontend
        MapStatic["Map Static Assets"]:::frontend
        StatsApp["Flask Stats App"]:::backend
        StatsTempl["Stats Templates"]:::frontend
    end

    Bokeh["Bokeh Server"]:::backend

    subgraph "External Data Providers"
        Feed1["AmericasCup JSON/BIN"]:::external
        Feed2["CloudFront Data"]:::external
        YouTube["YouTube Embed"]:::external
        VirtualEye["Virtual EYE Streams"]:::external
    end

    Browser -->|"HTTP GET /map, /stats"| Router
    Router --> MapApp
    Router --> StatsApp

    MapApp --> MapTempl
    MapApp --> MapStatic
    StatsApp --> StatsTempl

    MapApp -->|"fetch JSON/BIN"| Feed1
    MapApp -->|"fetch JSON/BIN"| Feed2
    StatsApp -->|"fetch JSON/BIN"| Feed1
    StatsApp -->|"fetch JSON/BIN"| Feed2

    Browser -->|"WebSocket /bokeh"| Bokeh
    MapApp -->|"POST data"| Bokeh
    StatsApp -->|"POST data"| Bokeh

    click MapApp "https://github.com/dorox/ac36/blob/master/map/main.py"
    click MapTempl "https://github.com/dorox/ac36/tree/master/map/templates/"
    click MapStatic "https://github.com/dorox/ac36/tree/master/map/static/"
    click StatsApp "https://github.com/dorox/ac36/blob/master/stats_app/main.py"
    click StatsTempl "https://github.com/dorox/ac36/tree/master/stats_app/templates/"
    click Bokeh "https://github.com/dorox/ac36/blob/master/bokeh_serve.py"
    click Router "https://github.com/dorox/ac36/tree/master/Procfile"
    click Router "https://github.com/dorox/ac36/blob/master/runtime.txt"
    click Router "https://github.com/dorox/ac36/blob/master/requirements.txt"
    click Feed1 "https://github.com/dorox/ac36/blob/master/README.md"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFD580,stroke:#333,stroke-width:1px
```
