Backend Architecture: Multi-Service Decomposition.

You're decomposing an eight-year-old monolith into a set of independently deployable services for a distribution business in the Colon Free Trade Zone in Panama. The monolith works until it doesn't: a fix to shipping breaks invoicing, a warehouse update locks a table the customs service needs. The customs integration with the national authority cannot go down during the transition.

The discipline skills: service boundary design as the highest-consequence decision in a distributed system, multi-environment infrastructure with cost guardrails and a documented lifecycle, threat modeling and data flow diagrams as design tools, and a deployment strategy that picks blue-green for the regulated service and rolling updates for everything else. The contracts between services become the spine of the work.

The AI-direction lesson: directing AI becomes orchestration. Claude Code carries subdirectory CLAUDE.md rules per service (loaded via the ancestor-hierarchy walk-up). Codex CLI runs as an MCP server on a second service in parallel. The GitHub Copilot coding agent takes a precisely-specified service via an issue handoff. You are no longer steering AI turn by turn — you are designing how AI work composes. A shared contract document keeps independently-produced services compatible. You decide what goes synchronous, what goes async, and where each kind of verification belongs.

Your Role

You're the senior engineer planning the architecture and leading the first services. The client's six-person IT team will own the system after the engagement — so the work is the services plus the architecture documents, threat model, cost projection, and orchestration plan they will inherit and extend.

You own the seams. Inside any one service, AI builds. At the boundaries between services, environments, trust zones, and agents, you decide. The client understands microservices intellectually but has not done a decomposition before. Every major decision needs a written justification someone else could defend.

What's New

Last time you owned a frontend, performance, verification, and observability architecture as a coherent whole under a hard satellite-internet constraint. You wrote ADRs before any prompt and held one codebase coherent across Claude Code and Codex CLI.

Three things change.

The boundaries are the architecture. P12 was one application across four columns. P13 is multiple services, multiple environments, multiple deployment strategies. The hardest decisions are not inside any service — they are at the seams.

Multi-agent work goes from one codebase to many. Two services built in parallel by two different agents, a third delegated async via an issue. The contract document is the spine. Composition is its own verification problem — each piece can pass and the system still fail at the seam.

Restraint moves to architecture itself. AI proposes Kubernetes, service meshes, and orchestrated sagas for any multi-service system. Most do not fit a six-person team's operational capacity. The judgment this project builds is matching the architecture to the team, not to the technical ambition of its builders.

Tools

• Node.js + TypeScript, Express or Hono (per-service framework — you decide), PostgreSQL per-service plus an event store or message bus — continuing, new topology.
• Docker + docker-compose — new. Local multi-service development.
• OpenAPI and AsyncAPI — new. Inter-service contract documents.
• Terraform extended to dev/staging/production, AWS or Azure (you decide), GitHub Actions for per-service CI/CD and blue-green orchestration — continuing.
• Microsoft Threat Modelling Tool or OWASP Threat Dragon, OWASP ZAP in CI — new.
• k6, OpenTelemetry, Grafana, Prometheus, Loki, Tempo, VS Code, Git + GitHub — continuing.
• Claude Code with subdirectory CLAUDE.md files layered into context via the ancestor-hierarchy walk-up (services/<svc>/CLAUDE.md, contracts/CLAUDE.md), and hooks at all four tiers of the spectrum (deterministic, external-service, fast-model, deep-agent — all configured as type: command) — new as a deliberate design space.
• Codex CLI as MCP server — continuing from P12, used per-service.
• GitHub Copilot coding agent — new. Async delegation via issue assignment.

Materials

• Forwarded email chain — how the project starts. The CFO writes to the client with the budget and constraints; he forwards it on with a note about the legacy monolith and the customs API.
• Legacy monolith reference — eight years of accreted code across all five domains. Enough to read and decompose, not to fix in place.
• Operational logs — three months of where the monolith actually breaks. The decomposition plan must be evidence-based.
• DGA customs API spec, multi-currency invoicing notes, bonded warehouse rules — the regulated and operational constraints. Discovered through conversation, not handed over.
• CLAUDE.md template — a root-level project memory skeleton for the multi-service scaffolding. You populate it and author per-service rules underneath.
• Hook tier reference — the four-tier spectrum (deterministic, external-service, fast-model, deep-agent — all type: command) you use to decide which tier fits which lifecycle event, plus working reference scripts and a .claude/settings.json that wires them.
• Empty ADR, contracts, and threat-model directories — you author ADRs 0001-0007, OpenAPI per service plus AsyncAPI for events, and a STRIDE walkthrough, data flow diagram, OWASP review, and AI-specific security audit.