Getting Started
Welcome to the OpsDNA monorepo — the product repository for OpsDNA, an agentic CFO platform initially focused on venture capital firms. This section is for engineers on their first days in the codebase: it gives you the repo tour, the local dev workflow, the bun run verify gate, and the branch-to-prod release flow.
Everything product-shaped lives here: ~120 workspace packages, 7 apps, database migrations, tests, demo scripts, engineering ADRs, and technical docs. The stack is Bun workspaces (pinned bun@1.3.14) + Turborepo, TypeScript throughout, with Effect 4 (beta) as the pervasive runtime abstraction. The backend is an Effect HttpApi surface deployed one-Lambda-per-route on AWS (RDS Postgres 18 behind RDS Proxy); the LP/GP portal is a TanStack Start SSR app on Cloudflare Workers (see docs/architecture-report.md in the repo for the full map).
Why a single monorepo? OpsDNA cares deeply about correctness in fund accounting (ASC 946/820 — see /entity-model for the data-model side), and the repo enforces that with typed package boundaries, Zod-constrained LLM outputs, and roughly forty automated gate scripts that run on every push. Knowing where those gates live and how to run them locally is most of what “onboarding” means here.
The workspace, not just the repo
Your local machine is expected to hold two sibling checkouts, with a symlink connecting them:
The vault gives agents and humans business context without making it part of the product repo. Do not edit context/vault unless explicitly asked — durable engineering decisions belong in this repo (usually as an ADR under docs/adrs/).
Repo tour
- api — Effect HttpApi; each src/entries/*.ts is one deployed Lambda
- portal — LP/GP web app, TanStack Start SSR on Cloudflare Workers
- chat-agent — CF Workers + Durable Objects agent runtime
- mcp — OpsDNA tools over MCP
- acceptance-lab — end-to-end FundScenario close harness (pglite)
- demo / landing-page
- CLAUDE.md / AGENTS.md — agent + engineer working instructions
- DATA-MODEL.md — canonical entity model (read before any schema change)
- DESIGN.md — design system source of truth
Three root documents are load-bearing and non-optional reading before certain kinds of changes: DATA-MODEL.md before any schema/migration/FK decision, DESIGN.md before any UI decision, and CLAUDE.md for the working rules that apply to everyone (human or agent).
Two gotchas bite new engineers on day one. First, bun version shadowing: on some machines /opt/homebrew/bin/bun (1.2.5) shadows the pinned ~/.bun/bin/bun (1.3.14) on PATH, which produces phantom “Cannot find module” walls in fresh worktrees — check which bun and invoke ~/.bun/bin/bun explicitly if in doubt. Second, many packages/*/src dirs contain committed build artifacts (.js/.d.ts); the source of truth is always the .ts files.
Where to next
For the domain itself, continue to /entity-model (the layer cake and identifier policy) and /architecture (runtime and deployment topology).