Architektúratervezés

Architecture Planning

Design the simplest system that meets the real requirements and that the team can build, run and change. Start from the existing system, never from a blank page.

Workflow

1. Requirements: the functional ones, the non-functional ones with numbers, and the constraints (budget, timeline, team, existing stack). Do not design until they are covered; name what is missing and ask.
2. Options: map the requirements to patterns, and keep at least one alternative to the favorite.
3. Design: components and their responsibilities, data ownership, the interfaces between them, and a diagram (Mermaid or ASCII) when it helps.
4. Decide: state each key decision with its trade-off; record the ones that pass the ADR gate.
5. Review: check the design against the requirements and the failure modes; on a gap, return to step 3.

Non-functional requirements, with numbers

• Performance: p95 latency per key endpoint (for example under 200 ms), throughput, batch volume.
• Scale: concurrent users, requests per second, data volume and growth, peak versus average.
• Availability: 99.9% allows about 8.8 hours of downtime a year, 99.99% about 53 minutes. Choose by need; every extra nine costs.
• Recovery: RPO (data you may lose) and RTO (time to restore), and the backups that meet them.
• Security and compliance: authentication, authorization model, data sensitivity, encryption, tenant isolation, regulations.
• Operations and cost: deploy frequency, monitoring, on-call, monthly budget.

Patterns

Failure modes

For each component: what fails, the impact, and the mitigation (database down: failover; cache down: fall back to the database, degraded; external API slow: timeout and fallback). Plan for partial failure, retries and duplicates at every boundary.

Architecture decision records

Write an ADR only when all three hold:

1. Hard to reverse: changing your mind later would cost something meaningful.
2. Surprising without context: a future reader would wonder why it was done this way.
3. A real trade-off: there were genuine alternatives and one was chosen for specific reasons. Typical cases: the architectural shape, how contexts integrate, technology with lock-in (database, message bus, auth provider, hosting), ownership and scope boundaries (an explicit "no" counts), deliberate deviations from the obvious path, constraints not visible in code, and rejected alternatives someone will propose again. Format: put it where the project keeps them (otherwise docs/adr/0001-short-slug.md, numbered in sequence); a title and 1–3 sentences on context, decision and why. Add status, alternatives considered or consequences only when they add value.

Rules

• Weigh the downsides and operating cost, not only the benefits; record each technology choice with the alternatives considered.
• Every piece of data and every business rule has exactly one owner.
• Security is part of the design: trust boundaries, authorization, secrets.
• Keep proven facts, assumptions and proposals apart, and name what is uncertain.

Output

A requirements summary, the design (components, data, interfaces, diagram), key decisions with trade-offs, risks and mitigations, open questions.