How dorox/ac36 works
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)