How we architect platforms for a five-year horizon

We are repeatedly hired to inherit a platform that was shipped fast, looked good on launch day, and quietly fell apart 18 months later. The first version usually works — the second version is what breaks. Five-year platforms aren’t about writing more careful code; they’re about a small set of architecture decisions that compound. This is the checklist we apply to every greenfield engagement at 802.software.

1. Pick a data model you can explain in one whiteboard

The single biggest predictor of long-term cost is the schema. If the data model requires a senior engineer to draw three diagrams before a new joiner understands it, the codebase will calcify around that complexity. We spend the first week of every discovery argue-ing about the data model in plain English: nouns, verbs, ownership, lifecycle. We write the ERD only after that conversation settles.

Multi-tenancy is the second part of this. Pick row-level isolation or schema isolation up front and never mix the two. Mixed-mode tenancy is the single most expensive migration we are asked to perform.

2. Write the ADR before the code

Every consequential decision gets an Architecture Decision Record: a one-page markdown document with context, the decision, the alternatives we rejected, and the consequences. ADRs are checked into the repository alongside the code they describe. The future maintainer — often us, often the client’s team, sometimes a competitor we’ve been asked to hand off to — gets to see why the choice was made, not just what was chosen.

ADRs do something more important than documentation. They force the team to articulate the tradeoff before the keyboard is hot, which is when the conversation is still cheap.

3. Make the API the contract, not the implementation

The API surface — REST, tRPC, GraphQL, gRPC — is the line that future-you cannot cross without breaking someone. We design that line first, version it from day one, and add contract tests that fail CI the moment a breaking change ships. We have moved platforms from PHP to Go to TypeScript without breaking a single client integration because the API contract was treated as the immovable interface and the implementation was treated as disposable.

4. Plan the migration before the launch

Every platform is mid-migration the moment it ships: dependencies update, infrastructure shifts, regulations move. We design the v1 cutover and the eventual v2 cutover on the same diagram. If we cannot describe how the platform will absorb a database migration, a region failover, and a major framework upgrade without downtime, we change the design until we can.

5. Tests are the only document that doesn’t lie

Documentation drifts. Comments drift. Slack threads drift. Tests do not — they fail in CI the moment the system disagrees with them. We require three layers on every new platform: unit tests for the logic, integration tests against a real database, and contract tests that pin the public API. Coverage thresholds are enforced in CI; the bar is not negotiable.

6. Observability before the first real user

OpenTelemetry, structured logs, request IDs that traverse every service, error budgets defined per surface. The cost of wiring this in before launch is one afternoon. The cost of wiring it in after the first incident is a multi-week rewrite. We do it before launch.

7. The handoff is the deliverable

A platform that only the building team can operate is a liability. Every engagement ends with runbooks, on-call playbooks, decommission paths, and the honest answer to the question “what could break this in eighteen months?” Most of the platforms we’ve shipped are still on retainer with us, which is how we know what holds up — and which decisions we want to make differently next time.

What we don’t do

We don’t add microservices because someone read a Netflix blog post. We don’t adopt Kubernetes for a workload that fits on a single managed container. We don’t pick the latest framework — we pick the one whose maintainers will still be answering issues in 2030. Boring software is the actual five-year strategy.