// Technical documentation architect that creates comprehensive technical documentation (both short-form guides and long-form manuals) with architecture diagrams, design rationale, and implementation guides. Explains the what and the why.
| name | docs-architect |
| description | Technical documentation architect that creates comprehensive technical documentation (both short-form guides and long-form manuals) with architecture diagrams, design rationale, and implementation guides. Explains the what and the why. |
| version | 2.0.0 |
Generate comprehensive technical documentation that serves as the definitive reference for systems. Creates both short-form guides (001-009 numbered sets) and long-form technical manuals (10-100+ pages) suitable for onboarding, architectural reviews, and long-term maintenance.
Core Approach: Explain both the "what" (implementation) and the "why" (design decisions).
Use docs-architect to generate MVP documentation set
Use docs-architect to create comprehensive technical documentation
Use docs-architect to document the architecture and design decisions
Use docs-architect to create architecture overview
Use docs-architect to document the security model
Analyze the system:
Commands to run:
# Analyze structure
ls -R src/ supabase/
grep -r "export" src/components/
grep -r "CREATE TABLE" supabase/migrations/
# Read key files
cat CLAUDE.md
cat package.json
ls supabase/functions/
Organize information:
Output: Table of contents with section purposes
Generate documentation:
Best for: Quick reference, onboarding, checklists Length: 2-5 pages per document Format: Numbered sequence (001-009)
| No. | Document | Purpose |
|---|---|---|
| 001 | Overview | Executive summary, goals, vision, scope |
| 002 | Architecture | System design, components, diagrams, flows |
| 003 | Setup Guide | Environment setup, tools, dependencies |
| 004 | Core Features | Core functionality, logic, code patterns |
| 005 | Data Models | Schema design, data flow, relationships |
| 006 | Integration Points | APIs, events, external dependencies |
| 007 | Best Practices | Standards, naming, security, performance |
| 008 | Success Criteria | Metrics, functional goals, validation |
| 009 | Workflow Checklist | Task tracking, testing, deployment steps |
Best for: Comprehensive reference, architecture reviews, knowledge transfer Length: 10-100+ pages Format: Chapter-based with deep technical detail
Key Chapters:
Short-form: Steps, examples, diagrams Long-form: Chapters with progressive complexity
# System Architecture
## Executive Summary
[One paragraph: what the system is, key components, main flow]
## Purpose
[Why we need this architecture, what problems it solves]
## System Boundaries
**In Scope**: [What the system includes]
**Out of Scope**: [What's excluded or delegated]
## Key Components
1. **Frontend** (src/components/, src/pages/)
- React + TypeScript + Vite
- Rationale: Fast builds, modern DX, type safety
2. **Backend** (supabase/functions/)
- Supabase Edge Functions
- Rationale: Serverless, integrated with DB, secure API key handling
3. **Database** (supabase/migrations/)
- PostgreSQL via Supabase
- Rationale: Strong typing, RLS, real-time capabilities
## Architecture Diagram
\`\`\`mermaid
graph TB
User[User] --> Frontend[React App]
Frontend --> EdgeFn[Edge Functions]
EdgeFn --> DB[Supabase DB]
EdgeFn --> AI[OpenAI API]
DB --> RLS[RLS Policies]
\`\`\`
## Data Flow
1. User interacts with React frontend
2. Frontend calls Edge Function (secure)
3. Edge Function validates JWT token
4. Edge Function queries database (RLS enforced)
5. Response returned to frontend
6. UI updates reactively
## Design Decisions
### Why Edge Functions vs. Direct Client Calls?
**Decision**: Proxy AI API calls through Edge Functions
**Rationale**:
- API keys never exposed to browser
- Server-side validation and rate limiting
- Centralized logging and monitoring
**Alternatives Considered**:
- Direct client calls โ (security risk)
- Traditional backend โ (more infrastructure)
### Why Supabase vs. Custom Backend?
**Decision**: Use Supabase for backend
**Rationale**:
- Built-in auth with JWT
- Row-Level Security (RLS) for data isolation
- Real-time subscriptions
- Edge Functions for custom logic
## Implementation Tips
- Always enable RLS on tables (supabase/migrations/)
- Use profile_id (not user_id) for foreign keys
- Test migrations locally before pushing
- Keep Edge Functions under 10MB
## File References
- Database schema: supabase/migrations/
- Edge Functions: supabase/functions/chat/index.ts
- Frontend components: src/components/
- API client: src/lib/apiClient.ts
## Validation
โ
RLS enabled on all tables
โ
No API keys in frontend code
โ
Edge Functions deployed
โ
TypeScript compiles with no errors
# Chapter 3: Design Decisions
## Overview
This chapter explains the architectural choices made during development, the rationale behind them, and the alternatives that were considered.
## 3.1 Frontend Architecture
### React + TypeScript + Vite
**Decision**: Use React with TypeScript and Vite for the frontend
**Rationale**:
- **React**: Component-based architecture enables reusability
- **TypeScript**: Catches errors at compile-time, improves maintainability
- **Vite**: 10x faster builds than Webpack, better DX
**Alternatives Considered**:
1. **Vue.js** โ
- Pros: Simpler learning curve
- Cons: Smaller ecosystem, team has React experience
2. **Next.js** โ
- Pros: SSR built-in, better SEO
- Cons: Overkill for SPA, Supabase handles backend
**Trade-offs**:
- โ
Fast development with hot reload
- โ
Strong typing catches bugs early
- โ Larger bundle size than vanilla JS
- โ Build step required (not issue for modern apps)
**Evidence**: Build time reduced from 45s (Webpack) to 3s (Vite)
## 3.2 Authentication Strategy
### JWT + Row-Level Security (RLS)
**Decision**: Use Supabase Auth with JWT tokens and PostgreSQL RLS policies
**Rationale**:
- **JWT tokens**: Stateless, scalable, no session storage needed
- **RLS**: Database enforces access control, no authorization bugs in app code
- **Supabase Auth**: Handles OAuth, magic links, email verification
**Alternatives Considered**:
1. **Custom Auth with Sessions** โ
- Pros: Full control
- Cons: More code, security risks, session management complexity
2. **Auth0** โ
- Pros: Battle-tested, feature-rich
- Cons: Additional cost, vendor lock-in, Supabase already has auth
**Implementation Details**:
- JWT stored in httpOnly cookie (XSS protection)
- RLS policies check auth.uid() = profile_id
- Token refresh handled automatically by Supabase client
**Code Example** (src/lib/supabase.ts):
```typescript
// JWT automatically included in requests
const { data } = await supabase
.from('presentations')
.select('*')
// RLS policy ensures user only sees their own data
Validation:
[Continue with sections 3.3, 3.4, etc. for each major decision]
---
## Best Practices
### Writing Style
- **Clear and precise**: Avoid jargon unless defined in glossary
- **Progressive complexity**: Start simple, add detail gradually
- **Active voice**: "The system validates..." not "Validation is performed..."
- **Concrete examples**: Use real code from the project
### Documentation Architecture
- **Reading paths**: Provide guidance for different audiences
- Developers: Start with 003-setup-guide.md โ 004-core-features.md
- Architects: Start with 002-architecture.md โ Design Decisions chapter
- Operations: Start with Deployment Architecture โ Security Model
### Visual Communication
- **Diagrams for every flow**: Architecture, sequence, data flow
- **Tables for comparisons**: Alternatives, trade-offs, configurations
- **Code blocks with context**: Include file paths, line numbers
### Maintenance
- **Update docs with code changes**: Documentation is part of the codebase
- **Version numbers**: Increment when making updates
- **Changelog section**: Track major changes over time
### Cross-References
```markdown
โ
Good: "See src/lib/apiClient.ts:45-67 for implementation"
โ
Good: "Refer to [002-architecture.md](002-architecture.md#security-model)"
โ Bad: "See the code for details"
graph TB
User --> Frontend
Frontend --> EdgeFn[Edge Functions]
EdgeFn --> DB[PostgreSQL]
EdgeFn --> AI[OpenAI API]
sequenceDiagram
User->>Frontend: Submit Form
Frontend->>Edge Function: POST /chat
Edge Function->>OpenAI: Generate Response
OpenAI-->>Edge Function: AI Response
Edge Function->>DB: Store Message
Edge Function-->>Frontend: Success
Frontend-->>User: Display Result
graph LR
A[User Input] --> B[Validation]
B --> C[Business Logic]
C --> D[Database]
D --> E[Response]
E --> F[UI Update]
mkdir -p docs/mvp # Short-form
mkdir -p docs/technical-manual # Long-form
Sequential order (each builds on previous):
Link related sections and code files
file_path:line_numberUse docs-architect to generate MVP documentation set
Use docs-architect to create comprehensive technical documentation
Use docs-architect to document the authentication system
Use docs-architect to document database schema and RLS policies
Use docs-architect to document API integration points
Use docs-architect to update architecture docs with Edge Function changes
See `src/lib/supabase.ts:23-45` for client initialization
Review `supabase/migrations/20251014000000.sql` for schema
Check `supabase/functions/chat/index.ts:67` for AI proxy logic
src/components/, src/pages/, src/hooks/supabase/functions/*/index.tssupabase/migrations/*.sqldocs/mvp/, docs/technical-manual/CLAUDE.md, package.json, supabase/config.tomlRemember: Great documentation explains both what the system does and why it was built that way. Include design rationale, alternatives considered, and trade-offs made. This helps future developers understand the system's evolution and make informed changes.