Initial commit

2025-11-30 08:38:46 +08:00
commit 6902106648
49 changed files with 11466 additions and 0 deletions
--- a/.claude/skills/tech-stack-architect/SKILL.md
+++ b/.claude/skills/tech-stack-architect/SKILL.md
@@ -0,0 +1,376 @@
+---
+name: tech-stack-architect
+description: Design complete technology stack and system architecture from project requirements - generates TECH-STACK.md with frontend/backend/database/DevOps choices plus rationale, and ARCHITECTURE.md with components, data flow, and mermaid diagrams
+version: 0.1.0
+tags: [architecture, planning, tech-stack, design]
+triggers:
+  - tech stack
+  - architecture
+  - technology choices
+  - system design
+  - architecture diagram
+---
+
+# Tech Stack Architect
+
+## Purpose
+Generate comprehensive technology stack selection and system architecture design from project requirements. Creates two foundational documents that guide implementation.
+
+## When to Use
+- Starting a new project after PROJECT-OVERVIEW.md is created
+- Re-architecting existing systems
+- Technology evaluation and selection
+- Architecture documentation needed
+- User mentions "tech stack", "architecture", "system design"
+
+## Behavior
+
+### Phase 1: Technology Stack Selection
+
+1. **Read PROJECT-OVERVIEW.md** for:
+   - Project goals and constraints
+   - Scale requirements (users, data, traffic)
+   - Team skills and preferences
+   - Budget and timeline
+   - Compliance requirements
+
+2. **Analyze requirements** across 4 categories:
+   - Frontend (framework, state management, UI library)
+   - Backend (language, framework, API style)
+   - Database (RDBMS, NoSQL, caching, search)
+   - DevOps (hosting, CI/CD, monitoring, security)
+
+3. **Generate TECH-STACK.md** with:
+   - **Category tables**: Technology | Rationale | Alternatives Considered
+   - **Integration notes**: How technologies work together
+   - **Trade-offs**: What you gain/lose with this stack
+   - **Migration path**: How to evolve the stack
+   - **Team considerations**: Learning curve, hiring, support
+
+### Phase 2: System Architecture Design
+
+1. **Design components**:
+   - Client-side architecture
+   - API layer and services
+   - Data storage and caching
+   - Background jobs and queues
+   - External integrations
+
+2. **Define data flow**:
+   - Request/response paths
+   - Authentication flow
+   - Data persistence patterns
+   - Event-driven flows (if applicable)
+
+3. **Generate ARCHITECTURE.md** with:
+   - **System Overview**: High-level component diagram (C4 Context)
+   - **Component Details**: Responsibilities, interfaces, dependencies
+   - **Data Flow Diagrams**: Key user journeys with sequence diagrams
+   - **Scalability Strategy**: Horizontal scaling, caching, load balancing
+   - **Security Architecture**: Auth, encryption, OWASP considerations
+   - **Mermaid Diagrams**: C4, sequence, data flow, deployment
+
+## Output Style
+- Use `table-based` for technology comparisons
+- Use `markdown-focused` with mermaid diagrams for architecture
+- Keep rationales concise (1-2 sentences per choice)
+- Include visual diagrams for clarity
+
+## Output Files
+
+### 1. project-management/TECH-STACK.md
+```markdown
+# Technology Stack
+
+## Summary
+[2-3 sentence overview of the stack philosophy]
+
+## Frontend Stack
+
+| Technology | Choice | Rationale | Alternatives Considered |
+|------------|--------|-----------|------------------------|
+| Framework | React 18 | ... | Vue, Svelte, Angular |
+| State | Zustand | ... | Redux, Jotai, Context |
+| UI Library | Tailwind + shadcn/ui | ... | MUI, Chakra, custom |
+| Build | Vite | ... | Webpack, Turbopack |
+
+## Backend Stack
+
+| Technology | Choice | Rationale | Alternatives Considered |
+|------------|--------|-----------|------------------------|
+| Language | Python 3.11 | ... | Node.js, Go, Rust |
+| Framework | FastAPI | ... | Django, Flask, Express |
+| API Style | REST + OpenAPI | ... | GraphQL, gRPC, tRPC |
+
+## Database & Storage
+
+| Technology | Choice | Rationale | Alternatives Considered |
+|------------|--------|-----------|------------------------|
+| Primary DB | PostgreSQL 15 | ... | MySQL, MongoDB, SQLite |
+| Caching | Redis | ... | Memcached, Valkey |
+| Search | ElasticSearch | ... | Algolia, Meilisearch |
+| Object Storage | S3 | ... | MinIO, CloudFlare R2 |
+
+## DevOps & Infrastructure
+
+| Technology | Choice | Rationale | Alternatives Considered |
+|------------|--------|-----------|------------------------|
+| Hosting | AWS ECS Fargate | ... | k8s, VM, serverless |
+| CI/CD | GitHub Actions | ... | GitLab CI, CircleCI |
+| Monitoring | DataDog | ... | Grafana, New Relic |
+| Secrets | AWS Secrets Manager | ... | Vault, Doppler |
+
+## Integration Notes
+- [How frontend talks to backend]
+- [Database connection pooling strategy]
+- [Caching layer integration]
+- [CI/CD pipeline flow]
+
+## Trade-offs
+**Gains**: [What this stack provides]
+**Costs**: [Complexity, vendor lock-in, learning curve]
+
+## Migration Path
+- Phase 1: [Initial minimal stack]
+- Phase 2: [Add caching, search]
+- Phase 3: [Scale horizontally]
+
+## Team Considerations
+- **Learning Curve**: [Estimate for team]
+- **Hiring**: [Availability of talent]
+- **Support**: [Community, docs, enterprise support]
+```
+
+### 2. project-management/ARCHITECTURE.md
+```markdown
+# System Architecture
+
+## Overview
+[2-3 sentence description of the system]
+
+## C4 Context Diagram
+```mermaid
+C4Context
+  title System Context for [Project Name]
+
+  Person(user, "User", "End user of the system")
+  System(app, "Application", "Main system")
+  System_Ext(auth, "Auth Provider", "OAuth2 provider")
+  System_Ext(payment, "Payment Gateway", "Stripe")
+
+  Rel(user, app, "Uses", "HTTPS")
+  Rel(app, auth, "Authenticates", "OAuth2")
+  Rel(app, payment, "Processes payments", "API")
+```
+
+## Component Architecture
+```mermaid
+graph TB
+  Client[React Client]
+  API[FastAPI Backend]
+  DB[(PostgreSQL)]
+  Cache[(Redis)]
+  Queue[Job Queue]
+  Worker[Background Workers]
+
+  Client -->|HTTPS/JSON| API
+  API -->|SQL| DB
+  API -->|GET/SET| Cache
+  API -->|Enqueue| Queue
+  Queue -->|Process| Worker
+  Worker -->|Update| DB
+```
+
+### Component Details
+
+**Client (React)**
+- **Responsibilities**: UI rendering, state management, client-side validation
+- **Key Libraries**: React Router, Zustand, React Query
+- **Interfaces**: REST API via fetch/axios
+
+**API (FastAPI)**
+- **Responsibilities**: Business logic, validation, auth, rate limiting
+- **Key Modules**: auth, users, payments, notifications
+- **Interfaces**: REST endpoints (OpenAPI), WebSocket (notifications)
+
+**Database (PostgreSQL)**
+- **Responsibilities**: Persistent data storage, relational integrity
+- **Schema**: Users, sessions, transactions, audit logs
+- **Patterns**: Repository pattern, connection pooling
+
+**Cache (Redis)**
+- **Responsibilities**: Session storage, rate limiting, job queue
+- **TTL Strategy**: Sessions (24h), API cache (5m), rate limits (1h)
+
+**Background Workers**
+- **Responsibilities**: Email sending, report generation, cleanup jobs
+- **Queue**: Redis-backed Celery/ARQ
+- **Monitoring**: Dead letter queue, retry logic
+
+## Authentication Flow
+```mermaid
+sequenceDiagram
+  participant User
+  participant Client
+  participant API
+  participant Auth0
+  participant DB
+
+  User->>Client: Click "Login"
+  Client->>Auth0: Redirect to OAuth2
+  Auth0->>Client: Return auth code
+  Client->>API: Exchange code for token
+  API->>Auth0: Validate code
+  Auth0->>API: User profile
+  API->>DB: Create/update user
+  API->>Client: Return JWT token
+  Client->>Client: Store token (httpOnly cookie)
+```
+
+## Data Flow: User Registration
+```mermaid
+sequenceDiagram
+  participant Client
+  participant API
+  participant DB
+  participant Queue
+  participant Worker
+  participant Email
+
+  Client->>API: POST /api/register
+  API->>API: Validate input
+  API->>DB: Create user (inactive)
+  API->>Queue: Enqueue welcome email
+  API->>Client: 201 Created
+  Queue->>Worker: Process email job
+  Worker->>Email: Send welcome email
+  Worker->>DB: Log email sent
+```
+
+## Scalability Strategy
+
+### Horizontal Scaling
+- **API**: Stateless containers (2-10 instances behind ALB)
+- **Database**: Read replicas for reporting queries
+- **Cache**: Redis Cluster (3+ nodes)
+- **Workers**: Auto-scale based on queue depth
+
+### Caching Strategy
+- **API Responses**: Cache GET endpoints (5m TTL)
+- **Database Queries**: Query result cache in Redis
+- **Static Assets**: CDN (CloudFront) with edge caching
+
+### Load Balancing
+- **Application**: AWS ALB with health checks
+- **Database**: pgpool for read/write splitting
+- **Geographic**: Multi-region deployment (future)
+
+## Security Architecture
+
+### Authentication & Authorization
+- **Strategy**: OAuth2 + JWT tokens (15m access, 7d refresh)
+- **Storage**: httpOnly cookies for web, secure storage for mobile
+- **Rotation**: Automatic token refresh
+
+### Data Protection
+- **At Rest**: PostgreSQL encryption (AWS RDS)
+- **In Transit**: TLS 1.3 for all connections
+- **Secrets**: AWS Secrets Manager, rotated monthly
+
+### OWASP Top 10 Mitigations
+- **Injection**: Parameterized queries (SQLAlchemy ORM)
+- **Auth**: JWT validation, session management
+- **XSS**: Content Security Policy, input sanitization
+- **CSRF**: SameSite cookies, CSRF tokens
+- **Rate Limiting**: Redis-backed (100 req/min per IP)
+
+### Network Security
+- **VPC**: Private subnets for DB/workers
+- **Security Groups**: Least privilege access
+- **WAF**: CloudFront WAF rules
+
+## Deployment Architecture
+```mermaid
+graph TB
+  subgraph "Public Subnet"
+    ALB[Application Load Balancer]
+  end
+
+  subgraph "Private Subnet - App Tier"
+    API1[API Container 1]
+    API2[API Container 2]
+    Worker1[Worker Container]
+  end
+
+  subgraph "Private Subnet - Data Tier"
+    DB[(RDS PostgreSQL)]
+    Cache[(ElastiCache Redis)]
+  end
+
+  Internet((Internet)) --> ALB
+  ALB --> API1
+  ALB --> API2
+  API1 --> DB
+  API2 --> DB
+  API1 --> Cache
+  API2 --> Cache
+  Worker1 --> DB
+  Worker1 --> Cache
+```
+
+## Monitoring & Observability
+
+**Metrics**:
+- API latency (p50, p95, p99)
+- Error rates by endpoint
+- Database connection pool usage
+- Cache hit/miss ratios
+
+**Logging**:
+- Structured JSON logs (ECS logs to CloudWatch)
+- Request ID tracing across services
+- Error tracking (Sentry)
+
+**Alerting**:
+- API error rate >1%
+- Database connections >80%
+- Job queue depth >1000
+
+## Future Considerations
+
+**Phase 2 Enhancements**:
+- GraphQL API option
+- WebSocket real-time updates
+- ElasticSearch for full-text search
+
+**Phase 3 Scale**:
+- Multi-region deployment
+- Event-driven microservices
+- CQRS for read-heavy workloads
+```
+
+## Guardrails
+- Keep technology choices pragmatic (avoid hype-driven development)
+- Consider team skills when selecting stack
+- Prefer managed services over self-hosted for DevOps
+- Include alternatives to show deliberate choice
+- Use mermaid for all diagrams (portable, version-controllable)
+- Keep each document under 400 lines
+- Link to official docs for each technology
+
+## Integration
+- Run after PROJECT-OVERVIEW.md is created
+- Feed into `/lazy plan` for user story creation
+- Reference during `/lazy code` for implementation consistency
+- Update during `/lazy review` if architecture evolves
+
+## Example Prompt
+> Design the tech stack and architecture for this project
+
+## Validation Checklist
+- [ ] TECH-STACK.md has all 4 categories (Frontend, Backend, Database, DevOps)
+- [ ] Each technology has rationale and alternatives
+- [ ] ARCHITECTURE.md has system overview + 3+ mermaid diagrams
+- [ ] Authentication and data flow are documented
+- [ ] Scalability and security sections are complete
+- [ ] Trade-offs and migration path are clear