nordabiz/docs/architecture/README.md

# Nordabiz Platform - Architecture Documentation

## Executive Summary

The **Nordabiz Platform** is a comprehensive business directory and networking platform for members of the Norda Biznes association in Wejherowo, Poland. This architecture documentation provides complete technical reference for developers, operators, and stakeholders.

**Platform Stats:**
- **Production Status:** LIVE since 2025-11-23
- **Members:** 80 companies (100% coverage)
- **URL:** https://nordabiznes.pl
- **Technology Stack:** Flask 3.0, PostgreSQL, Google Gemini AI, Multi-API integration

**Critical Architecture Highlights:**
- **3-Tier Architecture:** NPM Reverse Proxy → Flask/Gunicorn → PostgreSQL
- **4 Security Zones:** Public Internet → DMZ → Application → Data
- **6 External API Integrations:** Gemini AI, Brave Search, PageSpeed, Places, KRS, MS Graph
- **36 Database Tables** across 11 functional domains
- **90+ HTTP Routes** across 13 categories

## Overview

This directory contains comprehensive architecture documentation for the Nordabiz platform, including system diagrams, data flows, and infrastructure details. All diagrams use **Mermaid.js** for version control-friendly visualization.

## Purpose

The architecture documentation serves to:
- Provide visual understanding of system components and their interactions
- Document critical configurations (NPM proxy, ports, servers)
- Illustrate data flows for key user journeys
- Help new developers understand system boundaries
- Prevent production incidents through clear documentation (see [Incident Report](../INCIDENT_REPORT_20260102.md))

## Quick Start

### For New Developers
**Start here:** [System Context Diagram](01-system-context.md) → [Container Diagram](02-container-diagram.md) → [Flask Components](04-flask-components.md)

**Learn data flows:** [Authentication Flow](flows/01-authentication-flow.md) → [Search Flow](flows/02-search-flow.md) → [AI Chat Flow](flows/03-ai-chat-flow.md)

**Critical warnings:** [Critical Configurations](08-critical-configurations.md) - **Must read NPM proxy section!**

### For Operations/DevOps
**Infrastructure:** [Deployment Architecture](03-deployment-architecture.md) → [Network Topology](07-network-topology.md) → [Critical Configurations](08-critical-configurations.md)

**Troubleshooting:** [HTTP Request Flow](flows/06-http-request-flow.md) - Covers the infamous port 5000 vs 80 redirect loop

**Security:** [Security Architecture](09-security-architecture.md) - Complete security model

### For System Architects
**High-level overview:** [System Context](01-system-context.md) → [Container Diagram](02-container-diagram.md) → [External Integrations](06-external-integrations.md)

**Data model:** [Database Schema](05-database-schema.md) - 36 tables, 11 domains

**Complete flows:** See all 6 flow diagrams in [`flows/`](flows/) directory

## Documentation Map

```mermaid
graph TD
    Start([Start Here]) --> Role{Your Role?}

    Role -->|Developer| Dev[01: System Context]
    Role -->|DevOps| Ops[03: Deployment]
    Role -->|Architect| Arch[02: Container Diagram]

    Dev --> DevFlow[Flask Components<br/>04]
    DevFlow --> DevData[Database Schema<br/>05]
    DevData --> DevFlows[Data Flows<br/>flows/]

    Ops --> OpsNet[Network Topology<br/>07]
    OpsNet --> OpsConfig[Critical Config<br/>08]
    OpsConfig --> OpsSec[Security<br/>09]

    Arch --> ArchExt[External APIs<br/>06]
    ArchExt --> ArchDB[Database<br/>05]
    ArchDB --> ArchSec[Security<br/>09]

    DevFlows --> End([You're Ready!])
    OpsSec --> End
    ArchSec --> End

    style Start fill:#90EE90
    style End fill:#90EE90
    style Dev fill:#87CEEB
    style Ops fill:#FFB6C1
    style Arch fill:#DDA0DD

    classDef docs fill:#FFF8DC,stroke:#333,stroke-width:2px
    class DevFlow,DevData,DevFlows,OpsNet,OpsConfig,OpsSec,ArchExt,ArchDB,ArchSec docs
```

## Documentation Structure

### High-Level Architecture
These documents provide the "big picture" view of the entire system using the C4 model approach.

| Document | Description | Size | Key Topics |
|----------|-------------|------|------------|
| [01-system-context.md](01-system-context.md) | **C4 Level 1** - System boundary, external actors, integrations | 14KB | Actors (Members, Visitors, Admins), 8 external systems, data flows |
| [02-container-diagram.md](02-container-diagram.md) | **C4 Level 2** - Major containers and their interactions | 30KB | 8 containers, protocols, NPM proxy config, security zones |
| [03-deployment-architecture.md](03-deployment-architecture.md) | **Infrastructure** - Physical servers, IPs, ports, deployment | 68KB | 3 servers, network topology, port mapping, Git workflow |

### Component Architecture
Detailed internal structure of the application and its subsystems.

| Document | Description | Size | Key Topics |
|----------|-------------|------|------------|
| [04-flask-components.md](04-flask-components.md) | Flask app components - routes, services, models | 55KB | 90+ routes, 7 services, 36 models, request handling |
| [05-database-schema.md](05-database-schema.md) | Database ERD - entities, relationships, constraints | 38KB | 36 tables, 11 domains, 45+ relationships, indexes |
| [06-external-integrations.md](06-external-integrations.md) | External APIs - authentication, rate limits, pricing | 31KB | 6 APIs (Gemini, Brave, PageSpeed, Places, KRS, MS Graph) |

### Data Flows
Detailed sequence diagrams showing how data moves through the system for key user journeys.

| Document | Description | Size | Key Topics |
|----------|-------------|------|------------|
| [flows/01-authentication-flow.md](flows/01-authentication-flow.md) | User registration, login, email verification, password reset | 27KB | Flask-Login, session mgmt, token security, access control |
| [flows/02-search-flow.md](flows/02-search-flow.md) | Company search - NIP lookup, FTS, fuzzy matching | 36KB | SearchService, synonyms, scoring, AI integration |
| [flows/03-ai-chat-flow.md](flows/03-ai-chat-flow.md) | AI chatbot - context building, Gemini API, cost tracking | 42KB | Full DB context, token optimization, dual cost tracking |
| [flows/04-seo-audit-flow.md](flows/04-seo-audit-flow.md) | SEO auditing - PageSpeed API, on-page analysis, scoring | 38KB | Admin dashboard, batch processing, quota management |
| [flows/05-news-monitoring-flow.md](flows/05-news-monitoring-flow.md) | News monitoring - Brave API, AI filtering, moderation | 58KB | Relevance scoring, admin moderation, notifications |
| [flows/06-http-request-flow.md](flows/06-http-request-flow.md) | HTTP routing - NPM → Flask → PostgreSQL ⚠️ **Critical!** | 52KB | Port 5000 config, redirect loops, troubleshooting |

### Network and Security
Infrastructure topology, critical configurations, and security model.

| Document | Description | Size | Key Topics |
|----------|-------------|------|------------|
| [07-network-topology.md](07-network-topology.md) | Network layout - Fortigate, DMZ, internal network | 38KB | 6 zones, IP addressing, DNS, routing, health checks |
| [08-critical-configurations.md](08-critical-configurations.md) | Critical settings - NPM, ports, SSL, systemd ⚠️ **Critical!** | 35KB | Port mappings, .env vars, database config, backup |
| [09-security-architecture.md](09-security-architecture.md) | Security model - zones, threats, controls, compliance | 60KB | 5 trust zones, STRIDE analysis, RBAC, OWASP Top 10 |

### Reference Documentation
*Note: These documents are planned but not yet created.*

| Document | Description | Status |
|----------|-------------|--------|
| 10-api-endpoints.md | Complete API reference with examples | 📋 Planned |
| 11-troubleshooting-guide.md | Common issues and solutions | 📋 Planned |
| MAINTENANCE.md | Documentation maintenance procedures | 📋 Planned |

## Architecture at a Glance

### System Overview Diagram

```mermaid
graph TB
    subgraph "Public Internet"
        Users[Users/Visitors]
        Admins[Administrators]
    end

    subgraph "Network Perimeter"
        Fortigate[Fortigate Firewall<br/>NAT: 178.218.174.220→10.22.68.250]
    end

    subgraph "DMZ Zone - 10.22.68.250"
        NPM[NPM Reverse Proxy<br/>:443 SSL/TLS<br/>⚠️ Forwards to :5000]
    end

    subgraph "Application Zone - 10.22.68.249"
        Flask[Flask/Gunicorn<br/>:5000 HTTP<br/>90+ routes, 7 services]
        Scripts[Background Scripts<br/>SEO, Social, News]
    end

    subgraph "Data Zone - 10.22.68.249"
        PostgreSQL[(PostgreSQL<br/>:5432<br/>36 tables, 11 domains)]
    end

    subgraph "External Services"
        Gemini[Google Gemini AI<br/>Text generation, chat]
        PageSpeed[PageSpeed Insights<br/>SEO audits]
        Brave[Brave Search<br/>News monitoring]
        Places[Google Places<br/>Business profiles]
        KRS[KRS API<br/>Company registry]
        MSGraph[MS Graph<br/>Email notifications]
    end

    Users -->|HTTPS 443| Fortigate
    Admins -->|HTTPS 443| Fortigate
    Fortigate -->|HTTPS 443| NPM
    NPM -->|HTTP 5000| Flask
    Flask -->|SQL| PostgreSQL
    Scripts -->|SQL| PostgreSQL

    Flask -->|REST API| Gemini
    Flask -->|REST API| PageSpeed
    Flask -->|REST API| Brave
    Flask -->|REST API| Places
    Flask -->|REST API| KRS
    Flask -->|OAuth 2.0| MSGraph

    style NPM fill:#FFB6C1,stroke:#333,stroke-width:3px
    style Flask fill:#87CEEB,stroke:#333,stroke-width:2px
    style PostgreSQL fill:#90EE90,stroke:#333,stroke-width:2px
    style Gemini fill:#FFF8DC,stroke:#333,stroke-width:1px
    style PageSpeed fill:#FFF8DC,stroke:#333,stroke-width:1px
    style Brave fill:#FFF8DC,stroke:#333,stroke-width:1px
```

### Technology Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| **Reverse Proxy** | Nginx Proxy Manager | SSL termination, domain routing, rate limiting |
| **Web Framework** | Flask 3.0 + Gunicorn | HTTP routing, business logic, templating |
| **Database** | PostgreSQL 13+ | Relational data, FTS, JSONB, pg_trgm |
| **Authentication** | Flask-Login | Session management, user authentication |
| **AI/ML** | Google Gemini 3 Flash | Chat, recommendations, content analysis |
| **Search** | Brave Search API | News monitoring, social media discovery |
| **SEO Audit** | Google PageSpeed Insights | Performance, accessibility, SEO scoring |
| **Business Data** | Google Places API | Reviews, ratings, business profiles |
| **Company Registry** | KRS Open API | Polish company verification |
| **Email** | Microsoft Graph API | Transactional email via OAuth 2.0 |
| **Frontend** | Jinja2 + Vanilla JS | Server-side rendering, progressive enhancement |
| **Deployment** | Systemd + Gunicorn | Process management, auto-restart |
| **Version Control** | Git (Gitea + GitHub) | Code repository, deployment source |

### Key Statistics

**Infrastructure:**
- **Servers:** 3 (NORDABIZ-01, R11-REVPROXY-01, r11-git-inpi)
- **Network:** Internal 10.22.68.0/24, Public 178.218.174.220
- **Uptime Target:** 99.5%

**Application:**
- **Routes:** 90+ HTTP endpoints
- **Services:** 7 service layer components
- **Database:** 36 tables across 11 domains
- **External APIs:** 6 integrations

**Data:**
- **Companies:** 80 members (100% coverage)
- **Users:** Active community platform
- **AI Requests:** ~1,500/day (free tier)
- **SEO Audits:** ~25,000 quota/day

**Performance:**
- **Median Response:** ~180ms
- **P95 Response:** ~350ms
- **Database Queries:** Indexed, optimized
- **Caching:** Strategic use of in-memory caching

### Critical Warnings

> ⚠️ **NPM Proxy Port Configuration**
>
> The NPM reverse proxy **MUST** forward to port **5000** (Flask/Gunicorn), NOT port 80 (nginx redirect).
> Incorrect configuration causes infinite redirect loops (ERR_TOO_MANY_REDIRECTS).
>
> **See:** [Incident Report](../INCIDENT_REPORT_20260102.md) | [HTTP Request Flow](flows/06-http-request-flow.md) | [Critical Configurations](08-critical-configurations.md)

> ⚠️ **Database Access**
>
> PostgreSQL only accepts connections from **localhost (127.0.0.1)** for security.
> All scripts must connect via localhost, not the external IP 10.22.68.249.
>
> **See:** [Critical Configurations](08-critical-configurations.md#database-configuration)

> ⚠️ **API Rate Limits**
>
> - Google Gemini: 1,500 req/day (free tier)
> - Brave Search: 2,000 searches/month (free tier)
> - PageSpeed: 25,000 req/day (free tier)
>
> Exceeding limits may cause service degradation. Monitor usage carefully.
>
> **See:** [External Integrations](06-external-integrations.md)

## Diagram Format and Tools

### Chosen Tool: Mermaid.js

All architecture diagrams in this repository use **Mermaid.js** syntax embedded in Markdown files.

#### Rationale for Mermaid.js

| Criterion | Mermaid.js | PlantUML | Draw.io/Lucidchart | Visio |
|-----------|------------|----------|-------------------|-------|
| **Version Control** | ✅ Text-based, excellent diffs | ✅ Text-based | ❌ XML/binary files | ❌ Binary files |
| **GitHub Rendering** | ✅ Native support | ⚠️ Requires plugin | ❌ No support | ❌ No support |
| **No External Tools** | ✅ Renders in browser | ❌ Requires Java | ✅ Web-based | ❌ Requires license |
| **Learning Curve** | ✅ Simple syntax | ⚠️ Moderate | ✅ Visual editor | ⚠️ Complex |
| **Diagram Types** | ✅ All needed types | ✅ Extensive | ✅ Unlimited | ✅ Unlimited |
| **Maintenance** | ✅ Easy text edits | ✅ Easy text edits | ⚠️ Requires editor | ❌ Requires software |
| **Cost** | ✅ Free & open-source | ✅ Free | ⚠️ Free tier limited | ❌ Paid |

**Decision:** Mermaid.js provides the best balance of version control friendliness, native GitHub rendering, zero external dependencies, and ease of maintenance.

#### Diagram Types Used

This documentation utilizes the following Mermaid.js diagram types:

1. **Flowchart** - System architecture, component relationships
2. **Sequence Diagram** - Data flows, API interactions, user journeys
3. **Entity Relationship Diagram** - Database schema
4. **Graph/Network Diagram** - Infrastructure topology, server connections
5. **State Diagram** - Authentication flows, session management
6. **Class Diagram** - Service layer structure (when needed)

#### Syntax Examples

##### Basic Flowchart
```mermaid
graph TD
    A[User] -->|HTTPS| B[NPM Proxy]
    B -->|Port 5000| C[Flask App]
    C -->|Query| D[(PostgreSQL)]
```

##### Sequence Diagram
```mermaid
sequenceDiagram
    participant User
    participant Flask
    participant Gemini
    User->>Flask: POST /api/chat
    Flask->>Gemini: Generate response
    Gemini-->>Flask: AI response
    Flask-->>User: JSON response
```

##### Entity Relationship Diagram
```mermaid
erDiagram
    Company ||--o{ User : "has"
    Company ||--o{ CompanyNews : "mentioned in"
    User ||--o{ ChatMessage : "sends"
```

##### Network Topology
```mermaid
graph LR
    Internet((Internet)) -->|HTTPS| NPM[NPM Proxy<br/>10.22.68.250:443]
    NPM -->|Port 5000| Flask[Flask App<br/>10.22.68.249:5000]
    Flask -->|Port 5432| DB[(PostgreSQL<br/>10.22.68.249:5432)]
```

#### How to View and Edit Diagrams

##### Viewing on GitHub
- Mermaid diagrams render automatically in GitHub's Markdown preview
- No additional setup required
- Works in PR reviews and issues

##### Local Editing Tools

**VS Code Extensions:**
- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
- [Mermaid Editor](https://marketplace.visualstudio.com/items?itemName=tomoyukim.vscode-mermaid-editor)

**Online Editors:**
- [Mermaid Live Editor](https://mermaid.live/) - Official online editor
- [Mermaid Chart](https://www.mermaidchart.com/) - Advanced editor with collaboration

**Command Line:**
```bash
# Install Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# Generate PNG from markdown
mmdc -i diagram.md -o diagram.png
```

##### Local Preview in Browser
Create an HTML file with Mermaid script:
```html
<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <div class="mermaid">
    graph TD
      A[Start] --> B[End]
  </div>
</body>
</html>
```

#### Best Practices

**1. Diagram Complexity**
- Keep diagrams focused on one aspect (don't combine flows and infrastructure)
- Use multiple simple diagrams instead of one complex diagram
- Aim for 5-15 nodes per diagram maximum

**2. Naming Conventions**
- Use descriptive node labels: `[Flask App]` not `[App]`
- Include IPs/ports in infrastructure diagrams: `[Server<br/>10.22.68.249:5000]`
- Use consistent colors/styling across related diagrams

**3. Comments and Documentation**
```mermaid
%% This diagram shows the HTTP request flow through NPM proxy
%% Critical: NPM must forward to port 5000, NOT port 80
graph LR
    User -->|HTTPS 443| NPM
    NPM -->|HTTP 5000| Flask
```

**4. Version Control**
- Keep each diagram in its own file
- Use meaningful commit messages when updating diagrams
- Include "why" in commit messages (not just "updated diagram")

**5. Accessibility**
- Provide alt text descriptions for diagrams
- Use high contrast colors
- Include text descriptions for complex flows

#### Common Gotchas

**Issue 1: Diagram Not Rendering**
```markdown
<!-- Wrong: Missing language identifier -->
```
graph TD
    A --> B
```

<!-- Correct: Use 'mermaid' identifier -->
```mermaid
graph TD
    A --> B
```
```

**Issue 2: Special Characters in Labels**
```mermaid
%% Wrong: A["User says "hello""]  (unescaped quotes break syntax)

%% Correct: Use single quotes or escape
graph LR
    A['User says "hello"']
    B["User says 'hello'"]
```

**Issue 3: Line Breaks in Nodes**
```mermaid
%% Use <br/> for line breaks in labels
graph TD
    A[Flask App<br/>10.22.68.249<br/>Port 5000]
    B[PostgreSQL<br/>10.22.68.249<br/>Port 5432]
    A --> B
```

#### Diagram Style Guide

To maintain consistency across all architecture documentation:

```mermaid
%%{init: {'theme':'default', 'themeVariables': { 'fontSize':'16px'}}}%%
graph TD
    %% External systems - rounded boxes
    Ext((External<br/>System))

    %% Our services - rectangles
    Service[Our Service]

    %% Databases - cylinder
    DB[(Database)]

    %% Decision points - diamond (implicit in flowchart)
    Service -->|Success| DB
    Service -->|Failure| Ext

    %% Styling
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px
    classDef database fill:#bfb,stroke:#333,stroke-width:2px

    class Ext external
    class Service internal
    class DB database
```

#### Resources

- [Mermaid.js Official Documentation](https://mermaid.js.org/)
- [Mermaid Syntax Reference](https://mermaid.js.org/intro/syntax-reference.html)
- [C4 Model for Architecture](https://c4model.com/) - Our structural approach
- [Mermaid Cheat Sheet](https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/)

#### Alternative Tools Considered

**PlantUML** - Powerful but requires Java runtime, less GitHub-friendly
**Draw.io** - Visual editing is nice but binary/XML files don't diff well in Git
**Lucidchart** - Professional but proprietary, requires subscription
**Visio** - Industry standard but Windows-only, expensive, binary format
**Graphviz** - Lower-level, steeper learning curve
**Excalidraw** - Great for sketching but JSON format, not text-friendly

All alternatives were rejected in favor of Mermaid.js due to its superior version control integration and zero-dependency GitHub rendering.

## Frequently Asked Questions

### General Questions

**Q: Where do I start if I'm new to the codebase?**
A: Start with the [Quick Start](#quick-start) section above, which provides role-specific learning paths.

**Q: What's the most critical thing I need to know?**
A: The NPM proxy MUST forward to port 5000, not port 80. See [Critical Configurations](08-critical-configurations.md) and the [Incident Report](../INCIDENT_REPORT_20260102.md).

**Q: How often is this documentation updated?**
A: Architecture diagrams should be updated whenever significant changes are made to the system. See the date at the bottom of each document.

### Technical Questions

**Q: Why Mermaid.js instead of Draw.io or Visio?**
A: Mermaid.js is text-based, version control-friendly, and renders natively in GitHub. See [Diagram Format and Tools](#diagram-format-and-tools) for full comparison.

**Q: How do I view these diagrams locally?**
A: Use VS Code with Mermaid extensions, or paste the code into [Mermaid Live Editor](https://mermaid.live/). See [How to View and Edit Diagrams](#how-to-view-and-edit-diagrams).

**Q: Can I export diagrams to PNG/PDF?**
A: Yes, use `@mermaid-js/mermaid-cli` or online editors like mermaid.live. See [Command Line](#command-line) section.

**Q: Where are the actual code files?**
A: This is architecture documentation only. Code is in the root directory: `app.py`, `database.py`, `templates/`, etc.

### Operational Questions

**Q: How do I troubleshoot a production issue?**
A: Start with [HTTP Request Flow](flows/06-http-request-flow.md) for routing issues, or [Network Topology](07-network-topology.md) for infrastructure issues. Full troubleshooting guide coming soon (11-troubleshooting-guide.md).

**Q: How do I deploy changes to production?**
A: See [Deployment Architecture](03-deployment-architecture.md) for the complete Git-based deployment workflow.

**Q: What are the backup and recovery procedures?**
A: See [Critical Configurations](08-critical-configurations.md#backup-and-recovery-locations) for backup locations and disaster recovery procedures.

## Documentation Coverage

### Completed Documentation (9 documents)

✅ **High-Level Architecture** (3/3)
- System Context, Container Diagram, Deployment Architecture

✅ **Component Architecture** (3/3)
- Flask Components, Database Schema, External Integrations

✅ **Data Flows** (6/6)
- Authentication, Search, AI Chat, SEO Audit, News Monitoring, HTTP Request

✅ **Network & Security** (3/3)
- Network Topology, Critical Configurations, Security Architecture

### Planned Documentation (3 documents)

📋 **Reference Documentation** (0/3)
- API Endpoints Reference
- Troubleshooting Guide
- Maintenance Procedures

### Documentation Metrics

- **Total Documents:** 9 completed, 3 planned
- **Total Size:** ~480KB of documentation
- **Diagrams:** 30+ Mermaid diagrams
- **Coverage:** ~75% complete

## Quick Reference Card

### Emergency Contacts
- **System Owner:** Norda Biznes Association
- **Primary Developer:** See CLAUDE.md
- **Infrastructure:** INPI (skills: proxmox-manager, dns-manager, npm-manager)

### Quick Commands
```bash
# Check application health
curl -I https://nordabiznes.pl/health

# Restart application (on NORDABIZ-01)
sudo systemctl restart nordabiznes

# View application logs
sudo journalctl -u nordabiznes -f

# Check database status
sudo systemctl status postgresql

# Deploy updates (after git push)
ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes"
```

### Key File Locations
- **Application:** `/var/www/nordabiznes/`
- **Environment:** `/var/www/nordabiznes/.env`
- **Logs:** `/var/log/nordabiznes/` (check systemd journal)
- **Database:** PostgreSQL on 10.22.68.249:5432
- **Backups:** Proxmox Backup Server (VM snapshots)

## Quick Links

### Documentation
- [Main Project Documentation (CLAUDE.md)](../../CLAUDE.md)
- [Incident Reports](../INCIDENT_REPORT_20260102.md)
- [Database Schema SQL](../../database/schema.sql)

### Tools & Services
- **Production:** https://nordabiznes.pl
- **NPM Admin:** https://10.22.68.250:81 (admin panel)
- **Gitea:** https://10.22.68.180:3000/maciejpi/nordabiz
- **GitHub:** https://github.com/pienczyn/nordabiz

### External Resources
- [Mermaid.js Documentation](https://mermaid.js.org/)
- [C4 Model](https://c4model.com/)
- [Flask Documentation](https://flask.palletsprojects.com/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

## Contributing

When updating the codebase, please maintain architecture documentation:

1. **Before Major Changes:**
   - Review affected architecture diagrams
   - Plan updates needed to documentation
   - Include documentation tasks in your work estimate

2. **During Development:**
   - Update diagrams as you make structural changes
   - Add inline comments referencing architecture docs
   - Document any new external integrations

3. **After Completion:**
   - Verify all affected diagrams are updated
   - Include architecture updates in PR description
   - Update "Last Updated" date in modified documents

4. **For New Features:**
   - Add new data flow diagrams if needed
   - Update system context for new external integrations
   - Add new routes to Flask components documentation

See [MAINTENANCE.md](./MAINTENANCE.md) *(planned)* for detailed procedures.

## Maintenance

This documentation is a living resource that must evolve with the codebase.

### Update Frequency
- **Critical configurations:** Update immediately when changed
- **Component diagrams:** Update when adding/removing major components
- **Data flows:** Update when user journeys change significantly
- **Infrastructure:** Update when servers/networks change

### Maintenance Checklist
See [MAINTENANCE.md](./MAINTENANCE.md) *(planned)* for complete maintenance guidelines.

---

## Document Status

**Version:** 1.0.0
**Last Updated:** 2026-01-10
**Status:** ✅ Core documentation complete (9/12 documents)
**Coverage:** High-level architecture, components, flows, network, security

**Completion Status:**
- ✅ Phase 1: Research and Analysis (100%)
- ✅ Phase 2: Architecture Documentation Structure (100%)
- ✅ Phase 3: High-Level Architecture Diagrams (100%)
- ✅ Phase 4: Component Architecture Diagrams (100%)
- ✅ Phase 5: Data Flow Documentation (100%)
- ✅ Phase 6: Network and Security Documentation (100%)
- 🔄 Phase 7: Integration and Reference Documentation (25% - master overview complete)
- 📋 Phase 8: Review and Validation (pending)

**Next Steps:**
1. Create API Endpoints Reference (10-api-endpoints.md)
2. Create Troubleshooting Guide (11-troubleshooting-guide.md)
3. Create Maintenance Guide (MAINTENANCE.md)
4. Update CLAUDE.md with architecture doc references
5. Validate all diagrams render correctly
6. Cross-check documentation against code

---

*This master architecture overview document serves as the entry point to comprehensive technical documentation for the Nordabiz Platform. For questions or suggestions, please contact the development team or open an issue in the repository.*