nordabiz/docs/architecture/MAINTENANCE.md

Architecture Documentation Maintenance Guide

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

---

Table of Contents

1. Overview
2. When to Update Documentation
3. Update Triggers & Document Matrix
4. Maintenance Procedures
5. Review Schedule
6. Verification Checklist
7. Common Change Scenarios
8. Tools & Automation
9. Responsibilities
10. 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

# 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:

# 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:

# [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:

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

# 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
• All Architecture Docs: docs/architecture/
• Verification Scripts: verify_diagrams.py, verify_architecture_accuracy.py
• Main Project Guide: CLAUDE.md

---

Quick Reference Card

🚨 Emergency Documentation Updates

# 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

# 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)