# Web Frontend Subsystem Architecture & Documentation Index (`web/`)

Welcome to the **Web Frontend Subsystem Documentation**. This directory contains the single-page application dashboard markup, design system, interactive financial charts, and visual assets for the AI Gold Quant Engine.

---

## 🗺️ Web Subsystem Architecture & File Map

```mermaid
graph TD
    Launcher[gui_launcher.py / Embedded Browser] --> Web[web/index.html / index_v2.html]
    Web --> Server[observability/health.py: HTTP API on :9100]
    
    Server --> D1[GET /api/data: Live Metrics]
    Server --> D2[GET /api/chart: Candlestick & S/R Data]
    Server --> D3[GET /api/journal: AI Lessons Feed]
    Server --> D4[GET /api/audit: Forensic Trade Ledger]
    Server --> C1[POST /api/config: Parameter Hot-Reload]
    Server --> C2[POST /api/reset: Kill-Switch Override]
```

---

## 📂 File Directory Breakdown

| File Name | File Type | Role & Description |
| :--- | :--- | :--- |
| **`index.html`** | Standalone SPA HTML5 | Primary client dashboard interface with embedded CSS, JS, and Lightweight Charts. |
| **`index_v2.html`** | Standalone SPA HTML5 | Production release mirrored version of the dashboard with WebView2 flexbox guards. |
| **`Logo.png`** | Brand Image Asset | High-resolution Trading Cafe vector logo displayed on the dashboard header. |
| **`dashboard_architecture.md`** | Technical Spec | [Detailed Architectural Specification](dashboard_architecture.md) covering UI components, Lightweight Charts, and REST API interfaces. |

---

## 🛠️ Key Technical Guardrails

1. **WebView2 Flexbox Height Collapse Guard:** Uses strict modern flex layouts (`flex: 1; min-height: 0; height: 100%;`) to prevent container collapse on older Windows Server / VPS environments.
2. **Lightweight Charts Timestamp Shift:** Employs dynamic 1-second timestamp offset shifting for concurrent ticks to prevent chart rendering crashes.
3. **Responsive Mobile PWA Viewport:** Switches from fixed desktop sidebar to touch-optimized bottom navigation bar on screens $\le 900	ext{px}$.

---

## 🔗 Routing — When You Change Something Here

- **`index.html` and `index_v2.html` are both generated output — do not hand-edit them directly.** Both
  files are written by `build_html.py`'s `build()` from a single embedded `html_template` string, and
  `gui_launcher.py` calls `build_html.build()` at every startup — any direct edit to either `.html` file
  is silently overwritten on next launch. **The actual source to edit is `build_html.py`.** See
  `build_html.md` Routing.
- **The dashboard has no manual BUY/SELL/BOTH direction control** — only a read-only `dir-guard-label`
  showing the AI's current AUTO-driven bias. The dead `setDirection()` JS function and the
  nonexistent-button class-toggle code were removed from `build_html.py`'s template (and consequently
  from both generated `.html` files); direction is intentionally AI/AUTO-only (see `orchestrator.md`
  Routing). A handful of now-unused `.dir-btn-active-*` CSS rules remain in the template — harmless,
  since nothing sets those classes anymore.
- **Every `/api/*` call in this file must have a matching handler in `observability/health.py`** — adding
  a new dashboard feature that calls a new endpoint requires both sides to change together.

---
*Memory Rule Maintained: Web Subsystem Documentation Synchronized Across Workspaces.*
