157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# Architecture Documentation Workflows
|
|
|
|
## Table of Contents
|
|
- Interview Workflow for New Projects
|
|
- Interview Workflow for Existing Systems
|
|
- Documentation Generation Process
|
|
- Update and Maintenance Workflow
|
|
|
|
## Interview Workflow for New Projects
|
|
|
|
Gather information through these questions in order:
|
|
|
|
### Phase 1: Project Context (2-3 questions)
|
|
1. **Project basics**: Name, purpose, target users
|
|
2. **Timeline**: Launch date, current phase (planning/development/production)
|
|
3. **Team**: Size, composition, experience level
|
|
|
|
### Phase 2: Technical Stack (2-4 questions)
|
|
1. **Backend**: Primary language and framework (e.g., "Node.js with Express" or "Python with Django")
|
|
2. **Frontend**: Framework or approach (e.g., "React SPA" or "Server-rendered with templates")
|
|
3. **Database**: Type and name (e.g., "PostgreSQL" or "MongoDB")
|
|
4. **Infrastructure**: Cloud provider or hosting (e.g., "AWS" or "On-premise")
|
|
|
|
### Phase 3: Architecture Pattern (1-2 questions)
|
|
1. **Pattern**: Monolith, microservices, serverless, or hybrid
|
|
2. **Rationale**: Why this pattern? (helps understand constraints)
|
|
|
|
### Phase 4: Components (2-4 questions based on pattern)
|
|
|
|
For Monolith:
|
|
- Main modules or features
|
|
- Background jobs or scheduled tasks
|
|
- Static asset handling
|
|
|
|
For Microservices:
|
|
- List of services (name and responsibility)
|
|
- How services communicate (REST, gRPC, message queue)
|
|
- Shared components (API gateway, service mesh)
|
|
|
|
For Serverless:
|
|
- Functions and their triggers
|
|
- State management approach
|
|
- Event sources
|
|
|
|
### Phase 5: Data and Integrations (1-3 questions)
|
|
1. **Additional data stores**: Cache, search engine, file storage
|
|
2. **External services**: Payment, email, analytics, etc.
|
|
3. **APIs**: Third-party APIs being consumed
|
|
|
|
### Phase 6: Operations (1-2 questions)
|
|
1. **Deployment**: Manual, CI/CD, orchestration
|
|
2. **Monitoring**: Logging, metrics, alerting setup
|
|
|
|
## Interview Workflow for Existing Systems
|
|
|
|
For systems already built, adjust approach:
|
|
|
|
### Quick Assessment
|
|
1. **Documentation exists?** If yes, review it first
|
|
2. **Codebase access?** If yes, analyze structure
|
|
3. **Team knowledge?** Interview developers
|
|
|
|
### Targeted Questions
|
|
1. What's changed since last documentation?
|
|
2. What's causing confusion for new developers?
|
|
3. What's undocumented or poorly documented?
|
|
4. Are there any planned changes?
|
|
|
|
### Validation Approach
|
|
- Cross-reference answers with code
|
|
- Identify discrepancies between docs and reality
|
|
- Highlight areas needing attention
|
|
|
|
## Documentation Generation Process
|
|
|
|
### Step 1: Select Template
|
|
Choose based on architecture pattern:
|
|
- `assets/ARCHITECTURE.md` for general/unknown
|
|
- `assets/ARCHITECTURE-microservices.md` for microservices
|
|
- `assets/ARCHITECTURE-monolith.md` for monoliths
|
|
|
|
### Step 2: Generate System Diagram
|
|
Use `scripts/generate_diagram.py` based on pattern:
|
|
- Monolith: Use "layered" type
|
|
- Microservices: Use "flow" or "c4" type
|
|
- Simple systems: Use "simple" type
|
|
|
|
### Step 3: Fill Template Sections
|
|
Populate in this order:
|
|
1. Project Identification (Section 10) - establishes context
|
|
2. Project Structure (Section 1) - concrete foundation
|
|
3. System Diagram (Section 2) - using generated diagram
|
|
4. Core Components (Section 3) - from interview data
|
|
5. Data Stores (Section 4) - databases and caches
|
|
6. External Integrations (Section 5) - third-party services
|
|
7. Deployment & Infrastructure (Section 6) - ops details
|
|
8. Security Considerations (Section 7) - auth, encryption
|
|
9. Development & Testing (Section 8) - dev environment
|
|
10. Future Considerations (Section 9) - roadmap items
|
|
11. Glossary (Section 11) - domain-specific terms
|
|
|
|
### Step 4: Enhance with Technology Specifics
|
|
Load relevant reference and apply patterns:
|
|
- Node.js: See references/nodejs.md
|
|
- Python: See references/python.md
|
|
- Java: See references/java.md
|
|
|
|
### Step 5: Validate
|
|
Run validation script:
|
|
```bash
|
|
python scripts/validate_architecture.py ARCHITECTURE.md
|
|
```
|
|
|
|
Address any issues or warnings.
|
|
|
|
## Update and Maintenance Workflow
|
|
|
|
### For Incremental Updates
|
|
1. Identify changed components
|
|
2. Update affected sections only
|
|
3. Update "Date of Last Update" in Section 10
|
|
4. Add brief note in Future Considerations if major change
|
|
|
|
### For Major Updates
|
|
1. Re-interview on changed areas
|
|
2. Regenerate system diagram if structure changed
|
|
3. Update multiple sections as needed
|
|
4. Consider adding version notes
|
|
|
|
### Best Practices
|
|
- Keep updates small and frequent
|
|
- Document changes when they happen
|
|
- Review quarterly even if no changes
|
|
- Archive old versions if major restructure
|
|
|
|
## Tips for Effective Interviews
|
|
|
|
### Keep Questions Focused
|
|
- Ask one thing at a time
|
|
- Avoid overwhelming with options
|
|
- Build on previous answers
|
|
|
|
### Adapt Based on Responses
|
|
- If user is technical, use technical terms
|
|
- If user is non-technical, simplify language
|
|
- Skip redundant questions
|
|
|
|
### Handle Uncertainty
|
|
- If user unsure, offer to add placeholder
|
|
- Suggest reasonable defaults
|
|
- Mark uncertain items for review
|
|
|
|
### Validate Understanding
|
|
- Summarize what you heard
|
|
- Confirm critical details
|
|
- Check for consistency
|