cloudthinker-ai System Design Document
Phase 1: Context and Requirements
Define the problem space and requirements.
Problem statement:
- What problem does this system solve?
- Who are the users/consumers?
- What is the business impact?
Functional requirements:
- Core use cases (numbered list)
- Input/output specifications
- User-facing behavior
Non-functional requirements:
- Availability target: ___
- Latency target (p99): ___
- Throughput target: ___
- Data retention requirements: ___
- Compliance requirements: ___
- Security requirements: ___
Constraints:
- Technology constraints
- Timeline constraints
- Budget constraints
- Team capacity constraints
Phase 2: High-Level Architecture
- Draw system context diagram (external systems, users, data flows)
- Draw component diagram (internal services, databases, queues)
- Identify synchronous vs asynchronous communication paths
- List all external dependencies
Component Inventory:
| Component | Responsibility | Technology | Owner |
|---|---|---|---|
Phase 3: Detailed Design
For each component:
- Data model / schema design
- API contract (endpoints, request/response schemas)
- State management approach
- Error handling strategy
- Caching strategy
- Authentication and authorization
Key Design Decisions:
| Decision | Options Considered | Chosen | Rationale |
|---|---|---|---|
Phase 4: Data Design
- Entity relationship diagram
- Storage technology selection and justification
- Read/write patterns and access patterns
- Data partitioning / sharding strategy
- Backup and recovery approach
- Data migration plan (if applicable)
Phase 5: Operational Design
- Deployment strategy (blue-green, canary, rolling)
- Monitoring and alerting plan
- Logging strategy
- Runbook for common operations
- Capacity planning estimates
- Disaster recovery plan
- Feature flag strategy
Phase 6: Security Review
- Authentication mechanism
- Authorization model
- Data encryption (at rest and in transit)
- Input validation
- Rate limiting
- Audit logging
- Threat model reference (link)
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|---|---|
| "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate |
| "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses |
| "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears |
| "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate |
| "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams |
Output Format
Document Metadata
- Project: ___
- Author: ___
- Status: Draft / In Review / Approved
- Reviewers: ___
- Last updated: ___
Review Checklist
- Requirements are testable and measurable
- Architecture diagram is clear and complete
- All external dependencies are identified
- Data model supports all use cases
- API contracts are defined
- Failure modes are addressed
- Security review is complete
- Operational concerns are addressed
- Cost estimates are included
- Timeline and milestones are defined