Architecture
The applications and packages in this repository, what each one does today, and where the unbuilt agent surfaces are meant to land
This page maps the repository as it stands. Where a part of the design has no code yet, it says so rather than describing the intended file as though it existed.
OPB Brain is a Bun and Turborepo monorepo. The root workspace covers
apps/* and packages/*; bun@1.3.10 is pinned as the package manager.
Applications
Each application is self-contained and does not import another application. Each carries an env.ts
at its root that composes the keys() function of every package it depends on, so a missing
required variable fails that application's build rather than surfacing at runtime.
| Application | Port | What it is today |
|---|---|---|
apps/app | 3000 | The authenticated product shell. Clerk sign-in and sign-up, a search page, a webhooks page. No entity views yet. |
apps/web | 3001 | The marketing site. No database access and no auth. |
apps/api | 3002 | A health check, a keep-alive cron route, and the Clerk and Stripe webhook receivers. |
apps/email | 3003 | React Email preview server for the templates in packages/email. Local only. |
apps/studio | 3005 | Prisma Studio against the schema in packages/database. Local only. |
apps/storybook | 6006 | Component workshop for packages/design-system. |
apps/docs | 3004 | A Mintlify project inherited from the template this repository forked. Superseded by the site you are reading. |
The documentation site is not in apps/. It is a separate Next.js project at docs/ in the
repository root, with its own bun.lock and no workspace membership. It is installed and built from
its own directory.
Where the agent surfaces are meant to go
None of these exist. They are listed here so the map is honest about its own gaps.
| Planned surface | Intended home | Page |
|---|---|---|
MCP server at /mcp | apps/api | MCP |
REST API at /api/v1 | apps/api | REST |
GraphQL at /graphql | apps/api/graphql | GraphQL |
Entity views, .md views, data-testid selectors | apps/app | Browser |
| The domain tables | packages/database | Concepts |
packages/database currently holds one stub model inherited from the template. Nothing in
the domain model has a table.
Packages
Twenty shared packages, all published under the @repo/* namespace and all private to the
repository. A package exports everything an application needs from it — middleware, hooks,
components, and its own environment variable schema.
| Package | Covers |
|---|---|
@repo/ai | AI SDK wiring. No documentation page yet. |
@repo/analytics | PostHog and web analytics |
@repo/auth | Clerk authentication |
@repo/cms | BaseHub content |
@repo/collaboration | Liveblocks presence |
@repo/database | Cloudflare D1 |
@repo/design-system | The Quiet Instrument design system |
@repo/email | Resend and React Email |
@repo/feature-flags | Feature flags |
@repo/internationalization | Dictionaries and locale routing |
@repo/next-config | Shared Next.js configuration |
@repo/notifications | Knock in-app notifications |
@repo/observability | Sentry and BetterStack |
@repo/payments | Stripe |
@repo/rate-limit | Cloudflare KV rate limiting |
@repo/security | Arcjet and security headers |
@repo/seo | Metadata, JSON-LD and sitemaps |
@repo/storage | Cloudflare R2 |
@repo/typescript-config | The shared tsconfig bases. No documentation page. |
@repo/webhooks | Svix outbound webhooks |
Several of these are wired but not configured — the integration is present and skips itself when its environment variables are absent. Each package page says which state it is in.
Boundaries
Turborepo boundaries enforce that a package only reaches for what it declares. Violations are caught by:
bun run boundariesAn application depends on packages. A package does not depend on an application, and does not reach into another package's internals.
Repository-wide guards
Four suites run at the repository root, outside any workspace, under vitest run __tests__:
| Suite | Holds |
|---|---|
no-upstream-references | No file outside a named allowlist mentions the upstream template. The allowlist is a shrinking scoreboard, and a stale entry fails the suite. |
docs-links | Every internal /docs/... link, every related: entry, and every meta.json entry resolves to a page that exists. |
docs-llms-index | Every documentation page appears in /llms.txt exactly once. |
root-identity | The repository root identifies as OPB Brain. |
locale-parity | Every locale dictionary carries the same keys. |
turbo test runs the workspace suites; the root test script runs both.
Specifications
spec/ at the repository root is the ground truth these documentation pages are written from.
| File | Subject |
|---|---|
spec/00-product-vision.md | What the product is and is not |
spec/01-domain-model.md | Entities, the task state machine, leasing, invariants |
spec/02-agent-interfaces.md | The four doors and the write-back contract |
spec/03-agent-experience.md | The eight rules a surface has to satisfy |
Where a page here and a file there disagree, the spec is right and the page is a bug.