Software architecture

C4Container
  title Containers: invoicing app
  Person(user, "Freelancer")
  System_Ext(stripe, "Stripe", "Card payments")
  System_Boundary(app, "Invoicing app") {
    Container(web, "Web app", "Next.js", "UI")
    Container(api, "API", "Bun", "Use cases")
    ContainerDb(db, "Database", "PostgreSQL")
  }
  Rel(user, web, "Uses", "HTTPS")
  Rel(web, api, "Calls", "JSON/HTTPS")
  Rel(api, db, "Reads and writes", "SQL")
  Rel(api, stripe, "Charges cards", "HTTPS")

<context>
I'm [your role, e.g. the technical cofounder] at
[organization, e.g. a 3-person B2B SaaS startup]. We are
building [system, e.g. invoicing for freelancers:
clients, invoices, card payments, reminders, tax export].
Where it stands:
[stage: greenfield | prototype | in production].
I'm not an architect. The proposal will be read by
[readers, e.g. 2 developers and a non-technical cofounder].
</context>
 
<task>
Interview me before designing anything. The end
result will be an architecture proposal (candidate
architectures, a recommendation recorded as ADRs, C4
diagrams); first you need its architecture drivers.
</task>
 
<requirements>
- At most 10 questions, grouped under: business goals and
  key use cases; quality attributes (use the ISO/IEC 25010
  characteristics); constraints; team and operations; scale
  and growth; existing systems and decisions already made.
- For each question: one line on how the answer changes the
  architecture, and 2–3 typical answers I can pick from.
- No architecture, patterns or technologies yet.
</requirements>
 
<quality_bar>
Before answering, check your questions against:
- Each answer could change a structural
  decision; drop any question that couldn't.
- Quality questions ask for a number (a
  response measure), not an adjective.
- Nothing I already told you is asked again.
</quality_bar>
 
<output_format>
Numbered questions under the
group headings, and nothing else.
</output_format>
 
<process>
Ask all the questions in one message, then stop. When I
answer, restate the drivers as three lists (use cases;
ranked quality attributes as scenarios with response
measures; constraints), mark anything still open [NEEDS
SOURCE], and end with a list of the assumptions you made.
</process>

<materials>
[paste the drivers from stage 1, with my answers]
</materials>
 
<context>
Team: [team, e.g. 3 developers, no dedicated
ops, one on-call rotation]. Time horizon:
[horizon: prototype | MVP | 5+ year platform].
</context>
 
<task>
Candidate architectures for this system, so I can
choose one before anything is drawn or written up.
</task>
 
<requirements>
- 2–4 materially different candidates; one must
  be the simplest workable option (a modular
  monolith or plain layers). Candidates that
  differ only in technology names don't count.
- For each: one paragraph, the modules or services, how it
  meets each top quality attribute, the operating load for
  this team, and which decisions would be hard to reverse.
- Use ATAM vocabulary: sensitivity points,
  trade-off points, risks and non-risks.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every component serves a numbered driver.
- Each candidate names what it makes
  worse, not only what it improves.
- The trade-off table scores every
  candidate on every top quality attribute.
- The recommendation names the assumption
  that, if wrong, would flip it.
</quality_bar>
 
<output_format>
One section per candidate; a trade-off table
(candidate | each top quality attribute, scored +, 0
or - with a reason | operating load | hard-to-reverse
decisions); a recommendation in under 100 words.
</output_format>
 
<process>
End with a list of the assumptions you made. Then stop and
wait for my choice: no ADRs, diagrams or module tables yet.
</process>

<materials>
[paste the agreed drivers from stage 1]
[paste the chosen candidate and
the trade-off table from stage 2]
[paste existing ADRs, the folder tree
or the integration list, if any]
</materials>
 
<context>
[product and team, e.g. B2B invoicing for freelancers,
built by 3 developers with no ops]. The readers: [readers,
e.g. the other 2 developers and a non-technical cofounder].
We chose [candidate, e.g. candidate 1, the
modular monolith] because [reason, e.g. the
lowest operating load for a team with no ops].
</context>
 
<task>
The architecture proposal for the chosen candidate:
the document the team approves and then builds from.
</task>
 
<requirements>
- Name qualities with their ISO/IEC 25010
  characteristics; write the top 3 as quality
  attribute scenarios with response measures.
- C4 model: a system context and a
  container diagram, one level each, in
  [notation: Mermaid | PlantUML | Structurizr DSL | D2];
  every arrow labeled with intent and
  protocol; technology on every container.
- Each hard-to-reverse decision as an ADR in
  [ADR format: MADR | Nygard], status Proposed,
  with at least 2 negative consequences.
- Modules by business capability; each owns
  its data and exposes a public API;
  dependencies point inward, with no cycles.
- Risks and non-risks in ATAM
  style, each tied to a decision.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every component and ADR traces to a numbered driver.
- The diagrams, the module table and the
  prose name the same parts, with no extras.
- No module reads or writes another module's tables.
- The operating load fits the team in <context>.
- Each fitness function would fail
  CI when its rule is broken.
</quality_bar>
 
<output_format>
Markdown, under [length, e.g. 4 pages], in these
sections: summary (5 lines); drivers; architecture
overview; C4 diagrams; module table (module |
responsibility | data owned | public API | depends on);
ADRs; quality scenarios and how the design meets each;
risks and non-risks; fitness functions; open questions.
</output_format>
 
<process>
Ask me up to 3 questions first if anything
missing would change your answer; otherwise go
on. End with a list of the assumptions you made.
</process>

<materials>
<proposal>
[paste the architecture proposal]
</proposal>
<drivers>
[paste the agreed drivers]
</drivers>
</materials>
 
<context>
This is a fresh chat: you did not write this proposal.
It goes to [reviewers, e.g. the two developers who
will build it] for approval [when, e.g. on Friday].
</context>
 
<task>
An ATAM-style review of the proposal before it is
approved: what would make it miss its quality goals.
</task>
 
<requirements>
- A short utility tree: quality attributes, then scenarios,
  each rated H/M/L for importance and difficulty.
- For the 5 highest-rated scenarios: how the
  design responds, with its sensitivity points,
  trade-off points, risks and non-risks.
- Score the proposal 1–5 on: traceability,
  measurable qualities, trade-offs, alternatives,
  boundaries, dependencies, fit to team,
  reversibility, risks, diagrams, enforcement.
- Do not rewrite the proposal and do not praise it.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your review against:
- Every problem cites the section,
  diagram or ADR it comes from.
- Problems are ranked by the business
  goal they threaten, worst first.
- You compared the diagrams with the module
  table, and the ADRs with the drivers.
- If you found fewer than 5 problems,
  you say which checks came back clean.
</quality_bar>
 
<output_format>
The utility tree; a scenario table (scenario | design
response | sensitivity points | trade-off points |
risks | non-risks); the scorecard; the ranked fixes
(problem | evidence | fix | effort S, M or L).
</output_format>
 
<process>
End with a list of the assumptions you made.
</process>

Turn these requirements into quality attribute scenarios
(source, stimulus, environment, artifact, response, response
measure), named by ISO/IEC 25010 characteristic: [paste
requirements]. Check that every response measure is a number
a test could check, and mark each number as mine to confirm.

<materials>
[paste the requirements, user stories or meeting notes]
</materials>
 
<context>
[system, e.g. B2B invoicing for freelancers], built by
[team, e.g. 3 developers]. Expected load: [scale, e.g.
2,000 customers in year 1, 50 requests/s at peak].
</context>
 
<task>
Quality attribute scenarios for the
qualities these requirements imply, so we
can rank them and design against the top 3.
</task>
 
<requirements>
- The six-part form: source, stimulus, environment,
  artifact, response, response measure.
- Name each quality by its ISO/IEC 25010 characteristic and
  subcharacteristic, e.g. maintainability › modifiability.
- 2 scenarios for each of the top 5 qualities: one
  in normal operation, one under stress or failure.
- Mark every number you propose
  "(proposed)", for me to confirm.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every response measure is a number with a
  unit that a test or a dashboard could check.
- No scenario restates a feature; each describes a quality.
- The ranking follows my requirements, not a generic order.
</quality_bar>
 
<output_format>
A table: quality (ISO/IEC 25010) | source | stimulus |
environment | artifact | response | response measure.
Then the top 3, ranked, one line each on why.
</output_format>
 
<process>
Ask me up to 3 questions first if anything
missing would change your answer; otherwise go
on. End with a list of the assumptions you made.
</process>

Write ADR-[number, e.g. 0004] in [ADR format: MADR | Nygard]
for: [decision, e.g. one Postgres with a schema per module].
Include 2+ negative consequences and a "revisit if" line.
Check each rejected option has a real reason; mark missing
facts [NEEDS SOURCE].

<materials>
[paste the discussion notes, the
trade-off table and any related ADRs]
</materials>
 
<context>
Our ADRs live in [location, e.g. docs/adr/ in
the repo] and are read by [readers, e.g. the
current developers and whoever joins next year].
</context>
 
<task>
ADR-[number, e.g. 0004] recording this decision: [decision,
e.g. one PostgreSQL database with a schema per module].
</task>
 
<requirements>
- Template: [ADR format: MADR | Nygard]. MADR
  sections: decision drivers, considered options,
  pros and cons of each, confirmation. Nygard
  sections: context, decision, consequences.
- Status: [status: Proposed | Accepted]. If it replaces
  an earlier ADR, say which one it supersedes.
- At least 2 positive and 2 negative consequences, and a
  "revisit if" line naming a condition we could observe.
- One decision only; under one page.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- The context states the forces, not the conclusion.
- Each rejected option has a real reason, not a straw man.
- The negative consequences are the ones
  a skeptic on the team would raise.
- Someone joining next year could tell from
  it whether the decision still holds.
</quality_bar>
 
<output_format>
Markdown in the chosen template, titled with
the number and the decision in under 10 words.
</output_format>
 
<process>
End with a list of the assumptions you made.
</process>

From this description, draw C4 system context and
container diagrams in Mermaid (C4Context, C4Container):
[paste description]. Label every Rel with intent and
protocol, put technology on every container, and check
nothing appears that the description doesn't mention;
list what you couldn't place.

<materials>
[paste the architecture description,
module table or proposal]
</materials>
 
<context>
The diagrams go in [where, e.g. the repo README
and the onboarding doc], read by [readers, e.g.
new developers and a non-technical cofounder].
</context>
 
<task>
C4 diagrams of this system, as
text we can render, diff and edit.
</task>
 
<requirements>
- Levels:
  [C4 levels: system context | container | component],
  one level per diagram.
- Notation:
  [notation: Mermaid | PlantUML | Structurizr DSL | D2].
- A title and scope on every diagram; every
  arrow labeled with intent and protocol;
  technology on every container and data store.
- Draw only elements the description mentions.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every element and arrow is in the description,
  and everything in the description is placed.
- No diagram mixes C4 levels.
- The syntax uses only features the notation has
  (Mermaid's C4 support is narrower than C4-PlantUML's).
</quality_bar>
 
<output_format>
One fenced code block per diagram; then anything you could
not place; then a 3-line legend for non-technical readers.
</output_format>
 
<process>
End with a list of the assumptions you made.
</process>

Here are our folder tree and module dependency graph:
[paste tree and graph]. Infer the business capabilities,
propose target modules (responsibility, data owned,
public API), list the cycles, and give an incremental
plan. Check every step leaves the app shippable.

<materials>
<tree>
[paste the folder tree]
</tree>
<graph>
[paste the dependency graph, e.g.
from dependency-cruiser or madge]
</graph>
</materials>
 
<context>
Pain points: [pain points, e.g. slow builds,
every change touches 5 folders, brittle tests].
Team: [team, e.g. 4 developers, weekly releases].
</context>
 
<task>
A target module decomposition for this
codebase and an incremental plan to reach it.
</task>
 
<requirements>
- Modules by business capability, not technical
  layer; each owns its data and exposes a public API.
- List the dependency cycles and
  the 10 most depended-on files.
- Steps that each leave the app shippable, using
  [method: branch by abstraction | strangler fig].
- One fitness function per step that
  fails CI if the step regresses.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every file in the tree lands in exactly one module.
- Every cross-module call in the
  target goes through a public API.
- No step needs a code freeze or a big-bang merge.
</quality_bar>
 
<output_format>
The capabilities; a module table (module |
responsibility | data owned | public API | depends
on); cycles and hotspots; the step plan (step |
what moves | fitness function | rollback).
</output_format>
 
<process>
Ask me up to 3 questions first if anything
missing would change your answer; otherwise go
on. End with a list of the assumptions you made.
</process>

For this design: [paste design], write a risk
register (risk | cause | likelihood L/M/H | impact
L/M/H | mitigation | cheapest early test |
trigger), 8–12 rows, worst first. Check every risk
names a component or decision: no generic risks.

<materials>
[paste the design document, diagrams and ADRs]
</materials>
 
<context>
Approval is [when, e.g. next week]. Before then
we can spend [budget, e.g. 3 developer-days] on
spikes to test the worst risks.
</context>
 
<task>
A risk register for this design, to choose
which risks to test before approval.
</task>
 
<requirements>
- 8–12 risks, each naming the
  component or decision it comes from.
- Cover technical, operational, security (trust boundaries,
  STRIDE) and organizational risks (Conway's law, skills).
- For each, the cheapest early test: a
  spike or prototype that fits the budget.
- Rate likelihood and impact on [scale: L/M/H | 1–5].
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- No risk could be pasted into another
  project's register unchanged.
- Each trigger is observable: a metric, an event or a date.
- The top 3 risks threaten the
  top-ranked quality attributes.
</quality_bar>
 
<output_format>
A table: ID | risk | cause | likelihood |
impact | mitigation | cheapest early test
| owner role | trigger. Worst first.
</output_format>
 
<process>
End with a list of the assumptions you made.
</process>

Our architecture rules: [paste rules]. Stack: [stack,
e.g. TypeScript, Bun, Vitest]. For each rule write an
automated check, what it catches and misses, and how to
run it in CI. Check every option exists in the tool's
current docs; mark any you're unsure of [CHECK DOCS].

<materials>
[paste the dependency rules or
allowed-imports matrix, and the folder tree]
</materials>
 
<context>
Stack: [stack, e.g. TypeScript on Bun, Vitest, GitHub
Actions]. Today the rules live only in a document and
get broken about [frequency, e.g. once a sprint].
</context>
 
<task>
Fitness functions that fail CI when
an architecture rule is broken.
</task>
 
<requirements>
- One check per rule, using
  [tool: dependency-cruiser | ESLint | architecture test].
- Cover import direction, cycles, imports
  of another module's internals, and
  domain code importing infrastructure.
- For each: what it catches, what it misses,
  and roughly how long it adds to CI.
- Only options that exist in the tool's current
  docs; mark any you are unsure of [CHECK DOCS].
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Each check fails on a deliberately broken
  import; give that import as its test case.
- No check relies on file names when
  it could check the import graph.
- The config is complete enough to paste and run.
</quality_bar>
 
<output_format>
One code block per check, each followed by: rule |
catches | misses | CI cost. Then the CI job snippet.
</output_format>
 
<process>
End with a list of the assumptions you made.
</process>

Current system: [paste summary, tree, pain points].
Target: [paste target design]. Write a strangler-fig
plan: phases, what moves, the facade that switches
traffic, data migration by expand/contract, rollback per
phase. Check every phase leaves the system shippable.

<materials>
<current>
[paste the current system's summary, folder
tree, pain points and incident notes]
</current>
<target>
[paste the target architecture or proposal]
</target>
</materials>
 
<context>
Team: [team, e.g. 3 developers who also handle
support]. Fixed dates: [constraints, e.g. no
deploys in the last week of each quarter].
</context>
 
<task>
A migration plan from the current system
to the target, one capability at a time.
</task>
 
<requirements>
- Pattern: [pattern: strangler fig | parallel run],
  with the facade or routing that switches traffic.
- Data moves by expand and contract: no step needs downtime,
  and no one-way schema change runs without a backup.
- Each phase: what moves, how traffic switches, the
  rollback, and the test that proves it is done.
- Phase 1 is the lowest-risk capability
  that still teaches us something.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every phase leaves the system
  shippable and can be rolled back.
- No phase moves code and data in
  one step without a fallback.
- The plan ends with the old system switched
  off, not running forever beside the new one.
</quality_bar>
 
<output_format>
A phase table (phase | capability | what
moves | traffic switch | data step | rollback
| done when), then the risks of each phase.
</output_format>
 
<process>
Ask me up to 3 questions first if anything
missing would change your answer; otherwise go
on. End with a list of the assumptions you made.
</process>

Rules: [paste dependency rules]. ADRs: [paste relevant
ADRs]. Diff: [paste diff]. List each violation (file,
line, rule or ADR broken, why it matters, smallest fix),
worst first, no style comments. Check you cite a rule
for every finding; if none, say which rules you checked.

<materials>
<rules>
[paste the dependency rules or allowed-imports matrix]
</rules>
<adrs>
[paste the relevant ADRs]
</adrs>
<tree>
[paste the folder tree]
</tree>
<diff>
[paste the diff or the changed files]
</diff>
</materials>
 
<context>
The change: [change, e.g. late-payment fees on
invoices], by [author, e.g. a developer new to the
codebase]. It is due to merge [when, e.g. today].
</context>
 
<task>
An architecture review of this
change: violations and risks only.
</task>
 
<requirements>
- Check import direction, module boundaries,
  data ownership and the decision in each ADR.
- Severity per finding: blocker (must
  fix before merge), major or minor.
- No style or naming comments; do not rewrite the code.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your review against:
- Every finding cites a file and line
  and the rule or ADR it breaks.
- Each fix is the smallest change that restores the rule.
- If you found nothing, you list the rules you checked.
</quality_bar>
 
<output_format>
A table: severity | file:line | rule or ADR |
why it matters | smallest fix. Then any rule
the code suggests we should change instead.
</output_format>
 
<process>
End with a list of the assumptions you made.
</process>

Design a microservices architecture
for my SaaS app. Use best practices.

<context>
Product: B2B invoicing for freelancers:
clients, invoices, card payments via Stripe,
overdue reminders, quarterly tax export.
Team: 3 developers, one on-call rotation, no dedicated ops.
Scale: about 2,000 customers in year 1 and
20,000 in year 3; 50 requests/s at peak.
Readers: the other 2 developers
and a non-technical cofounder.
</context>
 
<task>
An architecture proposal I can take to the team: two
candidate architectures, a recommendation recorded
as an ADR, and the views we need to start building.
</task>
 
<requirements>
- Ranked quality attributes (ISO/IEC 25010 names): 1.
  functional correctness of payments: no lost or double
  charges; 2. maintainability: one developer ships a
  feature a week; 3. operating cost under $300/month.
- Constraints: TypeScript on Bun,
  PostgreSQL, EU hosting, GDPR.
- Candidates: a modular monolith, and the
  smallest service split you could defend.
- C4 context and container diagrams in
  Mermaid; the ADR in Nygard format.
- Justify every component against a numbered attribute.
- Never invent numbers, names, quotes or sources:
  write [NEEDS SOURCE] where support is missing.
</requirements>
 
<quality_bar>
Before answering, check your draft against:
- Every component traces to attribute 1, 2 or 3.
- The trade-offs say what each candidate makes worse.
- Each module owns its data: no module
  reads another module's tables.
- The operating load fits 3 developers with no ops.
</quality_bar>
 
<output_format>
1. Trade-off table: candidate |
   attribute 1 | 2 | 3 | operating load.
2. The recommendation as ADR-0001.
3. The two C4 diagrams.
4. Module table: module | responsibility
   | data owned | public API.
5. The top 5 risks with mitigations,
   and 3 fitness functions.
</output_format>
 
<process>
Ask me up to 3 questions first if anything
missing would change your answer; otherwise go
on. End with a list of the assumptions you made.
</process>

No questions: the brief covers the decision. Assumptions
are at the end.
 
1. Trade-offs
Candidate        | 1 Correct | 2 Maint. | 3 Cost | Ops load
Modular monolith | + one tx  | +        | +      | low
3 services       | - sagas   | 0        | -      | high
 
2. ADR-0001: Build a modular monolith
Status: Proposed
Context: 3 developers, no ops; payment correctness is the
top attribute. One PostgreSQL database keeps a payment and
its invoice update in one transaction.
Decision: one deployable, 4 modules, a schema per module.
Consequences: + one deploy, atomic money updates, under
$300/month. - One failure domain: a slow query in one
module can starve the others. - Boundaries hold only if CI
enforces them.
 
3. C4 context and container diagrams (Mermaid, omitted)
 
4. Modules
Module     | Responsibility | Data owned | Public API
invoicing  | create, send   | invoices   | createInvoice
payments   | charge, refund | payments   | charge, refund
reminders  | overdue nudges | schedules  | scheduleFor
tax-export | quarterly CSV  | exports    | runExport
Reminders runs a nightly job that selects overdue rows by
invoices.due_date and queues the emails.
 
5. Risks (2 of 5)
- Stripe can deliver a webhook twice: store an idempotency
  key per payment event.
- One module's slow query starves the rest: a statement
  timeout on each module's database role.
Fitness functions: no import of another module's internal
folders; no cycles between modules; domain code imports no
infrastructure package.
 
Assumptions:
1. Tax export runs as a quarterly batch job.
2. Reminders go out by email only.
3. Stripe reports payment results by webhook.

In the module table, reminders reads invoices.due_date
directly, which breaks "each module owns its data". Fix
it one of two ways: invoicing adds a query to its public
API (for example listOverdue(asOf)), or it publishes an
InvoiceDue event that reminders stores in its own
schema. Pick one, say why in two lines, and update the
module table, the container diagram and ADR-0001's
consequences. Then add a check that catches this kind of
dependency, such as a database role per module that can
reach only its own schema. List what you changed.

Which component in your design serves no numbered driver?
Remove it or justify it.

Argue for the simplest alternative (a modular monolith /
plain layers) as strongly as you can. Where does your
recommended design lose to it?

Pre-mortem: it is 18 months later and this architecture
failed. Write the 5 most likely reasons, then say which
decision today would have prevented each.

Which of these decisions are hard to reverse? For each,
what evidence should we gather before committing, and how
cheaply can we get it?