{{feature/system name}} System Design Doc

0. Executive Summary (READ THIS FIRST)

  • Problem:
  • Decision:
  • Why this approach:
  • Key tradeoffs:
  • Impact / scope:
Table of Contents

1. Key References & Dependencies

Prior ADRs:

  • ADR-XXX:

Specifications / Standards:

Existing systems / diagrams:

Policy / compliance docs:

2. Status

Status: Draft

3. Ownership & Metadata

  • Owner(s):
  • Reviewers:
  • Date:
  • Target release / milestone:

4. Context & Problem Statement

  • Problem statement:
  • Why now:
  • Current state / baseline:
  • Hard constraints:
  • Assumptions:

5. Goals & Non-Goals

Goals

Non-Goals

6. Stakeholders & Users

  • Primary users:
  • Secondary stakeholders:
  • Dependent teams / systems:

7. Requirements

7.1 Functional Requirements (What it must do)

  • Core capabilities:
  • Inputs / outputs:
  • Business rules / policies:
  • Primary flows:
  • Edge cases / exceptions:
  • State transitions:
  • Operational/admin actions:

7.2 Non-Functional Requirements (How well it must do it)

  • Availability / SLOs:
  • Latency / performance:
  • Scalability:
  • Reliability / fault tolerance:
  • Security / privacy:
  • Compliance / audit:
  • Observability:
  • Cost constraints:
  • Data integrity guarantees:

8. Decision

We will:

9. Architecture Overview

9.1 High-Level Components

9.2 Data / Control Flow

9.3 Data Model

  • Entities:
  • Keys / identifiers:
  • Consistency model:
  • Schema evolution:

9.4 Interfaces

  • APIs / RPCs:
  • Events / queues:
  • Versioning strategy:
  • Idempotency:

10. Policy & Authorization Model

  • AuthN:
  • AuthZ model:
  • Policy examples:
  • Evaluation points:
  • Audit requirements:

11. Failure Modes & Edge Case Handling

  • Dependency failures
  • Partial failures
  • Timeouts / retries
  • Invalid inputs
  • Overload / rate limiting
  • Consistency conflicts
  • DR assumptions

12. Observability & Operations

  • Metrics:
  • Logs:
  • Traces:
  • Dashboards:
  • Alerts:

13. Testing Strategy

  • Unit
  • Integration
  • Contract
  • Load / stress
  • Failure injection
  • Security

14. Rollout & Migration Plan

  • Phased rollout
  • Backward compatibility
  • Data migrations
  • Rollback plan
  • Feature flags

15. Alternatives Considered

Option A

  • Pros
  • Cons
  • Why rejected

Option B

  • Pros
  • Cons
  • Why rejected

16. Tradeoffs, Risks & Open Questions

  • Optimized for:
  • Deprioritized:
  • Risks:
  • Mitigations:
  • Open questions:

17. Consequences

  • Positive
  • Negative
  • Follow-on work

18. Acceptance Criteria

19. Appendix

References

Diagrams

Glossary