3.2 KiB
3.2 KiB
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:
- High Level Overview
- app purpose
- architecture summary
- tech stack
- major components
- request lifecycle
- Frontend Documentation For each major page/component:
- route/path
- purpose
- state management
- API calls used
- validation logic
- auth requirements
- important files
- related backend endpoints
- Backend Documentation For each module/service:
- purpose
- entry points
- controllers/routes
- middleware used
- business logic
- dependencies
- related DB models
- important files
- 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.
- API Documentation For every endpoint:
- method
- route
- request body
- response format
- auth requirements
- validation
- services called
- DB tables touched
- source files
- Database Documentation Document:
- schema
- tables
- relations
- indexes
- migrations
- ORM structure
- data flow
Include entity relationship explanations.
- 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
- Code Navigation Index Create a developer lookup table:
- feature
- frontend files
- backend files
- services
- database models
- middleware
- tests
- Infrastructure and Deployment Document:
- Docker setup
- compose files
- Kubernetes manifests
- CI/CD
- environment variables
- secrets handling
- reverse proxy config
- ports/services
- monitoring/logging stack
- Sequence Flows Generate clear step-by-step logic flows for:
- login
- signup
- authenticated requests
- data fetching
- background jobs
- notifications
- file uploads
- 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
- 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.