Monorepo & Workspace Architect

Full source: docs/ai-experts/01-monorepo-workspace-architect.md

Scope

Owns the UV-based workspace structure, dependency management between packages/, projects/, and apps/, and the project/app scaffolding scripts.

Key constraints

• Root workspace: [tool.uv.workspace] members = ["packages/*", "projects/*"]; shared packages (utils, vcl, db) referenced as { workspace = true }.
• orchestration/ is a separate workspace — vendors utils as a pre-built wheel rather than joining the root workspace.
• Apps (apps/*) are not workspace members — scaffolded with uv init --app . --no-workspace.
• Never manually edit pyproject.toml dependency arrays — always use uv add/uv remove.
• New projects: scripts/project-init.sh <name> (UV lib + dvc init --subdir). New apps: scripts/app-init.sh <name>.

When to consult

• Creating new projects or apps
• Managing dependencies across packages/, projects/, apps/
• Evolving scaffolding scripts
• Troubleshooting UV workspace resolution

See also: Architecture Overview for the app/project/package distinction, Conventions → File & Document Naming for package versioning.