An AI product often contains a web app, API, model gateway, asynchronous workers, agent tools, shared schemas and evaluation code. A monorepo keeps those parts in one versioned workspace so a contract change can be reviewed and tested together.

That benefit is real, but a monorepo is not automatically simpler. Without ownership and task boundaries, humans and coding agents can make unnecessarily broad changes. This guide focuses on that trade-off within AI application architecture.

A practical AI monorepo

apps/
  web/                 # user interface
  api/                 # product API and authentication
  model-gateway/       # provider adapters, routing and budgets
workers/
  ingestion/           # document parsing and embeddings
  agents/              # durable agent jobs
packages/
  schemas/              # runtime schemas and shared types
  prompts/              # versioned prompt definitions
  tools/                # tool contracts and clients
  observability/        # logging and tracing helpers
evals/
  datasets/
  scorers/
  regression/
infra/
  containers/
  deployment/

Organise by deployable responsibility first. A generic shared package easily becomes a dependency dumping ground.

When a monorepo helps

A monorepo is useful when changes frequently cross boundaries:

• a tool schema changes with its server and agent client;
• a streaming event changes across gateway, API and frontend;
• a prompt update needs matching evaluation fixtures;
• one deployment must coordinate a worker and database migration;
• coding agents need the complete contract to implement a feature safely.

Atomic pull requests make these changes visible together. Shared CI can run only the affected projects while still enforcing repository-wide policies.

When separate repositories are better

Use separate repositories when components have genuinely independent ownership, release cycles or access requirements. A model-evaluation dataset containing restricted data may not belong beside a public SDK. Infrastructure managed by a separate platform team may require its own permissions.

Do not choose a monorepo solely because a framework makes one easy to create. If every change touches one application, the extra orchestration may provide little value.

Shared schemas, not shared assumptions

Runtime schemas are among the highest-value shared packages in an AI system. They can define:

• model gateway events;
• tool inputs and outputs;
• asynchronous job states;
• API contracts;
• evaluation result records.

Version deployable services so an old worker can coexist briefly with a new API. A shared TypeScript type does not make independently deployed processes update simultaneously. See TypeScript for AI applications.

Prompts and evaluations

Keep prompts versioned and reviewable, but avoid importing raw prompt files everywhere. Expose a small package or registry that records prompt identity and version.

Evaluation datasets should identify provenance, licence and sensitive fields. Do not let every package read production examples merely because they share a repository.

CI should run focused evaluations when prompts, model routing, tool schemas or retrieval logic change. The GitHub Actions foundation covers that pipeline.

Coding agents in a monorepo

Monorepos give agents valuable context and a larger blast radius. Define scope explicitly:

• assign a package or set of paths;
• use worktrees for concurrent tasks;
• require a diff summary outside the intended scope;
• prevent secrets and generated data from entering context;
• require owners for security, billing and infrastructure paths.

Repository instructions should specify build commands and boundaries close to the relevant package. One enormous instruction file is likely to be ignored or become stale.

Follow Git workflows for coding agents for isolation and review.

Dependency boundaries

Enforce a direction such as:

apps/workers → domain packages → schemas/utilities

The model gateway should not import frontend code. Evaluation tooling should exercise public contracts rather than reach into application internals. Circular package dependencies make independent deployment and agent reasoning harder.

Use workspace tooling to detect cycles and undeclared imports. Cache builds by inputs, but invalidate caches when schemas, prompts or generated clients change.

Deployment

A monorepo does not imply one deployment. Build immutable artefacts per service and deploy only affected units. Record the same commit SHA across them so an incident can reconstruct the complete source state.

Coordinate incompatible contract or migration changes with staged rollouts:

1. deploy backward-compatible storage or API changes;
2. deploy consumers;
3. migrate traffic or jobs;
4. remove old compatibility only after observation.

The AI operations hub covers the runtime side.

Decision checklist

Choose a monorepo when:

• teams frequently change shared contracts together;
• unified review and CI reduce integration risk;
• access controls can still protect sensitive areas;
• tooling can build and test affected projects efficiently.

Avoid it when:

• repositories have legally or operationally distinct access;
• releases are fully independent and shared code is minimal;
• repository size makes every workflow slow;
• ownership boundaries exist only on paper.

For AI products, a monorepo is most valuable as a contract and evaluation workspace. It should make cross-system changes safer—not give every developer or agent unrestricted access to everything.