Architecture: Write It Down Before Rewriting
Part of the "How to bring order to a project" series — the architecture track. Same context: a growing gamedev project, about twenty services on different stacks, an architecture that "grew historically." Nobody designed it badly — nobody designed it at all: services appeared as needs arose, boundaries were drawn by circumstance, decisions lived in chats and heads. That's a normal phase — up to a…
Part of a series on bringing order to game development projects that have grown historically, without a formal design. Rather than rewriting the architecture, the approach is to document it. Services are given passports with key information: their purpose, boundaries, stack, status, owner, and deployment details. This documentation helps surface questions like "why is this even here?" and clarifies responsibilities, turning vague concerns into concrete tasks.
The service passports become a registry of all services, including their stack, status, and owners. A call graph outlines which services interact with each other, providing a text-based map of dependencies. Boundaries are explicitly defined, specifying what each service is responsible for, what is adjacent but owned by someone else, and how other services can interact with it.
Documenting these boundaries first, before writing any code, helps avoid overlaps and ensures new features are integrated in a controlled manner. Two types of written decisions are maintained: RFCs (requests for comments) for proposed changes, and ADRs (architecture decision records) for documented decisions. RFCs cover the problem, options, decision, and cost, while ADRs provide a record of past decisions and reasoning.
Both are reviewed, approved, and implemented in the same merge request to ensure consistency and catch mismatches early.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
