arch-design

Choose a modular monolith for small teams (2-15 people) with unclear domain boundaries and limited operations capacity. Choose microservices when domain boundaries are confirmed via event storming, multiple teams need autonomy, and independent scaling is required.

An ADR captures Context (the problem and constraints), Decision (what was chosen and alternatives considered), and Consequences (what becomes easier or harder). Use sequential numbering, keep it to one page, and record it immediately when the decision is made.

C4 is a four-layer abstraction: Context for business stakeholders, Container for deployable units and tech stacks, Component for internal modules, and Code for rare detailed cases. Each layer serves a different audience and should never be mixed in one diagram.

Use CQRS when read and write loads are severely asymmetric, queries are complex with multi-dimensional aggregation, and writes need strict transactional consistency. Avoid it for simple CRUD domains or when the team cannot accept eventual consistency between read and write models.

Skip DDD when the system is mostly data entry, reporting, or simple CRUD with little domain behavior, or when no domain experts are available for modeling. A simpler layered design is easier to maintain in those cases.

Use the strangler fig pattern: gradually replace monolith modules with new services behind an API gateway, split the database schema first, and start with the least-coupled modules. Keep old and new systems running in parallel during the transition.