Notes on the general software design lifecycle, the difference between design docs and implementation docs, and what a solid design doc should contain.
General Design Lifecycle
- Problem clarification and requirement doc
- Background, context, and problem statement
- Goals and success criteria
- Out of scope and non-goals
- Strategy and architecture doc
- HLD
- Major components, data flow, APIs, storage, queues, and dependencies
- LLD if possible
- Core entities, class or service responsibilities, schema
- Alternatives considered and tradeoffs
- HLD
Assumptions:
- traffic will not exceed X QPS in v1
- agents are idempotent
- only single-region support is needed initially
- Design review, align and refine
- Share with peers or leadership
- Gather feedback on correctness, feasibility, and risks
- Update the doc
- Implementation
- Follow design
- Write tests
- Implementation doc for product, non-eng, and ops
Purpose:
- explain what was actually built
- explain how to use or run it
Typical content:
- What we built: high-level summary of the system or feature
- How it works: simplified flow, less engineering jargon, enough to explain behavior
- Setup requirements: infra, dependencies, installation steps
- Configuration and properties: env vars, feature flags, property controllers
- Usage instructions: API endpoints, inputs and outputs, sample calls
Limitations and Known Issues:
- What are the current limitations or known issues in this implementation
- Deployment strategy: rollout and rollback
- How it will be deployed, CI/CD, scripts
- Rollout plan, staged, canary, feature flag
- Rollback strategy, how to revert safely
- Backward compatibility notes
- Testing: unit, integration, load
- Unit and integration tests and automation
- Load and stress tests
- Failure and chaos testing for reliability
Design doc = requirements + planned solution. Implementation doc = what got built + how to run or use it.
Design Doc Overview
What - Why - How
| Section | Description | Level of Detail |
|---|---|---|
Overview, Problem Statement and Goals Core Product Requirements |
What the service does, key problems it solves, and primary users. Goals are explicit objectives. Non-goals are things intentionally not covered to avoid scope creep. | 1-2 pages |
| High-Level Architecture (HLD) | System-level architecture diagram, major components, and high-level request or data flow. No deep implementation details. | Visual diagram + 1 page explanation |
| API Design | Overview of REST or gRPC endpoints, high-level request or response shapes, versioning strategy, and how other services integrate. | Sample requests for main APIs |
| Key Components (Light LLD) and Data Model (Optional) | Description of important internal modules, adapter patterns, orchestrators, caching logic, rate limiting, routing, and so on. Not class-by-class LLD. Also includes high-level schema, key fields, storage choices, and data contracts when relevant. | ER diagram or schema overview |
| Performance & Scalability | Current traffic, latency SLAs, throughput, scaling strategy, performance expectations, and SLOs. | Optional but small |
| Security, Compliance and Reliability | Authentication, authorization, RBAC, secret management, PII redaction, data residency, audit requirements, failover strategies, retries, and circuit breakers. | Security model overview |
| Deployment & Operations (Optional) | How the service is deployed, for example Kubernetes, rollout strategy, environment setup, and multi-region structure. | High-level process, no YAML or Helm values |
| Limitations and Future Scope | Current constraints, technical debt, bottlenecks, and planned improvements or features in pipeline. | Brief bullets |
| Appendix (Optional) | Code references, extended diagrams, vendor matrix, glossary, and deep links to configs. Keeps the main doc clean. | Supporting materials |