Jay Brown
45b5f2fd50
ai generated docs and related tools for publishing new versions * ai generated docs and tooling * tools * add mermaid links * add task docs:ai:generate * Merged main into feature/ai-generated-docs Approved-by: Michael McGuinness
205 lines
8.6 KiB
Markdown
205 lines
8.6 KiB
Markdown
# **Backend Codebase Analysis & Documentation Generation**
|
||
|
||
You are an expert system architect and technical writer tasked with analyzing a large backend codebase and producing comprehensive system and developer documentation. Your analysis should be thorough, accurate, and based entirely on evidence found in the codebase.
|
||
|
||
## **Analysis Methodology**
|
||
|
||
### **1\. Initial Codebase Survey**
|
||
|
||
* Read and catalog all `.md`, `.txt`, and documentation files first
|
||
* Identify the main entry points (`main.go`, `cmd/` directories)
|
||
* Map the overall directory structure and identify major modules/packages
|
||
* Locate configuration files (`.yaml`, `.json`, `.env`, `.toml`, etc.)
|
||
* Find infrastructure files (`Dockerfile`, `docker-compose.yml`, `Makefile`, CI/CD configs)
|
||
* If you find mocks used in testing note them but also note that its the project policy going forward to not use mocks in tests.
|
||
|
||
### **2\. Architecture Discovery**
|
||
|
||
* Trace the application startup flow from main functions.
|
||
* Identify how many cmd targets there are and what each one does.
|
||
* Identify and document all major components and their relationships. Which components are shared by which cmd targets.
|
||
* Map out the service initialization
|
||
* Document the middleware stack and request/response flow
|
||
* Identify database connections, external service integrations, and third-party dependencies
|
||
|
||
### **3\. Code Structure Analysis**
|
||
|
||
* Document all packages and their purposes
|
||
* Map internal APIs and interfaces between packages
|
||
* Identify design patterns used (repository, factory, adapter, etc.)
|
||
* Document error handling strategies and logging patterns
|
||
* Analyze configuration management and environment variable usage
|
||
|
||
### **4\. Operational Analysis**
|
||
|
||
* Extract deployment information from Dockerfiles and deployment configs
|
||
* Document environment variables and configuration options
|
||
* Identify monitoring, logging, and observability implementations
|
||
* Map out database schemas and migration strategies
|
||
* Document API endpoints, authentication, and authorization mechanisms
|
||
|
||
## **Required Documentation Outputs**
|
||
|
||
### **System Documentation**
|
||
|
||
#### **1\. System Overview**
|
||
|
||
* High-level architecture diagram (textual description) and mermaid diagrams.
|
||
* Core business domain and purpose
|
||
* Technology stack and major dependencies
|
||
* Deployment architecture and infrastructure requirements
|
||
|
||
#### **2\. Service Architecture**
|
||
|
||
* Component breakdown with responsibilities
|
||
* Inter-service communication patterns
|
||
* Data flow diagrams
|
||
* Integration points with external systems
|
||
* Scalability and performance considerations
|
||
|
||
#### **3\. API Documentation**
|
||
|
||
* All REST/GraphQL/gRPC endpoints
|
||
* Identify how rest api documentation is generated from the api definitions
|
||
* Identity and document Request/response schemas
|
||
* Authentication and authorization requirements
|
||
* Rate limiting and security considerations
|
||
* Error response formats and codes
|
||
|
||
#### **4\. Data Architecture**
|
||
|
||
* Database schemas and relationships
|
||
* Data models and entity relationships
|
||
* Migration strategies and versioning
|
||
* Data persistence patterns
|
||
* Caching strategies
|
||
|
||
### **Developer Documentation**
|
||
|
||
#### **1\. Getting Started Guide**
|
||
|
||
* Prerequisites and local development setup
|
||
* Build and run instructions
|
||
* Testing procedures
|
||
* Common development workflows
|
||
|
||
#### **2\. Code Organization**
|
||
|
||
* Package structure and naming conventions
|
||
* Architectural patterns and design principles
|
||
* Code style and formatting standards
|
||
* Dependency management practices
|
||
|
||
#### **3\. Configuration Management**
|
||
|
||
* All configuration options with descriptions and default values
|
||
* Environment-specific configurations
|
||
* Feature flags and toggles
|
||
* Secret management patterns
|
||
|
||
#### **4\. Operations Guide**
|
||
|
||
* Deployment procedures
|
||
* Monitoring and alerting setup
|
||
* Log analysis and debugging
|
||
*
|
||
|
||
## **Analysis Guidelines**
|
||
|
||
### **Code Reading Strategy**
|
||
|
||
1. **Start with the entry points** \- Understand how the application bootstraps
|
||
2. **Follow the request flow** \- Trace a typical request from entry to exit
|
||
3. **Identify the core domain** \- Understand the business logic and data models
|
||
4. **Map the boundaries** \- Document package interfaces and responsibilities
|
||
5. **Extract patterns** \- Identify recurring architectural and design patterns
|
||
|
||
### **Evidence-Based Documentation**
|
||
|
||
* Quote actual code snippets to support architectural claims
|
||
* Reference specific files and line numbers when relevant
|
||
* Validate assumptions by cross-referencing multiple source files
|
||
* Distinguish between implemented features and TODO comments
|
||
* Note any discrepancies between existing documentation and actual code
|
||
|
||
### **Technical Accuracy Requirements**
|
||
|
||
* Verify all API endpoints by examining route definitions
|
||
* Confirm database schemas by reading migration files or model definitions
|
||
* Validate configuration options by tracing their usage in code
|
||
* Cross-reference Docker configurations with application requirements
|
||
* Ensure all external dependencies are documented with versions
|
||
|
||
## **Output Format Requirements**
|
||
|
||
* Use clear, hierarchical structure with consistent heading levels
|
||
* Include code examples and configuration snippets where helpful but keep these to a minimum.
|
||
* Provide file paths and specific references for all claims
|
||
* Create logical groupings of related information
|
||
* Maintain technical accuracy while ensuring readability for different audiences
|
||
* Organize the docs in levels so that at the highest level you see the big picture items then the reader can drill down as needed where possible.
|
||
|
||
## **Verification Checklist**
|
||
|
||
Before finalizing documentation, ensure:
|
||
|
||
* \[ \] All major packages and their purposes are documented
|
||
* \[ \] API endpoints match actual route definitions in code
|
||
* \[ \] Configuration options are complete and accurate
|
||
* \[ \] Database schemas reflect actual model definitions
|
||
* \[ \] Deployment instructions match Dockerfile and infrastructure configs
|
||
* \[ \] Dependencies and versions are current and complete
|
||
* \[ \] Code examples compile and reflect actual usage patterns
|
||
|
||
## **Important Notes**
|
||
|
||
* Do not make assumptions about functionality not evident in the code
|
||
* When existing documentation conflicts with code, flag these discrepancies
|
||
* Focus on what the system actually does, not what it was intended to do
|
||
* Include both happy path and error handling scenarios
|
||
* Document any deprecated or legacy patterns you discover
|
||
|
||
Begin your analysis by reading the codebase systematically and then produce the comprehensive documentation as outlined above. Try to organize so that there is a minimal amount (or none if possible) of repeated information in the docs to keep them no longer than they need to be.
|
||
|
||
All output should be placed in the ./docs\_temp directory in the form of markdown and mermaid files, etc. for the team to review.
|
||
|
||
## Optional Memory Bank Instructions
|
||
|
||
You have access to a file-based memory system to track tasks, findings, and progress when working with large codebases or complex projects. If you don’t already have some sort of sequential reasoning capability then you may use this technique to help store temporary working state.
|
||
|
||
\#\#\# Setup and Usage:
|
||
1\. \*\*Directory Structure\*\*: Create and use \`./memory/\` as your working memory directory
|
||
2\. \*\*File Naming\*\*: Use descriptive \`.md\` filenames like \`tasks.md\`, \`bugs-found.md\`, \`analysis-progress.md\`, \`files-to-review.md\`
|
||
3\. \*\*List Format\*\*: Use markdown checkboxes for trackable items:
|
||
\`\`\`markdown
|
||
\# Task List
|
||
\- \[ \] Review authentication module
|
||
\- \[x\] Check database connections
|
||
\- \[ \] Analyze error handling patterns
|
||
|
||
### **When to Use Memory Files:**
|
||
|
||
* When analyzing codebases with 50+ files
|
||
* Tracking multiple bugs or issues across sessions
|
||
* Managing step-by-step analysis plans
|
||
* Storing intermediate findings that might be lost
|
||
* Breaking down large tasks into smaller checkable items
|
||
|
||
### **Memory Management:**
|
||
|
||
* **Read** existing memory files before starting work
|
||
* **Update** progress by checking off completed items `- [x]`
|
||
* **Add** new items as you discover them `- [ ]`
|
||
* **Create** new memory files for different categories as needed
|
||
* **Clean up** completed files when projects finish
|
||
|
||
### **Example Files:**
|
||
|
||
* `current-analysis.md` \- What you're currently working on
|
||
* `issues-found.md` \- Bugs and problems discovered
|
||
* `questions.md` \- Things to ask the user about
|
||
* `next-steps.md` \- Planned future actions
|
||
|
||
Always check for existing memory files first which might indicate that you have already begun work on this and the work was interrupted. Then update them as you work.
|
||
|