'UI Shell and General Architecture'

1 files changed, 39 insertions, 0 deletions

diff --git a/AGENTS.md b/AGENTS.md
index f3503e1..96532df 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,6 +56,45 @@ This checkout has no existing commit history. Use concise, imperative commit sub
 
 Pull requests should include a short summary, test results (`pytest`, `npm run lint`, `npm run build` when relevant), linked issues if applicable, and screenshots or screen recordings for visible UI changes. Note any required environment variables such as `FMP_API_KEY` or `FINNHUB_API_KEY`.
 
+## Design System (`design-system/`)
+
+The repo includes a full personal-brand design system at `design-system/`. All frontend work must follow it — never invent colors, radii, or type choices.
+
+**Token entry point:** `design-system/colors_and_type.css` (also mirrored into `frontend/public/design-system/` for serving). Import it for all new components; it declares every CSS custom property: ink surfaces, fg tints, brass/champagne accent, oxford navy, burgundy, semantic gain/loss/caution/info colors, spacing scale, radii, shadows, and font stacks.
+
+**Typefaces:**
+- `--font-serif` — EB Garamond (variable). Display + body serif; italic at large sizes is the signature move.
+- `--font-sans` — IBM Plex Sans. UI labels, eyebrows, buttons, badges.
+- `--font-mono` — IBM Plex Mono. All prices, percentages, and tabular numerics (`font-variant-numeric: tabular-nums`).
+
+**Visual rules that must not be broken:**
+- Background is `#0B0E13` (ink-0), never pure black. Text is `#F2ECDC` (fg-0), never pure white.
+- Primary accent is champagne `#C2AA7A` — for links, focus rings, eyebrows, button fills. Never as a large background fill.
+- Semantic colors: gain `#4F8C5E`, loss `#B5494B`, caution `#C49545`, info `#4A78B5`.
+- Card radius is 6px; buttons are 2px. No radius above 6px except capsule chips (999px). No bubbly rounding.
+- Hairline `1px` borders only (`#232934`). No gradients except the chart area fill. No glass effects.
+- Transitions are 150ms ease. No bounces, springs, or scroll-jacking.
+- No emoji — ever. Use SVG icons from `design-system/assets/icons/` or unicode geometrics (`▲ ▼ ◈ ✦ ↗ ·`).
+
+**Prism UI kit:** `design-system/ui_kits/prism/` is a forward-looking redesign showing the target component shapes: `<Sidebar>`, `<TopBar>`, `<TickerHeader>`, `<KPIStrip>`, `<ChartCard>`, `<QuoteTable>`, `<ValuationPanel>`, `<FilingsList>`, `<InsiderRow>`. Read `parts{1,2,3}.jsx` and `prism.css` before building new dashboard surfaces.
+
+## Reference: Prism v1 (`../prism`)
+
+The old Streamlit-based app at `../prism` is the canonical reference for finance logic being ported into v2. Do not import from it at runtime, but read it when implementing new financial features.
+
+Key source files to consult:
+
+- **`services/data_service.py`** — yfinance wrappers for price history, financials (income/balance/cash flow), options chain, insider transactions, SEC filings, market indices, and analyst targets. Contains `compute_ttm_ratios()` which self-computes P/E, P/B, P/S, EV/EBITDA, margins, ROE/ROA/ROIC, leverage ratios, and dividend metrics from raw quarterly statements (avoiding FMP quota). Includes outlier safeguards (e.g. P/B and EV/Sales capped at 100).
+- **`services/valuation_service.py`** — DCF engine (`run_dcf()`) using Gordon Growth Model: projects FCF with median historical growth (capped ±50%, skips sign flips), computes terminal value, bridges enterprise value to equity per share via net debt/preferred equity/minority interest. Also has `run_ev_ebitda()`, `run_ev_revenue()`, `run_price_to_book()`.
+- **`services/fmp_service.py`** — FMP REST calls for peers, forward analyst estimates, historical ratios, and news. Falls back to yfinance when FMP is unavailable.
+- **`services/news_service.py`** — Finnhub sentiment wrapper.
+- **`components/overview.py`** — signal badge logic (6 signals), 52-week range bar, short interest rendering.
+- **`utils/formatters.py`** — number formatting helpers (market cap abbreviations, percent display, etc.).
+
+**Caching strategy in v1:** `@st.cache_data` with staggered TTLs — financials at 1 h, indices at 5 min, search at 60 s. Mirror these TTLs when adding new cached endpoints in v2's `data_service.py`.
+
+**Data source hierarchy in v1:** yfinance primary → FMP fallback → Finnhub for news/sentiment. FMP free tier is 250 req/day; `FMP_API_KEY` and `FINNHUB_API_KEY` are set via `.env`.
+
 ## Security & Configuration Tips
 
 Do not commit API keys, local virtual environments, `node_modules/`, or generated SQLite data files. Optional market-data keys should be provided through the environment or a local `.env` file.