# 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