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)

Quick Start

For New Developers

Start here: System Context Diagram → Container Diagram → Flask Components

Learn data flows: Authentication Flow → Search Flow → AI Chat Flow

Critical warnings: Critical Configurations - Must read NPM proxy section!

For Operations/DevOps

Infrastructure: Deployment Architecture → Network Topology → Critical Configurations

Troubleshooting: HTTP Request Flow - Covers the infamous port 5000 vs 80 redirect loop

Security: Security Architecture - Complete security model

For System Architects

High-level overview: System Context → Container Diagram → External Integrations

Data model: Database Schema - 36 tables, 11 domains

Complete flows: See all 6 flow diagrams in flows/ directory

Documentation Map

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	C4 Level 1 - System boundary, external actors, integrations	14KB	Actors (Members, Visitors, Admins), 8 external systems, data flows
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	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	Flask app components - routes, services, models	55KB	90+ routes, 7 services, 36 models, request handling
05-database-schema.md	Database ERD - entities, relationships, constraints	38KB	36 tables, 11 domains, 45+ relationships, indexes
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	User registration, login, email verification, password reset	27KB	Flask-Login, session mgmt, token security, access control
flows/02-search-flow.md	Company search - NIP lookup, FTS, fuzzy matching	36KB	SearchService, synonyms, scoring, AI integration
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	SEO auditing - PageSpeed API, on-page analysis, scoring	38KB	Admin dashboard, batch processing, quota management
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	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	Network layout - Fortigate, DMZ, internal network	38KB	6 zones, IP addressing, DNS, routing, health checks
08-critical-configurations.md	Critical settings - NPM, ports, SSL, systemd ⚠️ Critical!	35KB	Port mappings, .env vars, database config, backup
09-security-architecture.md	Security model - zones, threats, controls, compliance	60KB	5 trust zones, STRIDE analysis, RBAC, OWASP Top 10

Reference Documentation

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

Architecture at a Glance

System Overview Diagram

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 - 57.128.200.27"
        Flask[Flask/Gunicorn<br/>:5000 HTTP<br/>90+ routes, 7 services]
        Scripts[Background Scripts<br/>SEO, Social, News]
    end

    subgraph "Data Zone - 57.128.200.27"
        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 | HTTP Request Flow | Critical Configurations

⚠️ Database Access

PostgreSQL only accepts connections from localhost (127.0.0.1) for security. All scripts must connect via localhost, not the external IP 57.128.200.27.

See: Critical Configurations

⚠️ 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

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

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

Sequence Diagram

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

erDiagram
    Company ||--o{ User : "has"
    Company ||--o{ CompanyNews : "mentioned in"
    User ||--o{ ChatMessage : "sends"

Network Topology

graph LR
    Internet((Internet)) -->|HTTPS| NPM[NPM Proxy<br/>10.22.68.250:443]
    NPM -->|Port 5000| Flask[Flask App<br/>57.128.200.27:5000]
    Flask -->|Port 5432| DB[(PostgreSQL<br/>57.128.200.27: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
• Mermaid Editor

Online Editors:

• Mermaid Live Editor - Official online editor
• Mermaid Chart - Advanced editor with collaboration

Command Line:

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

<!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/>57.128.200.27:5000]
• Use consistent colors/styling across related diagrams

3. Comments and Documentation

%% 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

<!-- 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

%% Use <br/> for line breaks in labels
graph TD
    A[Flask App<br/>57.128.200.27<br/>Port 5000]
    B[PostgreSQL<br/>57.128.200.27<br/>Port 5432]
    A --> B

Diagram Style Guide

To maintain consistency across all architecture documentation:

%%{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
• Mermaid Syntax Reference
• C4 Model for Architecture - Our structural approach
• 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 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 and the Incident Report.

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 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. See 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 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 for routing issues, or Network Topology for infrastructure issues. Full troubleshooting guide coming soon (11-troubleshooting-guide.md).

Q: How do I deploy changes to production? A: See Deployment Architecture for the complete Git-based deployment workflow.

Q: What are the backup and recovery procedures? A: See Critical Configurations 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

Reference Documentation (3 documents)

✅ Reference Documentation (3/3)

• API Endpoints Reference
• Troubleshooting Guide
• Maintenance Procedures

Documentation Metrics

• Total Documents: 12 completed
• Total Size: ~480KB of documentation
• Diagrams: 30+ Mermaid diagrams
• Coverage: ~95% 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

# 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@57.128.200.27 "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 57.128.200.27:5432
• Backups: Proxmox Backup Server (VM snapshots)

Quick Links

Documentation

• Main Project Documentation (CLAUDE.md)
• Incident Reports
• 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
• C4 Model
• Flask Documentation
• PostgreSQL Documentation

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 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 for complete maintenance guidelines.

---

Document Status

Version: 1.0.0 Last Updated: 2026-02-09 Status: ✅ All documentation complete (12/12 documents) Coverage: High-level architecture, components, flows, network, security, reference

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 (100%)
• ✅ Phase 8: Review and Validation (100%)

---

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.