technical-spec

❌ FORBIDDEN:
## Solution
We will use PostgreSQL for the database.
(No alternatives considered)
 
✅ REQUIRED:
## Proposed Solution

❌ FORBIDDEN:
"The user sends a request to the API, which talks to the database
and returns a response."
 
✅ REQUIRED:
Include at least one of:
- C4 Context/Container diagram
- Sequence diagram for key flows
- Data flow diagram
 
Example (Mermaid):
```mermaid
sequenceDiagram
    Client->>API: POST /orders
    API->>Auth: Validate token
    Auth-->>API: User context
    API->>DB: Create order
    DB-->>API: Order ID
    API-->>Client: 201 Created

 
### Success Metrics Defined
 
**Every design must include measurable success criteria.**
 
```markdown
❌ FORBIDDEN:
## Goals
- Make the system faster
- Improve reliability
- Better user experience
 
✅ REQUIRED:
## Success Metrics
 
| Metric | Current | Target | Measurement |
|--------|---------|--------|-------------|
| API Latency (P95) | 500ms | <200ms | Prometheus histogram |
| Availability | 99.5% | 99.9% | Uptime monitoring |
| Error Rate | 2% | <0.1% | Error tracking |
| Throughput | 1K req/s | 10K req/s | Load testing |

❌ FORBIDDEN:
(No risk section, assuming everything will work)
 
✅ REQUIRED:
## Risks & Mitigations
 
| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| Database migration fails | High | Medium | Backup + rollback plan, test in staging |
| Third-party API unavailable | Medium | Low | Circuit breaker, fallback cache |
| Team lacks expertise | Medium | Medium | Pair programming, external review |
| Scope creep | High | High | Fixed scope document, change control |

# Title: User Authentication System
 
**Author**: Jane Doe
**Status**: Proposed | In Review | Approved | Implemented
**Created**: 2025-12-18
**Last Updated**: 2025-12-18
**Reviewers**: @tech-lead, @security-team

## Problem
 
**Current State**: Users authenticate via legacy session cookies, no MFA support.
**Impact**: 23% of security incidents related to compromised credentials.
**Constraint**: Must support 10K concurrent users, <200ms login latency.
**Goal**: Implement secure, scalable authentication with MFA and OAuth support.

## Solution
 
Implement JWT-based authentication with:
- Access tokens (15min TTL) + Refresh tokens (7 day TTL)
- TOTP-based MFA (Google Authenticator compatible)
- OAuth 2.0 providers (Google, GitHub)
- Redis for token blacklist and session management
 
### High-Level Design
 
[Include C4 Container diagram here]
 
### Data Flow
 
1. User submits credentials → Auth Service validates
2. Auth Service generates JWT pair, stores refresh token in Redis
3. Client includes access token in Authorization header
4. API Gateway validates token, extracts user context
5. On expiry, client exchanges refresh token for new access token

## Alternatives
 
### Option A: Session-based authentication
**Pros**: Simpler implementation, server-side revocation
**Cons**: Doesn't scale horizontally, higher latency
**Decision**: Rejected - doesn't meet scalability requirements
 
### Option B: Auth0 (3rd party)
**Pros**: Battle-tested, feature-complete
**Cons**: $500/month cost, vendor lock-in
**Decision**: Deferred - revisit if team velocity insufficient

## Risks & Mitigations
 
| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| JWT secret leak | Critical | Low | Rotate secrets quarterly, use HSM |
| Token theft (XSS) | High | Medium | HttpOnly cookies, CSP headers |
| Redis downtime | High | Low | Fallback to stateless validation |
| Clock skew issues | Medium | Medium | Use `nbf` claim, allow 5min tolerance |

## Work Breakdown
 
### Phase 1: Core Authentication (Week 1-2)
- [ ] JWT generation/validation service
- [ ] Password hashing (bcrypt)
- [ ] User repository interface
- [ ] Unit tests + integration tests
 
### Phase 2: MFA (Week 3)
- [ ] TOTP secret generation
- [ ] QR code generation
- [ ] Verification endpoint
- [ ] Backup codes
 
### Phase 3: OAuth (Week 4)
- [ ] Google OAuth integration
- [ ] GitHub OAuth integration
- [ ] Account linking flow
 
### Success Metrics
- 100% test coverage for auth logic
- <100ms token validation latency
- Zero security vulnerabilities in audit

## Open Questions
 
1. **Token storage**: Should refresh tokens be in httpOnly cookie or localStorage?
   - **Recommendation**: Cookie (XSS protection), need CSRF mitigation
 
2. **MFA enforcement**: Opt-in or mandatory for all users?
   - **Requires**: Product team decision
 
3. **Session limits**: Should we limit concurrent sessions per user?
   - **Impact**: Redis storage requirements, UX complexity

✅ DO:
- Use simple, direct language
- Define acronyms on first use
- Include diagrams for complex flows
- Use tables for comparisons
- Provide concrete examples
 
❌ DON'T:
- Use jargon without explanation
- Write walls of text
- Assume prior knowledge
- Skip the "why" behind decisions
- Create docs that become stale

sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User data
    API->>Redis: Store session
    API-->>Client: JWT token

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
 
System_Boundary(c1, "Auth System") {
    Container(api, "API Gateway", "Node.js", "Routes requests")
    Container(auth, "Auth Service", "Go", "Handles authentication")
    ContainerDb(redis, "Redis", "Cache", "Sessions & tokens")
}
 
Person(user, "User")
user -> api : Login request
api -> auth : Validate
auth -> redis : Store token
@enduml

# Store docs with code
docs/
├── architecture/
│   ├── ADRs/
│   │   ├── 001-database-selection.md
│   │   └── 002-api-authentication.md
│   └── diagrams/
│       └── c4-system-context.puml
├── design/
│   └── auth-system-design.md
└── rfcs/
    └── 2025-01-user-authentication.md

## Requirements Traceability
 
| Requirement | Design Element | Implementation | Tests |
|-------------|---------------|----------------|-------|
| REQ-001: MFA support | Auth Service TOTP module | `auth/totp.go` | `auth/totp_test.go` |
| REQ-002: OAuth login | OAuth provider adapter | `auth/oauth.go` | `auth/oauth_test.go` |
| REQ-003: <100ms latency | Redis token cache | `middleware/jwt.go` | `benchmark/auth_bench.go` |

## Document Status
 
- **Proposed**: Initial draft, seeking feedback
- **In Review**: Under review by stakeholders
- **Approved**: Accepted, ready for implementation
- **Implemented**: Fully implemented
- **Deprecated**: No longer valid, superseded by ADR-XXX

❌ Design as justification
   - Don't write docs after implementation to justify decisions
   - Write BEFORE to think through design
 
❌ Too much detail
   - Don't document every function and variable
   - Focus on system-level design, not line-by-line code
 
❌ Spec-first waterfall
   - Don't spend months on perfect design
   - Write enough to start, iterate as you learn
 
❌ Stale documentation
   - Don't let docs drift from reality
   - Update or delete outdated docs
 
❌ No alternatives analysis
   - Don't present only one solution
   - Show you considered trade-offs
 
❌ Missing success criteria
   - Don't forget to define "done"
   - Include measurable success metrics