Repo Topology
Foundry separates three concerns across three repositories. Understanding this split is the key to everything else in the wiki.
The three repos
| Repo | Role | Owns |
|---|---|---|
foundry (+ the manifest) | The brain | The CLI, the manifest schema, and — in a monorepo — the platform's own foundry.json. |
foundry-ops | CI/CD owner & library | The central multi-repo manifest (platform.json), the orchestrator, and the reusable deploy workflow that service repos call. |
foundry-iac | Infrastructure modules | Shared OpenTofu modules and the control-plane stack. Per-service app-edge infra lives in each repo's ci/iac/. |
Manifest is the brain
Everything flows from a manifest. It declares WHAT the platform is — services, stacks, environments, and how each service deploys. In a monorepo that manifest is the repo'sfoundry.json. In a multi-repo platform the authoritative manifest is foundry-ops/platform.json, and individual service repos carry no manifest of their own — only a thin caller workflow.
foundry-ops is the CI/CD owner
Deploy logic lives in one place. A service repo's deploy workflow is a thin caller that invokes foundry-ops's reusable workflow_call workflow. That workflow checks out the caller repo, reads platform.json, and runs the orchestrator. No deploy logic is duplicated across service repos.
foundry-iac holds the modules
Shared infrastructure — VPC, ECS, RDS, ALB, CloudFront, WAF, and more — lives as reusable OpenTofu modules in foundry-iac, alongside the control-plane stack that provisions the always-on platform. Each app's edge infrastructure (its S3 bucket and CloudFront distribution for a static site, for example) lives in that repo's own ci/iac/ stack. See IaC Layout.
Monorepo vs multi-repo
The same manifest model covers both. The difference is two per-service fields:
- Monorepo — omit
repositoryandpath. The service lives at the convention pathapps/{type}/{name}(orpackages/{name}). - Multi-repo — set
repositorytoowner/repoand optionallypath(.= repo root, or a subdirectory). The service lives in its own repository.
Multi-repo is additive — a platform can mix both. Details in Multi-repo: repository & path.
GitHub-only: Foundry's cross-repo discovery and the orchestrated deploy path are built on GitHub (Actions, the GitHub API, and a GitHub App for cross-repo checkout).