Skip to content

system-design.md

Latest commit

 

History

History
97 lines (57 loc) · 2.4 KB

system-design.md

File metadata and controls

97 lines (57 loc) · 2.4 KB

[System/Project Name] — System Design

Status: draft | active | shipped | deprecated Owner: @[handle] Last updated: YYYY-MM-DD

Mission

Design Principles

  • [Principle] — [why it matters for this system]

Tech Stack

Layer Technology Notes
Runtime [e.g. Node.js 20] [version or constraints]
Language [e.g. TypeScript] [strictness, conventions]
Data [e.g. PostgreSQL 16] [primary use case]
Infra [e.g. Docker, Railway] [deployment context]

Architecture

graph TD
  A[Component A] --> B[Component B]
  B --> C[Component C]
Loading

[Component Name]

External Dependencies

  • [Service/API] — [purpose and failure behavior]

Cross-Cutting Concerns

Security

Assumptions

  • [Assumption] — [what breaks if wrong]

Known Gaps and Risks

Gap Severity Impact Root Cause Mitigation / Acceptance
[e.g. No rate limiting on public API] high DoS risk on auth service Not yet implemented Planned for v1.1; WAF provides partial coverage

Controls

  • [Control] — [what it protects and how]

Data Architecture (Optional)

Observability (Optional)

Performance and Scalability (Optional)

Error Handling and Resilience (Optional)

Constraints

  • [Constraint] — [how it shapes the architecture]

Architecture Rationale (Optional)

Open Points (Optional)

  • [Question] — context and options being considered

Related Documents (Optional)

  • PRD — product requirements this design implements
  • Codebase Docs — AI-navigable map of the repo
  • Rules — engineering standards
  • ADRs — architecture decisions