# Architecture

> Use when designing system architecture, extracting assumptions, creating ADRs, establishing domain boundaries, and mapping requirements to design choices.

- Skill: `sahilkhan30/architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sahilkhan30/architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sahilkhan30/architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SahilKhan30 (https://skillmd.com/u/sahilkhan30)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/sahilkhan30/architecture

---


# Architecture & System Design Skill

## Purpose
Standardize architectural reasoning, assumption extraction, ADR creation, and trade-off tracking for financial platform development.

---

## 1. Guideline Classification & Rules

### MANDATORY
- **Entry Point**: Read `docs/project-status.md` first before designing architecture.
- **Decision Budget**: Limit initial HLD/LLD design to **max 5–7 core ADRs** in `docs/decisions.md` to prevent analysis paralysis.
- Record explicit assumptions in `docs/assumptions.md` (`AS-xxx`) with impact ratings (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`).

### STARTING HYPOTHESIS & CONDITIONAL PATTERNS
- **Modular Monolith Starting Hypothesis**: Modular Monolith is a starting hypothesis to evaluate against scale, deployment independence, and isolation constraints rather than a default decision.
- **Asynchronous Workers**: Evaluate async processing (`@Async`, Spring Events, messaging) when high throughput or latency isolation is justified by requirements/assumptions.

---

## 2. Ambiguity Escalation Levels

- **Level 1 (Low)**: Minor detail -> Make explicit assumption (`AS-xxx`) in `docs/assumptions.md` and proceed.
- **Level 2 (Medium)**: Technical/API choice -> Make assumption (`AS-xxx`), record decision (`DEC-xxx`), proceed.
- **Level 3 (High / Critical)**: Major business rule or architectural fork -> Record `AS-xxx` with `HIGH`/`CRITICAL` impact, **STOP & prompt user immediately**.

---

## 3. ADR Template (`docs/decisions.md`)

```markdown
### DEC-xxx: [Decision Title]
- **Status**: Accepted
- **Context**: [Problem requirement REQ-xxx or constraint driving this decision]
- **Options Evaluated**:
  1. [Option A] - [Pros / Cons]
  2. [Option B] - [Pros / Cons]
- **Chosen Option & Rationale**: [Justification for choice]
- **Trade-offs & Risks**: [Consequences and operational trade-offs accepted]
- **Related Assumptions**: [AS-xxx]
```