Freezing service boundaries before the demo platform gets ideas

Overview

Box is a small “business in a box” platform built around contract-first service boundaries and scenario overlays. It generalizes part of the household-platform work into a deliberately smaller test: can a reusable business kernel support different scenarios without turning into one application with decorative service names?

The repository fixes the initial boundaries early because demo pressure is excellent at inventing shared databases, private imports, and simulator shortcuts. Those choices make a demo move quickly and make the architecture meaningless. Box starts with the interfaces instead.

System shape

The initial kernel contains party-service, catalog-service, and transaction-service. Each has a service manifest, an OpenAPI contract, an event schema, and example payloads under its own contract directory. The hotdog-stand and it-consultancy scenario packs provide seeds and policies without changing that kernel.

Local Python tooling is provided to validate service contracts and scenario content. A Compose file defines the local Postgres and NATS dependency stack, while the Terraform, Talos, and Flux trees reserve the intended deployment boundaries. They are scaffolding, not evidence of a deployed platform.

Current state

The source review on 12 October 2026 checked the repository README and tree. They still present the Phase 0 scaffold: architecture decisions, staged requirements, three initial service contracts, two scenario packs, validation tooling, and tests. Reference services, a simulator, and a working deployment path remain listed as subsequent implementation steps.

This review did not execute the validator, pytest, or a deployment. The 13 July 2026 version of this page recorded passing local document and schema validation; that is historical evidence, not a new October test result. The verification date above applies to the narrower repository-scope assessment.

The useful distinction remains the same: coherent definitions do not establish that the proposed platform works under load or survives a service replacement. This is a contract-first architectural scaffold, not an operated reference platform.

Open edges

The next meaningful proof is an end-to-end slice through the three reference services using service-owned persistence and contract-valid events. After that, the deterministic simulator has to generate both scenario packs without writing around the public interfaces.

The stronger test comes later: replace one service with another implementation while callers and scenarios remain unchanged. Until that works, “contract first” is a design constraint with validation tooling, not replacement proof.