Architecture
The system, part by part
I keep Bullpen’s shape in the repo, as decisions, rules and a model of what runs. Every tab below reads those records, so what you see is what is written down. Scrub through the series to watch it change.
Who owns the data
Overview · Part 3Built
What runs at the end of Part 3: a Market Data service beside the trading app in one Vercel project, and one Neon database with a schema and role per owner. Week one predicted two services with two databases; the build kept one owner per transaction instead.
SynchronousAsynchronousExternal
Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.
Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.
Watch it travel through the current part's nodes, step by step.
Part 3 nodes and connections
- Reader (actor): A blog reader exploring Bullpen's architecture timeline on the landing site.
- Player (actor): Sees live crypto and end-of-day stock prices and the leaderboard. Accounts and orders arrive in Part 4.
- Daily ingest cron (infra): Vercel's scheduler: once a day after the U.S. close it calls the Market Data service's ingest, with a secret. Decisions: ADR-0004 Deploy topology: Vercel Services in one project, ADR-0013 One Market Data owner.
- Bullpen Landing (app): The public landing site with the architecture timeline explorer. Decisions: ADR-0003 Monorepo, ADR-0006 React Flow for the architecture explorer, ADR-0009 Guardrails are enforced, not requested.
- Bullpen Trading App (app): The trading app. It owns orders, the ledger, positions and the leaderboard view in the trading schema, and shows end-of-day stock prices read through prices_v1. Decisions: ADR-0001 Stack, ADR-0003 Monorepo, ADR-0012 One database, a schema and a role per transactional owner, ADR-0014 The leaderboard as a materialized view.
- Market Data Service (service): Replaces the Price Snapshot Service: the CoinGecko price route moved into it. It owns both providers and both call budgets, and is the only writer of the market_data schema. A boundary in one release, not an independently deployed microservice. Decisions: ADR-0004 Deploy topology: Vercel Services in one project, ADR-0013 One Market Data owner.
- CoinGecko (ext): Crypto prices. Called only by the Market Data service, inside a monthly call budget, with the key in a header. Decisions: ADR-0005 Crypto prices from CoinGecko.
- Alpha Vantage (ext): U.S. stock prices, end of day, one request per symbol, fetched once a day by the Market Data service inside a daily call budget. Decisions: ADR-0008 U.S. stock prices from Alpha Vantage, end of day.
- Google Analytics 4 (ext): Page views and a short list of events, only after the visitor accepts. Decisions: ADR-0010 Product analytics with Google Analytics 4 and Microsoft Clarity, behind consent.
- Microsoft Clarity (ext): Heatmaps and session recordings, only after the visitor accepts. Decisions: ADR-0010 Product analytics with Google Analytics 4 and Microsoft Clarity, behind consent.
- trading schema (data): Accounts, orders, the ledger, positions and the leaderboard view. Orders and the ledger are written in one transaction. Decisions: ADR-0012 One database, a schema and a role per transactional owner.
- market_data schema (data): Quotes, the provider call ledger, and the view prices_v1. Decisions: ADR-0012 One database, a schema and a role per transactional owner, ADR-0013 One Market Data owner.
- market_data.prices_v1 (data): The price contract: symbol, price, as-of time, source and a stale flag. The only thing outside market_data that trading may read. Decisions: ADR-0012 One database, a schema and a role per transactional owner.
- Bullpen Database (data): One Neon project and one database, with a schema and a plain role per owner. Decisions: ADR-0012 One database, a schema and a role per transactional owner, ADR-0014 The leaderboard as a materialized view.
- Reader → Bullpen Landing (sync)
- Player → Bullpen Trading App (sync)
- Daily ingest cron → Market Data Service (async)
- Bullpen Landing → Market Data Service (sync)
- Bullpen Trading App → Market Data Service (sync)
- Market Data Service → CoinGecko (sync)
- Market Data Service → Alpha Vantage (sync)
- Bullpen Trading App → trading schema (sync)
- Bullpen Trading App → market_data.prices_v1 (sync)
- Market Data Service → market_data schema (sync)
- Bullpen Landing → Google Analytics 4 (async)
- Bullpen Landing → Microsoft Clarity (async)
- Bullpen Trading App → Google Analytics 4 (async)
- Bullpen Trading App → Microsoft Clarity (async)