Engineering Partner Onboarding

1. System architecture

Rendered diagram

Local asset: assets/system-architecture.svg

Flow (text)

Clients (Browser → CF Access → Stripe)
        │
        ▼
Cloudflare Pages (react-app-dist/ + _worker.js)
        │  proxy /timed/*
        ▼
timed-trading-ingest (worker/) — ALL /timed/* · DOs · fallback crons
        │
   ┌────┼────────────────────┐
   ▼    ▼                    ▼
tt-feed  tt-engine       tt-research   (same bundle, role-gated)
   │         │                │
   └────┬────┴────────────────┘
        ▼
   D1 + KV (+ PriceStream WS → TwelveData; PriceHub → Browser)

tt-broker-bridge (worker-bridge/) ← /timed/broker/* session owner
        │
   Alpaca / IBKR / Webull / Robinhood / E*TRADE scaffold

External: TwelveData · Discord · SendGrid / OpenAI · Stripe

Component cheat sheet

2. Newcomer material (summary)

The full day-1 / first-week guide lives in the newcomer guide. It covers:

• Repo map (worker/, role dirs, react-app, skills, tasks)
• Topology table and cutover / binding-parity rules
• Local run, .dev.vars, Pages vs worker proxy
• Auth tiers in brief
• Price invariants in brief
• Skills index pointers + house rules + first-week checklist

Reading path for a new senior engineer:

AGENTS.md → CONTEXT.md (Stack/Deploy) → skills/README.md → skills/worker-topology.md → skills/deploy.md → this pack’s architecture section.

3. Deploy topology (partner-facing)

CI workflows (path-filtered): deploy-worker.yml, deploy-feed.yml, deploy-engine.yml, deploy-research.yml.

A merge is not a deploy. Verify Cloudflare version dates or /timed/health deployedSha. Stamp ENGINE_GIT_SHA on hand deploys. Details: skills/deploy.md.

4. Auth, tiers, security boundaries

Entitlements

Server gate: canAccessLivePrices() / redactTickerMapForTier(). UI: window._ttIsPro. Canonical states: skills/user-state-matrix.md.

Route / trust boundaries

Full patterns: skills/security-auth-patterns.md. Broker tenant isolation: skills/partner-onboarding.md.

Discord / Stripe / Access (placement)

• Discord: outbound alerts from the main worker (and related crons); debug via skills/discord-alerts.md.
• Stripe: Checkout + webhooks on the main worker; VIP code grants and billing reconciliation have dedicated helpers — see skills/billing-and-sales-tax.md.
• CF Access: gates authenticated HTML; User Pages policy regex must list every authenticated page (CONTEXT notes this).

5. Price pipeline invariants (pointer sheet)

Do not re-implement. Read .cursor/rules/price-data-pipeline.mdc and CONTEXT lessons tagged PriceStream / q_ts.

Non-negotiables for a partner touching feed or UI prices:

1. TwelveData primary; parse native quote change fields (parseTdQuote).
2. Client daily change only via getDailyChange(t) in shared-price-utils.js.
3. Every timed:prices writer stamps q_ts + p_ts and never regresses them.
4. Freshness / health use value stamps, not blob t.
5. PriceStream DO ownership of symbols in timed:prices (orphan clobber risk under KV lag).
6. Session-aware EXT fields: no AH writes during RTH; preserve closed-session day/EXT appropriately.
7. Licensing footer: “Market data powered by Twelve Data”.

6. Skills index (common tasks)

Complete list: skills/README.md.

7. Partner onboarding checklist

Use this when an engineering partner joins (code access). For a broker-mirror product partner, use skills/partner-onboarding.md instead (different isolation model).

Access & tooling

• Repo read/write (or PR) access; Cloudflare visibility as needed (Workers, Pages, D1, KV) — operator grants; do not invent IAM
• Local Node 22 + npm install; wrangler via ./node_modules/.bin/wrangler
• Understanding that Cloud VMs may lack CF Access browser login — API key path for local API work
• Secrets never committed: worker/.dev.vars, bridge secrets, Stripe / TwelveData / Discord tokens

Engineering ramp

• Completed newcomer guide Day 1–5 checklist
• Can name the five Worker scripts and what Pages serves
• Can explain Pages vs Worker deploy independence
• Can explain Member vs Pro vs VIP vs Admin for price/score gating
• Knows where to find skills before inventing a procedure

First production-adjacent change

• Touches the correct deploy surface(s) per skills/deploy.md
• Runs bash scripts/check-branch-merge-state.sh before pushing an existing branch
• Verifies live behavior (health / route string / UI), not only green CI
• Updates lessons/CONTEXT if the operator corrects an assumption

Security review before self-serve prod writes

• No unguarded mutating /timed/* routes
• No browser→bridge shortcuts; no owner taken from client input on broker routes
• No licensed data leaked to Member/anon caches
• No emoji in commits/PRs; no “you/your” in user-facing product copy

8. Files in this pack

Changelog

• 2026-09-29 — Initial pack; newcomer guide split out as front door per founder priority.
• 2026-09-29 — Responsive HTML conversion under docs/web/.