Wiring Every Service Together: the Target Integration Plan

Why a Capstone Needs Integration Truth

A backend architecture is not proved by isolated lessons. It becomes real only when the services start from cold state, discover one another correctly, receive configuration through the intended channels, and process at least one representative business flow end to end. Integration testing therefore asks a different question from unit testing: not 'does this function behave correctly in isolation?' but 'does the system behave coherently when all moving parts are alive at the same time?'

For Meridian, the capstone must stay honest about the present. The current repository is still a scaffold: every service builds and exposes only /healthz. The capstone chapter therefore defines the target integration test plan that should become real as business handlers are added. That future plan is still valuable because it teaches the sequencing and contracts required for a production-grade bring-up.

Current vs Target State

The System Bring-Up Plan

A good bring-up plan is ordered. Infrastructure must come before services that depend on it. Schema or seed steps must happen before write paths are exercised. The gateway should come last among application processes because it depends on downstream route targets. A reporting consumer, once built, should come after the transactional services and the event transport. This is a general systems lesson: cold-start order is part of architecture, not an afterthought.

Request and Event Flows

The first meaningful integrated flow should stay representative but simple: a tenant-scoped request enters through gateway, the gateway resolves or propagates tenant identity, one downstream service writes authoritative state, and the resulting success is observable at the HTTP layer. A second flow should verify cross-service behavior, such as gateway calling identity-service for membership checks before community-service accepts a resident mutation. A third, future flow should prove asynchronous propagation into reporting-service once that module exists. This staged approach teaches a key backend principle: integration breadth should increase as the system actually grows, not by inventing fake complexity on day one.

Planned Artifacts

Verification Sequence

• Start PostgreSQL, Redis, and any event transport before the application services that depend on them.
• Start identity-service, community-service, and billing-service before gateway so the gateway's downstream URLs resolve to healthy targets.
• Verify each /healthz endpoint individually, then verify a gateway-routed request that reaches a downstream service.
• Add tenant-scoped write-path verification before introducing asynchronous reporting flows.
• Introduce reporting-service only after transactional services emit stable events worth aggregating.