# Architecture Documentation Maintenance Guide

**Version:** 1.0
**Last Updated:** 2026-01-10
**Status:** Active

---

## Table of Contents

1. [Overview](#overview)
2. [When to Update Documentation](#when-to-update-documentation)
3. [Update Triggers & Document Matrix](#update-triggers--document-matrix)
4. [Maintenance Procedures](#maintenance-procedures)
5. [Review Schedule](#review-schedule)
6. [Verification Checklist](#verification-checklist)
7. [Common Change Scenarios](#common-change-scenarios)
8. [Tools & Automation](#tools--automation)
9. [Responsibilities](#responsibilities)
10. [Emergency Updates](#emergency-updates)

---

## Overview

### Purpose

This guide ensures the architecture documentation in `docs/architecture/` remains accurate, complete, and useful as the Norda Biznes platform evolves.

### Documentation Coverage

Current architecture documentation set:

| Document | File | Size | Topics |
|----------|------|------|--------|
| **Architecture Overview** | README.md | 26KB | Master index, quick starts, FAQ |
| **System Context** | 01-system-context.md | 14KB | C4 Level 1, external actors |
| **Container Diagram** | 02-container-diagram.md | 29KB | C4 Level 2, major containers |
| **Deployment** | 03-deployment-architecture.md | 68KB | Infrastructure, servers, ports |
| **Flask Components** | 04-flask-components.md | 47KB | Routes, services, models |
| **Database Schema** | 05-database-schema.md | 38KB | ERD, 36 tables, relationships |
| **External APIs** | 06-external-integrations.md | 30KB | 6 APIs, 2 scrapers |
| **Network Topology** | 07-network-topology.md | 34KB | Network zones, routing |
| **Critical Config** | 08-critical-configurations.md | 34KB | NPM, SSL, systemd, secrets |
| **Security** | 09-security-architecture.md | 65KB | RBAC, threat model, controls |
| **API Endpoints** | 10-api-endpoints.md | 60KB | 90+ routes reference |
| **Troubleshooting** | 11-troubleshooting-guide.md | 59KB | Operations guide |

**Data Flow Documentation:**

| Document | File | Topics |
|----------|------|--------|
| **Authentication Flow** | flows/01-authentication-flow.md | Login, sessions, passwords |
| **Search Flow** | flows/02-search-flow.md | Company search, FTS, fuzzy |
| **AI Chat Flow** | flows/03-ai-chat-flow.md | Gemini integration, costs |
| **SEO Audit Flow** | flows/04-seo-audit-flow.md | PageSpeed API, scoring |
| **News Monitoring Flow** | flows/05-news-monitoring-flow.md | Brave API, moderation |
| **HTTP Request Flow** | flows/06-http-request-flow.md | NPM → Flask → PostgreSQL |

---

## When to Update Documentation

### Critical Update Triggers (Update Within 24 Hours)

**MUST update immediately when:**

- ❗ **Infrastructure changes** (IP addresses, ports, server names)
- ❗ **Security configuration changes** (authentication, authorization, RBAC)
- ❗ **Critical configuration changes** (NPM proxy settings, database connections)
- ❗ **Production incidents** (add to troubleshooting guide)
- ❗ **New external API integrations** (Gemini, Brave, etc.)
- ❗ **Database schema migrations** (new tables, columns, relationships)

### High Priority Updates (Update Within 1 Week)

**SHOULD update promptly when:**

- 🔶 **New major features** (authentication, search, AI chat equivalent)
- 🔶 **Significant route additions** (5+ new endpoints)
- 🔶 **New background jobs or scripts**
- 🔶 **Technology stack changes** (Flask upgrade, PostgreSQL version)
- 🔶 **Deployment process changes** (systemd, Gunicorn config)

### Standard Updates (Update Within 1 Month)

**Update during normal cycle when:**

- 🔹 **Minor feature additions** (1-4 new routes)
- 🔹 **Database model additions** (new fields, indexes)
- 🔹 **Bug fixes affecting documented flows**
- 🔹 **Performance optimizations**
- 🔹 **Code refactoring affecting architecture**

### Low Priority Updates (Quarterly Review)

**Can be batched for quarterly updates:**

- 📘 **Documentation improvements** (typos, clarifications)
- 📘 **Example updates** (better code samples)
- 📘 **FAQ additions**
- 📘 **Metrics updates** (company counts, performance stats)

---

## Update Triggers & Document Matrix

Use this matrix to identify which documents need updating for different types of changes:

| Change Type | Documents to Update | Priority |
|-------------|-------------------|----------|
| **New HTTP Route** | 04-flask-components.md, 10-api-endpoints.md | High |
| **New Database Table** | 05-database-schema.md, 04-flask-components.md | Critical |
| **New External API** | 06-external-integrations.md, 01-system-context.md, 02-container-diagram.md | Critical |
| **Infrastructure Change** | 03-deployment-architecture.md, 07-network-topology.md, 08-critical-configurations.md | Critical |
| **NPM Configuration** | 08-critical-configurations.md, 07-network-topology.md, flows/06-http-request-flow.md | Critical |
| **Authentication Change** | 09-security-architecture.md, flows/01-authentication-flow.md, 04-flask-components.md | Critical |
| **New Data Flow** | Create new flow doc in flows/, update README.md | High |
| **Port Mapping Change** | 03-deployment-architecture.md, 07-network-topology.md, 08-critical-configurations.md | Critical |
| **Security Issue/Fix** | 09-security-architecture.md, 11-troubleshooting-guide.md | Critical |
| **New Service Layer** | 04-flask-components.md, 02-container-diagram.md | High |
| **Database Migration** | 05-database-schema.md | Critical |
| **SSL/TLS Change** | 08-critical-configurations.md, 07-network-topology.md | Critical |
| **Rate Limit Change** | 10-api-endpoints.md, 06-external-integrations.md | High |
| **Performance Fix** | 11-troubleshooting-guide.md, relevant flow doc | Standard |
| **Bug Fix** | 11-troubleshooting-guide.md (if recurring) | Standard |

---

## Maintenance Procedures

### Standard Documentation Update Workflow

```bash
# 1. Create a feature branch
git checkout -b docs/update-architecture-[topic]

# 2. Make documentation changes
# - Update affected .md files
# - Update Mermaid diagrams if needed
# - Update version/date in document header

# 3. Verify diagrams render correctly
python3 verify_diagrams.py

# 4. Cross-check against code
python3 verify_architecture_accuracy.py

# 5. Update the master README if needed
# - Update file sizes: ls -lh docs/architecture/*.md
# - Update stats if significant changes

# 6. Commit with clear message
git add docs/architecture/
git commit -m "docs: update [document] for [change]"

# 7. Create pull request
git push origin docs/update-architecture-[topic]

# 8. Review and merge
# - Verify diagrams in GitHub preview
# - Check for broken links
# - Merge to master
```

### Updating Mermaid Diagrams

**Best Practices:**

1. **Test locally first** - Use VS Code with Mermaid extension
2. **Keep it simple** - Prefer clarity over complexity
3. **Use consistent styling** - Follow existing color schemes
4. **Add comments** - Explain complex diagram logic
5. **Validate syntax** - Run `verify_diagrams.py` before committing

**Common Diagram Updates:**

```markdown
# Adding a new component to container diagram
# 1. Add to the diagram block
Container(new_component, "Component Name", "Technology", "Description")

# 2. Add relationships
Rel(flask_app, new_component, "Uses", "Protocol")

# 3. Update the legend if needed
# 4. Rebuild the diagram and verify rendering
```

### Updating Data Flow Diagrams

**When to create a NEW flow document:**

- New major user journey (authentication-level complexity)
- New external API integration workflow
- New background job with multiple steps
- Complex multi-system interaction

**Template for new flow document:**

```markdown
# [Feature Name] Data Flow

**Document Status:** Draft/Active
**Last Updated:** YYYY-MM-DD

## Overview
Brief description of the data flow

## Mermaid Diagram
```mermaid
sequenceDiagram
    participant User
    participant System
    User->>System: Request
    System-->>User: Response
```

## Step-by-Step Flow
1. User initiates...
2. System processes...

## Database Operations
Tables affected, queries used

## Error Handling
Common errors and recovery

## Performance Considerations
Typical latency, bottlenecks

## Related Documentation
Links to relevant docs
```

---

## Review Schedule

### Monthly Review (1st of each month)

**Owner:** Tech Lead

**Tasks:**
- [ ] Review CHANGELOG for architecture-impacting changes
- [ ] Check for undocumented infrastructure changes
- [ ] Review GitHub issues for documentation gaps
- [ ] Update metrics in README.md (company count, route count)
- [ ] Run `verify_diagrams.py` to check diagram integrity

**Time Required:** ~30 minutes

### Quarterly Deep Review (January, April, July, October)

**Owner:** Development Team

**Tasks:**
- [ ] Full read-through of all architecture documents
- [ ] Cross-check against current codebase (`verify_architecture_accuracy.py`)
- [ ] Update all statistics and metrics
- [ ] Review and update troubleshooting guide with new issues
- [ ] Validate all external links
- [ ] Update technology versions (Flask, PostgreSQL, etc.)
- [ ] Review and update FAQ section
- [ ] Check for obsolete content
- [ ] Update maintenance checklist if needed

**Time Required:** ~2-3 hours

### Annual Comprehensive Audit (January)

**Owner:** CTO / Architecture Team

**Tasks:**
- [ ] Full architecture review session
- [ ] Validate all diagrams against production infrastructure
- [ ] Update all document versions
- [ ] Review and update security documentation
- [ ] Assess documentation completeness
- [ ] Plan documentation improvements for the year
- [ ] Update this maintenance guide

**Time Required:** ~1 day

---

## Verification Checklist

### Pre-Commit Verification

Before committing architecture documentation changes:

- [ ] All Mermaid diagrams render correctly in VS Code
- [ ] No syntax errors in Mermaid diagrams (`verify_diagrams.py`)
- [ ] File sizes updated in README.md if changed significantly
- [ ] Links to other documents work correctly
- [ ] Code examples are tested and accurate
- [ ] Date and version updated in document header
- [ ] Spelling and grammar checked
- [ ] No sensitive information (passwords, real API keys) included

### Post-Merge Verification

After merging documentation changes:

- [ ] Diagrams render correctly on GitHub
- [ ] Links work in GitHub web interface
- [ ] Table of contents is accurate
- [ ] Document appears in master README.md navigation
- [ ] Related documents are cross-linked
- [ ] CLAUDE.md references updated if needed

### Quarterly Audit Checklist

Every 3 months, verify:

- [ ] **Code Accuracy** - Run `verify_architecture_accuracy.py`
- [ ] **Infrastructure Accuracy** - Check IPs, ports, server names
- [ ] **API Accuracy** - Verify external API endpoints, rate limits
- [ ] **Database Accuracy** - Compare documented vs actual schema
- [ ] **Route Accuracy** - Compare documented vs actual endpoints
- [ ] **Configuration Accuracy** - Check NPM, systemd, Gunicorn configs
- [ ] **Statistics Current** - Update company counts, performance metrics
- [ ] **Diagrams Render** - Run `verify_diagrams.py`
- [ ] **Links Valid** - Check all internal and external links
- [ ] **Examples Work** - Test all code examples and commands

---

## Common Change Scenarios

### Scenario 1: Adding a New HTTP Route

**Example:** Adding `/api/companies/export-csv` endpoint

**Documents to Update:**

1. **04-flask-components.md**
   - Add route to "HTTP Routes" section
   - Add to route count
   - Add to component interaction diagram if complex

2. **10-api-endpoints.md**
   - Add full endpoint documentation
   - Include request/response examples
   - Document authentication/authorization requirements
   - Add to table of contents

**Checklist:**
- [ ] Document route method (GET/POST/etc)
- [ ] Document authentication required (public/authenticated/admin)
- [ ] Document request parameters
- [ ] Document response format
- [ ] Add example cURL command
- [ ] Document rate limiting
- [ ] Add to route count in README.md

**Estimated Time:** 15-20 minutes

---

### Scenario 2: Adding a New Database Table

**Example:** Adding `company_certifications` table

**Documents to Update:**

1. **05-database-schema.md**
   - Add table to ERD diagram
   - Add to entity list
   - Document all fields
   - Document relationships
   - Add indexes and constraints
   - Update table count

2. **04-flask-components.md**
   - Add SQLAlchemy model to models section
   - Update model count
   - Add to component diagram if needed

**Checklist:**
- [ ] Add table to Mermaid ERD diagram
- [ ] Document all columns with types
- [ ] Document foreign key relationships
- [ ] Document unique constraints
- [ ] Document indexes
- [ ] Document cascade behaviors
- [ ] Add SQLAlchemy model documentation
- [ ] Update table/model counts in README.md

**Estimated Time:** 30-40 minutes

---

### Scenario 3: Adding a New External API Integration

**Example:** Integrating OpenAI API for embeddings

**Documents to Update:**

1. **06-external-integrations.md**
   - Add new API section with full documentation
   - Add to integration count
   - Add to Mermaid diagram

2. **01-system-context.md**
   - Add external system to C4 diagram
   - Document interaction

3. **02-container-diagram.md**
   - Add API integration to container diagram
   - Document data flows

4. **04-flask-components.md**
   - Add service layer component if created

**Checklist:**
- [ ] Document API purpose and use cases
- [ ] Document authentication method
- [ ] Document rate limits and quotas
- [ ] Document pricing/cost model
- [ ] Add environment variables
- [ ] Document error handling
- [ ] Add example API calls
- [ ] Update integration count
- [ ] Add to all relevant Mermaid diagrams

**Estimated Time:** 1-2 hours

---

### Scenario 4: Infrastructure Change (IP/Port/Server)

**Example:** Moving PostgreSQL to new server with IP 10.22.68.251

**Documents to Update:**

1. **03-deployment-architecture.md**
   - Update server details
   - Update IP addresses
   - Update Mermaid infrastructure diagram

2. **07-network-topology.md**
   - Update network topology diagram
   - Update IP addressing scheme
   - Update routing information

3. **08-critical-configurations.md**
   - Update database connection strings
   - Update firewall rules
   - Update monitoring configurations

4. **flows/06-http-request-flow.md**
   - Update flow diagram if affected

**Checklist:**
- [ ] Update all IP addresses
- [ ] Update all port mappings
- [ ] Update infrastructure diagrams
- [ ] Update connection string examples
- [ ] Update firewall rule documentation
- [ ] Update troubleshooting commands
- [ ] Verify all diagrams render correctly
- [ ] Test all example commands

**Estimated Time:** 1-1.5 hours

---

### Scenario 5: Security Configuration Change

**Example:** Implementing OAuth 2.0 for API authentication

**Documents to Update:**

1. **09-security-architecture.md**
   - Update authentication architecture
   - Update access control matrix
   - Add OAuth flow diagrams

2. **flows/01-authentication-flow.md**
   - Add OAuth flow documentation
   - Update sequence diagrams

3. **10-api-endpoints.md**
   - Update authentication documentation
   - Add OAuth examples

4. **04-flask-components.md**
   - Document authentication middleware changes

**Checklist:**
- [ ] Document security architecture changes
- [ ] Update authentication flows
- [ ] Add OAuth sequence diagrams
- [ ] Document token handling
- [ ] Update access control matrix
- [ ] Document security testing procedures
- [ ] Review threat model impact
- [ ] Update security best practices

**Estimated Time:** 2-3 hours

---

### Scenario 6: Production Incident

**Example:** ERR_TOO_MANY_REDIRECTS incident (2026-01-02)

**Documents to Update:**

1. **11-troubleshooting-guide.md**
   - Add incident to relevant section
   - Document symptoms
   - Document root cause
   - Document solution
   - Add diagnostic commands

2. **08-critical-configurations.md**
   - Add warning if configuration-related
   - Document correct configuration

3. **Relevant flow document**
   - Add error scenario if flow-related
   - Document recovery procedure

**Checklist:**
- [ ] Document incident symptoms
- [ ] Document root cause analysis
- [ ] Document step-by-step solution
- [ ] Add diagnostic commands
- [ ] Add prevention measures
- [ ] Add to FAQ if common issue
- [ ] Link to incident report if exists
- [ ] Update critical warnings

**Estimated Time:** 30-45 minutes

---

## Tools & Automation

### Verification Scripts

**Location:** `docs/architecture/` (if needed, create in project root)

#### verify_diagrams.py

**Purpose:** Validates all Mermaid diagrams for syntax errors

**Usage:**
```bash
python3 verify_diagrams.py
```

**Output:**
- List of all diagrams found
- Syntax errors (if any)
- Warnings about diagram complexity
- Overall validation status

**When to Run:**
- Before committing diagram changes
- Monthly review
- After bulk documentation updates

---

#### verify_architecture_accuracy.py

**Purpose:** Cross-checks documentation against actual codebase

**Usage:**
```bash
python3 verify_architecture_accuracy.py
```

**Checks:**
- Database models vs documented tables
- HTTP routes vs documented endpoints
- External APIs vs documented integrations
- Infrastructure components vs documented servers
- Configuration files vs documented settings

**When to Run:**
- Quarterly deep review
- Before major releases
- After significant code changes

---

### Recommended VS Code Extensions

Install these extensions for better documentation editing:

1. **Markdown All in One** (yzhang.markdown-all-in-one)
   - Table of contents generation
   - Markdown formatting

2. **Mermaid Preview** (bierner.markdown-mermaid)
   - Live diagram preview
   - Syntax highlighting

3. **markdownlint** (DavidAnson.vscode-markdownlint)
   - Markdown style checking
   - Consistency enforcement

4. **Code Spell Checker** (streetsidesoftware.code-spell-checker)
   - Catches typos
   - Technical dictionary support

---

### Automation Opportunities

**Future Enhancements:**

1. **GitHub Actions Workflow**
   - Auto-run `verify_diagrams.py` on PR
   - Auto-update file sizes in README
   - Auto-generate route list from Flask app

2. **Pre-commit Hook**
   - Validate Mermaid syntax
   - Check for sensitive data
   - Update last-modified dates

3. **Monthly Report**
   - Auto-generate documentation health report
   - List outdated documents (>6 months since update)
   - Identify missing documentation areas

4. **Diagram Auto-Generation**
   - Generate database ERD from SQLAlchemy models
   - Generate route list from Flask decorators
   - Generate API docs from route signatures

---

## Responsibilities

### Documentation Ownership

| Document | Primary Owner | Update Trigger |
|----------|---------------|----------------|
| README.md | Tech Lead | New docs, major changes |
| 01-system-context.md | Architect | New external systems |
| 02-container-diagram.md | Architect | Major architecture changes |
| 03-deployment-architecture.md | DevOps Lead | Infrastructure changes |
| 04-flask-components.md | Backend Lead | New routes, services |
| 05-database-schema.md | Database Lead | Schema migrations |
| 06-external-integrations.md | Integration Lead | New APIs |
| 07-network-topology.md | Network Admin | Network/routing changes |
| 08-critical-configurations.md | DevOps Lead | Config changes |
| 09-security-architecture.md | Security Lead | Security changes |
| 10-api-endpoints.md | Backend Lead | New/changed endpoints |
| 11-troubleshooting-guide.md | Operations Team | Incidents, common issues |
| flows/*.md | Feature Owner | Flow-related changes |

### Team Responsibilities

**All Developers:**
- Update documentation when making code changes
- Follow update triggers matrix
- Run verification scripts before committing
- Report documentation gaps

**Tech Lead:**
- Monthly review coordination
- Approve documentation PRs
- Maintain README.md master document
- Track documentation health metrics

**DevOps Team:**
- Maintain infrastructure documentation
- Update after infrastructure changes
- Maintain troubleshooting guide
- Verify production accuracy

**Security Team:**
- Maintain security documentation
- Review security-related changes
- Conduct security documentation audits
- Update threat model

---

## Emergency Updates

### Critical Production Issues

**When:** Production outage or security incident

**Procedure:**

1. **Resolve the incident first** - Documentation is secondary to recovery
2. **Document immediately after resolution** - While details are fresh
3. **Update within 24 hours:**
   - Add to troubleshooting guide
   - Update relevant architecture docs
   - Create incident report if needed
4. **Review in next team meeting:**
   - Lessons learned
   - Prevention measures
   - Documentation improvements

**Priority:** Critical (update within 24 hours)

---

### Urgent Configuration Changes

**When:** Emergency configuration change in production

**Procedure:**

1. **Make the change** - Production stability first
2. **Document the change immediately:**
   - Update critical-configurations.md
   - Add comment in relevant config files
   - Update deployment docs if needed
3. **Notify team:**
   - Send email/Slack with change details
   - Link to updated documentation
   - Schedule review if significant
4. **Follow up:**
   - Update related documents within 48 hours
   - Add to next monthly review agenda

**Priority:** Critical (update within 24-48 hours)

---

## Documentation Health Metrics

### Key Metrics to Track

Track these monthly to assess documentation health:

| Metric | Target | How to Measure |
|--------|--------|----------------|
| **Documentation Coverage** | >95% | % of code features documented |
| **Diagram Accuracy** | 100% | `verify_diagrams.py` pass rate |
| **Code-Doc Alignment** | >95% | `verify_architecture_accuracy.py` |
| **Update Frequency** | <3 months | Average days since last update |
| **Documentation Gaps** | <5 | Count of undocumented features |
| **Broken Links** | 0 | Link checker results |
| **Outdated Stats** | 0 | Count of incorrect metrics |

### Monthly Health Report Template

```markdown
# Architecture Documentation Health Report

**Month:** January 2026
**Reporting Period:** 2025-12-01 to 2026-01-01

## Metrics

- Documentation Coverage: 96% (✓ Target: >95%)
- Diagram Accuracy: 100% (✓ All diagrams render)
- Code-Doc Alignment: 94% (⚠ Target: >95%)
- Average Update Age: 2.1 months (✓ Target: <3 months)
- Documentation Gaps: 3 (✓ Target: <5)
- Broken Links: 0 (✓ Target: 0)
- Outdated Stats: 1 (⚠ Company count in README)

## Issues Identified

1. Database schema doc missing 3 new models added in December
2. Company count in README.md outdated (78 vs 80)

## Actions Taken

1. Updated database schema documentation
2. Updated README.md statistics

## Recommendations

1. Review database schema doc monthly with DB lead
2. Automate company count update in README
```

---

## Version History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-01-10 | Auto-Claude | Initial maintenance guide creation |

---

## Related Documentation

- **Architecture Overview:** [README.md](README.md)
- **All Architecture Docs:** [docs/architecture/](.)
- **Verification Scripts:** [verify_diagrams.py](verify_diagrams.py), [verify_architecture_accuracy.py](verify_architecture_accuracy.py)
- **Main Project Guide:** [CLAUDE.md](../../CLAUDE.md)

---

## Quick Reference Card

### 🚨 Emergency Documentation Updates

```bash
# 1. Critical infrastructure change
vim docs/architecture/03-deployment-architecture.md
vim docs/architecture/07-network-topology.md
vim docs/architecture/08-critical-configurations.md

# 2. New external API
vim docs/architecture/06-external-integrations.md
vim docs/architecture/01-system-context.md

# 3. Production incident
vim docs/architecture/11-troubleshooting-guide.md

# 4. Verify changes
python3 verify_diagrams.py

# 5. Commit immediately
git add docs/architecture/
git commit -m "docs: emergency update for [incident/change]"
git push
```

### 📋 Monthly Review Checklist

```bash
# Run on 1st of each month (15-30 minutes)

# 1. Verify diagrams
python3 verify_diagrams.py

# 2. Update metrics in README
# - Company count
# - Route count
# - File sizes

# 3. Check for gaps
git log --since="1 month ago" --name-only | grep -E "app.py|database.py"
# Did any of these changes affect architecture?

# 4. Update version dates if needed
# - Last Updated field in changed documents

# 5. Commit updates
git add docs/architecture/
git commit -m "docs: monthly architecture documentation review"
git push
```

---

## Conclusion

This maintenance guide ensures the architecture documentation remains a **living, accurate resource** rather than becoming outdated.

**Key Principles:**

1. ✅ **Update as you code** - Documentation is part of feature development
2. ✅ **Verify regularly** - Use automation to catch drift
3. ✅ **Review periodically** - Monthly light reviews, quarterly deep dives
4. ✅ **Prioritize critical changes** - Infrastructure/security updates within 24 hours
5. ✅ **Keep diagrams accurate** - Visual docs outdated = worse than no docs

**Questions or Issues?**

- Create GitHub issue with `documentation` label
- Contact Tech Lead for clarification
- Update this guide as processes evolve

---

**Document Status:** Active
**Maintenance Owner:** Tech Lead
**Next Review:** 2026-02-01 (Monthly)
