170 lines
3.2 KiB
Markdown
170 lines
3.2 KiB
Markdown
|
Create a complete Technical Design Document and Troubleshooting Runbook for this web application.
|
||
|
|
|
||
|
|
Your job is to fully map the system so a developer can:
|
||
|
|
- understand the architecture quickly
|
||
|
|
- trace frontend to backend logic
|
||
|
|
- debug failures rapidly
|
||
|
|
- locate relevant code immediately
|
||
|
|
- understand authentication, state, APIs, database flow, and infrastructure
|
||
|
|
|
||
|
|
Analyze the ENTIRE codebase including:
|
||
|
|
- frontend
|
||
|
|
- backend
|
||
|
|
- API layer
|
||
|
|
- middleware
|
||
|
|
- authentication
|
||
|
|
- database models
|
||
|
|
- services
|
||
|
|
- queues/workers
|
||
|
|
- caching
|
||
|
|
- deployment configs
|
||
|
|
- environment variables
|
||
|
|
- logging
|
||
|
|
- monitoring
|
||
|
|
- tests
|
||
|
|
- Docker/Kubernetes configs if present
|
||
|
|
|
||
|
|
Generate documentation in structured markdown.
|
||
|
|
|
||
|
|
Requirements:
|
||
|
|
|
||
|
|
1. High Level Overview
|
||
|
|
- app purpose
|
||
|
|
- architecture summary
|
||
|
|
- tech stack
|
||
|
|
- major components
|
||
|
|
- request lifecycle
|
||
|
|
|
||
|
|
2. Frontend Documentation
|
||
|
|
For each major page/component:
|
||
|
|
- route/path
|
||
|
|
- purpose
|
||
|
|
- state management
|
||
|
|
- API calls used
|
||
|
|
- validation logic
|
||
|
|
- auth requirements
|
||
|
|
- important files
|
||
|
|
- related backend endpoints
|
||
|
|
|
||
|
|
3. Backend Documentation
|
||
|
|
For each module/service:
|
||
|
|
- purpose
|
||
|
|
- entry points
|
||
|
|
- controllers/routes
|
||
|
|
- middleware used
|
||
|
|
- business logic
|
||
|
|
- dependencies
|
||
|
|
- related DB models
|
||
|
|
- important files
|
||
|
|
|
||
|
|
4. Authentication and Authorization
|
||
|
|
Document:
|
||
|
|
- login flow
|
||
|
|
- session/JWT handling
|
||
|
|
- refresh tokens
|
||
|
|
- RBAC/permissions
|
||
|
|
- middleware chain
|
||
|
|
- cookie handling
|
||
|
|
- OAuth/providers if used
|
||
|
|
- failure scenarios
|
||
|
|
- exact code locations
|
||
|
|
|
||
|
|
Include step by step request flow.
|
||
|
|
|
||
|
|
5. API Documentation
|
||
|
|
For every endpoint:
|
||
|
|
- method
|
||
|
|
- route
|
||
|
|
- request body
|
||
|
|
- response format
|
||
|
|
- auth requirements
|
||
|
|
- validation
|
||
|
|
- services called
|
||
|
|
- DB tables touched
|
||
|
|
- source files
|
||
|
|
|
||
|
|
6. Database Documentation
|
||
|
|
Document:
|
||
|
|
- schema
|
||
|
|
- tables
|
||
|
|
- relations
|
||
|
|
- indexes
|
||
|
|
- migrations
|
||
|
|
- ORM structure
|
||
|
|
- data flow
|
||
|
|
|
||
|
|
Include entity relationship explanations.
|
||
|
|
|
||
|
|
7. Error Handling and Troubleshooting
|
||
|
|
Create a troubleshooting matrix.
|
||
|
|
|
||
|
|
For every common failure:
|
||
|
|
- symptom
|
||
|
|
- likely cause
|
||
|
|
- logs to inspect
|
||
|
|
- files to inspect
|
||
|
|
- services involved
|
||
|
|
- DB queries involved
|
||
|
|
- recovery steps
|
||
|
|
|
||
|
|
Especially cover:
|
||
|
|
- login failures
|
||
|
|
- session expiration
|
||
|
|
- permission issues
|
||
|
|
- API failures
|
||
|
|
- database connectivity
|
||
|
|
- caching issues
|
||
|
|
- queue failures
|
||
|
|
- deployment/configuration issues
|
||
|
|
|
||
|
|
8. Code Navigation Index
|
||
|
|
Create a developer lookup table:
|
||
|
|
- feature
|
||
|
|
- frontend files
|
||
|
|
- backend files
|
||
|
|
- services
|
||
|
|
- database models
|
||
|
|
- middleware
|
||
|
|
- tests
|
||
|
|
|
||
|
|
9. Infrastructure and Deployment
|
||
|
|
Document:
|
||
|
|
- Docker setup
|
||
|
|
- compose files
|
||
|
|
- Kubernetes manifests
|
||
|
|
- CI/CD
|
||
|
|
- environment variables
|
||
|
|
- secrets handling
|
||
|
|
- reverse proxy config
|
||
|
|
- ports/services
|
||
|
|
- monitoring/logging stack
|
||
|
|
|
||
|
|
10. Sequence Flows
|
||
|
|
Generate clear step-by-step logic flows for:
|
||
|
|
- login
|
||
|
|
- signup
|
||
|
|
- authenticated requests
|
||
|
|
- data fetching
|
||
|
|
- background jobs
|
||
|
|
- notifications
|
||
|
|
- file uploads
|
||
|
|
|
||
|
|
11. Output Rules
|
||
|
|
- Use clean markdown
|
||
|
|
- Use tables where useful
|
||
|
|
- Include file paths everywhere possible
|
||
|
|
- Reference actual code locations
|
||
|
|
- Do not invent logic not present in code
|
||
|
|
- Mark uncertain assumptions clearly
|
||
|
|
- Prefer concise technical explanations
|
||
|
|
- Focus on developer usability and debugging speed
|
||
|
|
|
||
|
|
12. Final Deliverable
|
||
|
|
Produce:
|
||
|
|
- TECHNICAL_DESIGN.md
|
||
|
|
- TROUBLESHOOTING_RUNBOOK.md
|
||
|
|
- ARCHITECTURE_OVERVIEW.md
|
||
|
|
- API_REFERENCE.md
|
||
|
|
|
||
|
|
The documentation should allow a new engineer to debug production issues and navigate directly to the correct code with minimal onboarding.
|