Appearance
IIP Documentation Index
Technical documentation for the Integration Platform (IIP) — a service-oriented, event-driven integration middleware built around Kafka, a fixed canonical envelope wrapping runtime-defined schema contracts, and pluggable idempotent adapters.
The platform keeps its
iip-prefix and its intern use case, but it is no longer intern-specific. Interns is contract #1, not the schema: new schemas are registry rows and new fan-out targets are adapter attachments, neither requiring a build or a redeploy. See 06 — Generalization Strategy for why, and what it deliberately does not try to be.
These docs describe the full platform, not just an MVP slice. This is a solo project — one developer building everything the original design brief described, including what it labeled "Phase 2" — that work is simply sequenced into later releases (see the implementation plan), not cut from scope. Development follows Extreme Programming (XP), adapted to a single-developer context (see Implementation Plan §1): small continuously-integrated releases ordered by value and dependency, not by fixed dates or hour estimates — so none of these documents contain a schedule.
Documents
| Doc | Contents |
|---|---|
| 00 — Original Specification | The source design brief, preserved as authored, for historical context. Single-schema by design — superseded, not edited. |
| 01 — Architecture | System context (C4-L1), containers (C4-L2), key components (C4-L3), data-flow sequence diagrams, topic/partitioning design, both deployment topologies, tech stack, and the twelve architectural decisions with rationale. |
| 02 — Use Cases | Actors, use case diagram, and 15 detailed use cases (UC-1 … UC-15) covering intake, fan-out, failure recovery, DLQ handling, contract definition, adapter attachment, monitoring, and DLQ replay — each tagged with the release it belongs to. |
| 03 — Data Model | The fixed canonical envelope and per-contract payloads, contract definitions and the registry schema, the DLQ envelope, target storage models (generic landing table, PostgreSQL ERD, CSV format), and evolution/compatibility rules at both levels. |
| 04 — Implementation Plan | XP-based release roadmap (Releases 1–9, re-sequenced) covering the entire system, backlog with acceptance criteria per story, cross-release engineering practices, Definition of Done, and a risk register. |
| 05 — Phased Rollout | Each release broken into small, sequential, checkbox-tracked implementation phases — the working execution checklist for actually building the system, one commit-sized step at a time. |
| 06 — Generalization Strategy | Why and how the platform generalized from one fixed schema to a registry of contracts: the two deployment paths, the envelope/payload split, the landing-table trade-off, the re-sequenced roadmap, and the doc-by-doc migration that produced 01–05 in their current form. |
Reading order
- New to the project? Read them in numeric order: 00 → 01 → 02 → 03 → 04.
- Wondering why it isn't intern-specific any more? Start at 06 — it's the argument, with the alternatives that were rejected.
- Reviewing the architecture specifically? 01, then 03 for the contract details.
- Actually building something right now? Go straight to 05 and pick up the next unchecked phase.
How these docs stay accurate
Every capability described in 01–03 is tagged with the release (from 04) that introduces it, so as the platform grows past the MVP these documents don't need a rewrite — only incremental updates as each release lands. Per the Definition of Done, every story checks whether it changes architecture, a use case, or the data model enough to require a docs diff. Doc 05 is the exception — it's a living checklist, expected to change every time a phase lands.
Where documents disagree: 01–05 are the current contract. 00 is preserved history and is deliberately not updated. 06 is the rationale record behind the current contract — the reasoning that produced it, not a competing specification.