General Architecture Principles

The recurring failure mode these principles guard against: each feature designed as its own self-contained unit — its own DTOs, its own endpoint namespace, its own vocabulary — because that is locally clean and low-risk. Each such feature works; the system accretes disjointed, intermixed concepts with diffuse boundaries and a redundant overall model. Design for the system, not the feature.

Model the system, not the feature

• Every design starts from the model the system already has, not from the feature's needs.
• Before introducing any new type, endpoint, projection, or concept: enumerate the existing concepts that overlap it. Reuse or extend is the default.
• A new concept must earn its existence: an explicit, written justification — in the plan, before code — of why no existing concept can carry it. "It keeps the change self-contained" is not a justification; it is the failure mode.
• When an existing concept almost fits, prefer evolving it (and its other consumers) over cloning it. The clone is cheaper today and more expensive every day after.