Skip to content

ADR-001: Monorepo Structure

Status

Accepted

Date

2025-12-01

Context

Z-City ecosystem has 33 services, 16 apps, 6 packages, and 106 AI agents. Managing these across separate repositories creates dependency hell, inconsistent tooling, and slow cross-service changes.

Decision

Use a single monorepo (pnpm workspace) with the following structure:

  • services/ — backend microservices
  • apps/ — frontend applications
  • packages/ — shared libraries
  • .claude/agents/ — AI agent definitions
  • .tz/ — technical specifications
  • infrastructure/ — Terraform, K8s manifests
  • ci-templates/ — reusable CI/CD templates

Consequences

  • Easier cross-service refactoring and atomic changes
  • Single CI/CD pipeline with path-based triggers
  • Shared tooling and consistent developer experience
  • Requires careful management of build times and caching