Architecture & Concepts

Foundry runs as a four-process distributed system in local development and deploys to three managed platforms in production. The architecture is designed around one central idea: delivery knowledge (requirements, skills, workstreams, risks) is the moat, and AI agents consume that knowledge to turn plans into working software.

This section covers the structural decisions behind the platform — how data flows, where AI executes, and why each layer exists.

Section map

System Overview Four-process architecture, dual-mode design, provider hierarchy, and key design decisions.

Data Model 81 tables across 10 domains, entity hierarchy, row-level security, and indexing strategy.

Convex Layer Queries, mutations, actions, HTTP actions — the reactive backend that powers everything.

Background Jobs Scheduler patterns, webhook processing, retry logic, and cron jobs.

Agent System Three AI services, three-tier model deployment, context assembly, and prompt caching.

Key principles

• No traditional API layer for data. Convex queries and mutations are called directly from React via useQuery/useMutation. All data is automatically reactive.
• Row-level security on everything. Every tenant-scoped query and mutation calls assertOrgAccess(). No exceptions except health checks.
• Index-driven queries only. Every Convex query uses .withIndex(). The .filter() method causes full table scans and is banned in production paths.
• AI is a delivery participant, not an assistant. Agents ingest project artifacts, extract requirements, decompose tasks, write code in sandboxes, push branches, and submit PRs.