Skip to main content

ADR 001: Monorepo with Nx Orchestration

  • Status: Accepted
  • Date: 2026-03-07
  • Deciders: Project owner

Context​

GospeLib is a polyglot project with Go backend services, Python data/AI services, and TypeScript frontend applications. We needed to choose between a monorepo (all code in one repository) and a polyrepo (separate repositories per service/app) approach.

Decision​

Use a single monorepo with:

  • Nx for workspace orchestration, affected computation, and caching
  • pnpm workspaces for JavaScript/TypeScript packages and apps
  • Independent Go modules per service (standard Go module layout)
  • Python projects managed by uv per service (pyproject.toml + virtual envs)

Consequences​

Positive​

  • Atomic commits across service boundaries
  • Shared CI pipeline with Nx affected for efficient builds
  • Single source of truth for types, configs, and shared packages
  • Easier cross-cutting refactors
  • Unified developer tooling and onboarding

Negative​

  • Larger repository size (mitigated by Nx affected and sparse checkouts)
  • Requires Nx knowledge for workspace operations
  • Build system complexity (pnpm + Go modules + uv in one repo)

Neutral​

  • Go and Python services are decoupled from the JS workspace graph
  • Each service maintains its own dependency management