Architecture Judgment

Architecture is where cheap models fail quietly: they produce a plausible design instead of the right-sized one. The failure is almost never "too simple". It is over-engineering, wrong boundaries, or ignoring the operational reality of a small team running everything on one box.

The decision procedure (always)

1. State the actual requirement in one sentence, including scale honestly. "Handles our lead magnets" means hundreds a day, not millions. Design for 10x current need, not 1000x.
2. Generate 2-4 genuinely different options, not one option with three coats of paint. For each: build time, operational burden, failure modes, escape hatch (how hard to migrate off).
3. Pick against a stated priority order. Write yours down before you start. A common one for small teams is build fast, then ship fast, then monetize, where the tiebreaker is "which reaches a working state quickest without cutting quality."
4. Present trade-offs summarized, then implement the chosen one. Do not present a menu and stop. Recommend and proceed.

Pin your own stack first

Before an agent designs anything, give it your locked infrastructure as non-negotiable context: what you run on, what you will never introduce, and which system is the record of truth for each kind of data. Agents default to whatever is fashionable, which is how a one-box project acquires a managed queue nobody asked for.

Keep that list in your own repo, not here. The point is that it exists and that every design references it.

Default choices (boring wins)

A Postgres table used as a queue is not a hack. At small scale it is the correct design: transactional, observable with SQL, and zero new infrastructure.

Boundary-drawing rules

• One writer per datum. If two services write the same table, the design is wrong. Pick an owner, the other calls its API.
• Push at the edges, sync truth in the middle. External surfaces (forms, webhooks, chat integrations) push into one ingestion endpoint. That endpoint owns validation and fan-out. Never let three surfaces each talk to your email provider directly.
• Webhooks: verify, ack fast, process async. Auth-check the caller, write the raw payload to a table, return 200, process from the table. Never do slow work inside the webhook response.
• Idempotency everywhere external systems retry. Dedupe key on a natural pair or the event ID. Design assuming every webhook is delivered twice.
• Fail open on side-effects, fail closed on auth. An email-provider outage must not block a content save (log it, retry later). A missing token must always block a write.

YAGNI tripwires, stop if you catch yourself designing these

• Microservices for a solo or two-person product. It is a monolith until proven otherwise.
• A generic plugin system or rules engine for the second use case. Wait for the third.
• Kafka, Redis, or Kubernetes at small scale. See the defaults table.
• Multi-region, multi-tenant, or white-label "while we're at it." Ship single-tenant, refactor at customer three.
• Config options for behavior nobody asked to vary.

Migration and cutover judgment

• Strangler over big-bang. The new system takes new traffic first, the old system stays read-only until parity is proven.
• Every migration needs a rollback line: "if X breaks, we flip Y back", written down before cutover.
• DNS: drop the TTL a day before cutover, not during.
• Never migrate data and change schema in the same step.

Design doc format (what to produce)

One markdown file. Requirement in one sentence, then options considered (2-4, with a trade-offs table), then the chosen design (diagram-in-text, data model, API surface), then failure modes and mitigations, then what you are explicitly not building, then the cutover and rollback plan if you are replacing something.

If the doc exceeds about two pages, the design is probably too big for the requirement.