dralgorhythm Designing Systems
Artifact Selection
- ADR (
./artifacts/adr_[topic].md, template): one decision — a choice among alternatives with rationale and consequences. - System Design Doc (
./artifacts/system_design_[component].md, template): a whole system or component — architecture, data model, API, NFRs, phased plan.
A new system usually needs both: the system design doc for the overall shape, plus an ADR for each decision worth justifying independently (e.g., "why Postgres over DynamoDB").
Workflow
- Requirements: Gather functional and non-functional requirements
- Diagram: Draft a Mermaid diagram showing components and their boundaries
- Data & API: Define the data model, storage strategy, and interface contracts
- Trade-offs: For each major decision, table Option A vs Option B — pros, cons, when to choose
- Risks: Identify single points of failure
- Tech Strategy: Confirm every technology choice matches
.claude/rules/tech-strategy.md— no deviation without explicit instruction - Document: Fill in the matching template and save under
./artifacts/
Design-Validation Loop
- Draft the artifact from the template
- Review with stakeholders
- Build a POC for the riskiest component
- Refine the design from POC findings
- Finalize the artifact