investor-flow/docs/TECH_DESIGN.md

# Investor Flow — Technical Design (as built)

**Audit date:** 2026-07-23  
**Companion:** [`FUNCTIONAL_DESIGN.md`](./FUNCTIONAL_DESIGN.md)  
**Canonical code roots:** `app/src` (Next frontend), `app/server/src` (Node backend)

---

## 1. Stack

| Layer | Actual technology | Notes vs older docs |
|-------|-------------------|---------------------|
| Frontend | Next.js **16.2**, React **19**, Tailwind **v4**, Recharts, Zustand, Radix UI | Not Bun SPA |
| Backend runtime | **Node ≥22** (dev on Node 26), native TS via `--experimental-strip-types` | DESIGN said Bun; runtime glue is Node + `node:sqlite` |
| API | **tRPC v11** HTTP, path `/api/trpc/*` | Frontend uses hand-rolled fetch client in `app/src/lib/trpc.ts` (not `@trpc/client`) |
| DB | SQLite file (`app/server/data/investor-flow.db`) | Single file multi-tenant |
| Market data | `yahoo-finance2` **v3** class API | |
| SEC | EdgarAdapter + SecFetchAdapter + SecLintAdapter + `secDataFetcher` | Filer CIK from accession prefix (critical fix) |
| Social | XCookieAdapter (encrypted ct0/auth_token), RedditAdapter | |
| Macro | FredAdapter | Key stored admin-side |
| Auth | Sessions + TOTP + OAuth (GitHub/Google) | Password hash via local crypto helpers |
| Tests | `node --test --experimental-strip-types` | Backend ~503 tests; **500 pass, 2 fail, 1 skip** as of audit |
| Deploy | `docker-compose.yml` (frontend + backend + volume) | Present; operator-run |

---

## 2. Process topology

```
Browser (Next :3000)
  │  fetch /api/trpc/<proc>  (credentials include)
  ▼
Next rewrites / proxy  →  Backend (:3001)
  │
  ├─ appRouter (tRPC)
  ├─ CacheRepository + AdapterQueue
  ├─ Source adapters (yfinance, sec-*, x, reddit, fred)
  └─ SQLite
```

- Dev helpers: `restart-servers.sh`, admin `serverRestart`.
- Queue drain loop + 30s schedule loop inside backend process.

---

## 3. Multi-tenant data tiers (still valid)

| Tier | Content | Isolation |
|------|---------|-----------|
| A | quotes, candles, options, filings, institution_filings, insider_tx, sector_map, macro | Shared, no owner |
| B | threads, x_cookie_posts, reddit_posts, adapter_queue*, queue_* | Shared infrastructure |
| C | watchlists, portfolio_holdings, trades, strategies, alerts, theses, emotion_logs, reports, saved filters | `owner_id` / `user_id` |
| D | users, sessions, admin_audit, x_credentials (singleton), llm_* | System |

**Demand set:** `symbol_demand` refcount drives which symbols the queue refreshes.

**Stale-while-revalidate:** CacheRepository returns cached rows and schedules refresh when past TTL.

### 3.1 Rate-limit-first data plane (ADR-0009)

All vendors (Yahoo, X, FRED, SEC, Reddit) have short rate limits. The system is designed so stress yields **stale/static UI**, not stampede:

| Rule | Mechanism |
|------|-----------|
| Request path never stampede | Serve SQLite / `kv_cache` / static fallback first; short timeout if live is unavoidable |
| One outbound owner | `AdapterQueue` only (background drain); UI schedules via `CacheRepository.get` |
| Steady throttle | Per-source min-interval (`sourceRatePolicy.DEFAULT_SOURCE_MIN_INTERVAL_MS`) |
| 429 cool-down | Source-wide pause 2→5→15→30→60 min; skip all jobs for that source; no schedule flood |
| Demand-bounded work | Only `symbol_demand` symbols get scheduled refresh |
| Observability | `queue.health().sourceCooldowns` |

**Anti-patterns (do not reintroduce):** N parallel Yahoo charts on a click; live `quoteSummary` without cache on every panel open; treating 429 as a 2s job retry that keeps hammering the same edge.

Slow-changing composition (ETF top holdings) uses `kv_cache` + `etfHoldingsFallback.ts`. Live upgrade is best-effort when the source is not cooling down.

---

## 4. Backend module map

```
app/server/src/
  index.ts                 HTTP server entry
  trpc/router.ts           ~2k LOC — all routers
  trpc/context.ts          session, cookies, db, cache, queue injection
  db/schema.sql            DDL (note: duplicate strategies blocks — debt)
   db/*Repository.ts        watchlist, portfolio, emotion logs, alertSubscription
  cache/CacheRepository.ts content-addressed cache API
  queue/AdapterQueue.ts    schedule, pause, retry, source cool-downs (ADR-0009)
  queue/sourceRatePolicy.ts 429 detect, cool-down ladders, min-intervals
  adapters/                YFinance, Options, Edgar, SecFetch, SecLint, X, Reddit
  analysis/                indicators, rotation, seasonality, etfHoldingsFallback, tickerContext
  admin/                   operator functions + CLI
  auth/                    totp, oauth, backup codes
   alerts/AlertEngine.ts
   alerts/producers/        types.ts, index.ts (registry), insiderProducer.ts, new13daProducer.ts
   services/emailAlertService.ts  nodemailer SMTP delivery + rate limit
   risk/RiskEngine.ts + haltCircuitBreaker.ts   ← pure; NOT on tRPC
  sizing/SizingEngine.ts + convictionUnlock + twoAxisMatrix  ← pure; NOT on tRPC
  strategy/BacktestEngine.ts
  screener/UniverseEvaluator.ts + SectorCrosslink.ts
  options/ConvexityGate.ts
  derisking/DeriskingEngine.ts
  thesis/ThesisMonitor.ts
  macro/FredAdapter.ts + MacroRegime.ts
  reports/ReportRunner.ts
  onboarding/starter.ts
  services/secDataFetcher.ts
  x/backfill.ts
```

### 4.1 tRPC surface (mounted)

| Router | Procedures (summary) |
|--------|----------------------|
| `auth` | signup, login, logout, me, enable2fa, confirm2fa, oauthStart, oauthCallback |
| `onboarding` | starter, complete |
| `market` | snapshot, candles, indicators, truckSales, manufacturingPmi, rotation, rotationCheckForAlert, sectorHoldings |
| `dashboard` | rollup |
| `admin` | users, sessions, passwords, queue*, lint, data quality, X creds/accounts/prune, FRED key, pending/approve/reject, audit, serverRestart, gdprExport, smtpConfig, smtpConfigUpdate, smtpConfigTest |
| `alerts` | list, acknowledge, acknowledgeAll, unackedCount, createSubscription, listSubscriptions, updateSubscription, deleteSubscription |
| `institutional` | flow, insiderStream, ownershipHistory, buyEvents |
| `edgar` | filings_index, company_facts, filer_cik_meta, full_text_search, form13f_holdings, form4_tx |
| `watchlists` | list, listByWatchlist, listWatchlists, create, delete, rename, reorder, addSymbol, removeSymbol |
| `portfolio` | holdings, addHolding, removeHolding |
| `options` | chain, greeks |
| `reports` | generate |
| `screener` | filter, strategy |
| `strategies` | list, create |
| `backtest` | run, evaluateLatest |
| `sectorCrosslink` | confirm |
| `optionsConvexity` | unlock, getPayoff |
| `derisking` | suggest |
| `macro` | series, calendar, regimeClassify, commentary, regimeHistory |
| `thesisMonitor` | assess, timeline |
| `x` | feed, cashtag_search, timeline, accountsForSymbol |
| `reddit` | subreddit, search |
| `emotionLogger` | add, getByTrade, delete |

### 4.2 Sizing + risk (mounted 2026-07-18)

| Router | Procedures |
|--------|------------|
| `sizing` | `compute` — pure `sizePosition` + portfolio/unlock/halt context |
| `risk` | `posture` — pure `assessRisk` + portfolio load + halt persist; `haltStatus` |

Still deferred: journal create path that throws `HaltedError` when plans are server-persisted (`persist-trade-plan-execution-loop`).

---

## 5. Frontend architecture

```
app/src/
  app/                     Next App Router pages
  components/              Panels + ui kit + layout
  stores/                  Zustand (several persist to localStorage)
  lib/trpc.ts              Partial API client (subset of routers)
  lib/chart-theme.ts       CSS-variable themed Recharts
  lib/strings.ts           Primary-rule sensitive copy
```

### 5.1 Routes

| Path | Role |
|------|------|
| `/` | Workbench overview |
| `/chart-lab` | Charts |
| `/institutional` | Institutional + filings |
| `/filings` | Filings only |
| `/options-dd` | Options DD |
| `/market-outlook` | Macro / rotation / notes |
| `/trade-plan`, `/execution`, `/trade-closure`, `/daily-focus` | Process (local) |
| `/alerts` | Alert events + subscriptions |
| `/settings` | Auth + onboarding |
| `/mobile` | Thin companion |
| `/admin`, `/users`, `/queue`, `/audit-logs`, `/x-accounts`, `/smtp` | Admin |

### 5.2 Client coverage gap

`lib/trpc.ts` exposes: market, edgar, auth, onboarding, watchlists, options, portfolio, dashboard, institutional, emotionLogger, alerts, x, admin.

**Not exposed in client (but on server):** screener, strategies, backtest, sectorCrosslink, optionsConvexity, derisking, macro (except commentary aliased under `market.commentary`), reports, thesisMonitor, reddit, some admin helpers (e.g. gdprExport).

---

## 6. Caching & adapters

| Source kind | Role | Typical freshness |
|-------------|------|-------------------|
| yfinance | quote, candles, sector, options | minutes / EOD |
| sec / sec-fetch | filings, 13F, Form 4 bulk | daily schedule default |
| sec-lint-* | gap detection / backfill | on demand admin |
| x | timelines / cashtags | demand + prune |
| reddit | subreddit/search | on demand |
| fred / macro | series + commentary inputs | slower |
| llm | summaries (tables present) | sparse product use |

**AdapterQueue features (built):** pause/resume, per-job errors with stacks, retry job/source, clear done, schedules, startup in_flight→pending recovery.

---

## 7. AuthZ model

| Gate | Behavior |
|------|----------|
| `publicProcedure` | No session required (many market/edgar/watchlist reads still public — intentional for local demo; tighten later if multi-tenant hardens) |
| `protectedProcedure` | Session + `users.status === 'active'` |
| `adminProcedure` | `is_admin` flag |

Watchlist list currently falls back to `userId ?? 'anonymous'` — convenient for local dev, weak isolation if exposed beyond localhost.

---

## 8. Testing

| Suite | Command | Audit result |
|-------|---------|--------------|
| Backend | `cd app/server && npm test` | **504 pass / 0 fail / 1 skip** (after P0 2026-07-18) |
| Frontend lite | Primary-Rule lint + options pure tests | Present |

Known red: `MacroRegime` commentary tests (`generateMacroCommentary` short/long-term + no macro-trade recommendation).

---

## 9. Schema debt

1. **`strategies` defined twice** in `schema.sql` (legacy `regime_gate/setup/risk_policy` vs `components/unlocked`). SQLite keeps first-created shape depending on migration history — dangerous drift.
2. Parallel filter tables: `screener_filters` vs `saved_filters`.
3. Process tables (`trades`, `trade_executions`, `theses`, `emotion_logs`) exist ahead of UI persistence.

---

## 10. LLM / provenance (as built vs design)

| Designed | As built |
|----------|----------|
| Full LLMGateway with classifyPayload gate | Tables `llm_providers`, `llm_dispatch_audit`, `llm_summaries`; no complete gateway module under `src/` |
| Ornith default `is_local=true` | Env-driven URL in docker-compose (`LLM_PROVIDER_URL`) |
| Sensitive thesis data never leaves host | Thesis content mostly not yet flowing through LLM product paths |

ADR-0006/0008 still govern intent; implementation is incomplete.

---

## 11. Deployment

```bash
# Local dev (typical)
cd app/server && npm run dev   # :3001
cd app && npm run dev          # :3000

# Compose
docker compose up --build
```

Secrets: `.env.example` documents session secret, SEC operator email, X cookie fields, Reddit, FRED, LLM URL.

---

## 12. Documentation map (after this audit)

| Doc | Role |
|-----|------|
| `docs/FUNCTIONAL_DESIGN.md` | What users can do / pending |
| `docs/TECH_DESIGN.md` | This file — how it is built |
| `CONTEXT.md` | Ubiquitous language (glossary only) |
| `docs/adr/*` | Durable decisions |
| Obsidian `investor-flow.md` | Session orientation wiki |

Deprecated as status sources: root `HANDOFF.md` (2026-06-30 orchestrator snapshot), slice DECOMPOSITION checkbox state.