Integration Rules
These rules are mandatory for all code review and development work involving multi-component systems.
Vertical Slice Principle
Every task MUST deliver a thin, working end-to-end path:
| Good (Vertical Slice) | Bad (Horizontal Layer) | |------------------------|------------------------| | "User can send message" (UI + API + LLM + response display) | "Create all database tables" | | "Display product list" (API call + domain filter + UI render) | "Build all API endpoints" | | "Process payment" (UI form + gateway + order update) | "Create all UI components" |
Walking Skeleton
The FIRST deliverable of any multi-component feature must be a walking skeleton:
- One request flows through ALL layers
- Returns real data (not hardcoded/mocked)
- Proves the architecture connects end-to-end
- Does NOT need to be feature-complete — just connected
Contract-First Development
When two components will communicate:
| Step | Action | Artifact | |------|--------|----------| | 1 | Define interface before implementation | TypeScript interface, OpenAPI schema, or protobuf | | 2 | Both sides code against the contract | Import shared types or generated clients | | 3 | Contract test validates both sides | Test that producer output matches consumer expectation |
Integration Test Requirements
| Boundary | Required Test |
|----------|---------------|
| HTTP API endpoint | Request with real HTTP client, validate response shape + status |
| Database operation | Testcontainers with real queries, validate data persisted |
| Message queue | Real producer + consumer, validate message delivered |
| External service | Test Double with // Test Double rationale: (only exception) |
| In-process module boundary | Real function call, validate input/output contract |
Orphan Detection
Code without a live entry point is dead-on-arrival.
Valid entry points (at least one required per new module):
- HTTP/WebSocket handler
- CLI command handler
- Event/message listener
- Scheduled job/cron handler
- Exported function called by a module that has an entry point
Detection: Trace from new code upward — if no path reaches an entry point, the code is an orphan.
Detection Checklist
When reviewing code, flag:
- New module/service without any caller (orphan code)
- Task structured as horizontal layer instead of vertical slice
- Two components communicating without shared interface/contract
- New boundary crossing without integration test
- Use case with DB/API dependency but only unit tests
- Component "works in isolation" but not wired to any entry point
- Interface defined but no contract test validating compatibility