maciejpi/nordabiz
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: Add complete architecture documentation with C4 diagrams

Browse Source 
- System Context diagram (C4 Level 1)
- Container diagram (C4 Level 2)
- Flask component diagram (C4 Level 3)
- Deployment architecture with NPM proxy
- Database schema (PostgreSQL)
- External integrations (Gemini AI, Brave Search, PageSpeed)
- Network topology (INPI infrastructure)
- Security architecture
- API endpoints reference
- Troubleshooting guide
- Data flow diagrams (auth, search, AI chat, SEO audit, news monitoring)

All diagrams use Mermaid.js and render automatically on GitHub.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Maciej Pienczyn 2026-01-10 12:40:52 +01:00
parent 70382b4e52
commit fa4fb92390
20 changed files with 26241 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
CLAUDE.md
View File

@ -24,9 +24,77 @@ nordabiz/
│ ├── ai_quality_evaluator.py
│ ├── ai_quality_test_cases.json
│ └── results/ # Wyniki testów (JSON)
└── scripts/ # Narzędzia Node.js
├── scripts/ # Narzędzia Node.js
└── docs/ # Dokumentacja
├── architecture/ # Architektura systemu (diagramy, przepływy)
└── INCIDENT_REPORT_20260102.md
```
## Dokumentacja architektury
Kompletna dokumentacja architektury systemu dostępna w katalogu `docs/architecture/`.
### 📚 Dokumenty główne
| Dokument | Opis |
|----------|------|
| [**README.md**](docs/architecture/README.md) | Przegląd całej dokumentacji architektury (start tutaj!) |
| [01-system-context.md](docs/architecture/01-system-context.md) | Kontekst systemu (C4 Level 1) - aktorzy i systemy zewnętrzne |
| [02-container-diagram.md](docs/architecture/02-container-diagram.md) | Diagram kontenerów (C4 Level 2) - Flask, PostgreSQL, NPM, API |
| [03-deployment-architecture.md](docs/architecture/03-deployment-architecture.md) | Architektura wdrożenia - serwery, porty, infrastruktura |
| [04-flask-components.md](docs/architecture/04-flask-components.md) | Komponenty Flask - routes, services, models |
| [05-database-schema.md](docs/architecture/05-database-schema.md) | Schemat bazy danych - 36 tabel, relacje, indeksy |
| [06-external-integrations.md](docs/architecture/06-external-integrations.md) | Integracje API - Gemini, Brave, PageSpeed, Places, KRS, MS Graph |
| [07-network-topology.md](docs/architecture/07-network-topology.md) | Topologia sieci - Fortigate, NPM, routing, DNS |
| [08-critical-configurations.md](docs/architecture/08-critical-configurations.md) | Konfiguracje krytyczne - NPM proxy, SSL, PostgreSQL, systemd |
| [09-security-architecture.md](docs/architecture/09-security-architecture.md) | Architektura bezpieczeństwa - RBAC, CSRF, strefy zaufania |
| [10-api-endpoints.md](docs/architecture/10-api-endpoints.md) | Referencja API - 90+ endpointów, auth, rate limiting |
### 🔄 Przepływy danych (Data Flows)
| Przepływ | Opis |
|----------|------|
| [01-authentication-flow.md](docs/architecture/flows/01-authentication-flow.md) | Rejestracja, login, reset hasła, sesje |
| [02-search-flow.md](docs/architecture/flows/02-search-flow.md) | Wyszukiwanie firm - synonimy, FTS, fuzzy matching |
| [03-ai-chat-flow.md](docs/architecture/flows/03-ai-chat-flow.md) | Chat AI - kontekst, Gemini API, tracking kosztów |
| [04-seo-audit-flow.md](docs/architecture/flows/04-seo-audit-flow.md) | Audyt SEO - PageSpeed API, analiza on-page/technical |
| [05-news-monitoring-flow.md](docs/architecture/flows/05-news-monitoring-flow.md) | Monitoring newsów - Brave API, filtrowanie AI, moderacja |
| [06-http-request-flow.md](docs/architecture/flows/06-http-request-flow.md) | Przepływ HTTP - user → NPM → Flask → PostgreSQL |
### ⚡ Szybki start
**Dla deweloperów:**
- Zacznij od [architecture/README.md](docs/architecture/README.md)
- Przejrzyj [04-flask-components.md](docs/architecture/04-flask-components.md) i [05-database-schema.md](docs/architecture/05-database-schema.md)
- Sprawdź przepływy w [flows/](docs/architecture/flows/) dla zrozumienia logiki biznesowej
**Dla DevOps:**
- [03-deployment-architecture.md](docs/architecture/03-deployment-architecture.md) - infrastruktura
- [07-network-topology.md](docs/architecture/07-network-topology.md) - sieć i routing
- [08-critical-configurations.md](docs/architecture/08-critical-configurations.md) - **KRYTYCZNE!** NPM port 5000
**Dla architektów:**
- [01-system-context.md](docs/architecture/01-system-context.md) - widok wysokopoziomowy
- [02-container-diagram.md](docs/architecture/02-container-diagram.md) - komponenty główne
- [06-external-integrations.md](docs/architecture/06-external-integrations.md) - zależności zewnętrzne
### 🛡️ Kluczowe ostrzeżenia z dokumentacji
**NPM Proxy (KRYTYCZNE!):**
- Port forward **MUSI być 5000**, NIE 80!
- Szczegóły: [08-critical-configurations.md](docs/architecture/08-critical-configurations.md#npm-reverse-proxy)
- Incydent: [INCIDENT_REPORT_20260102.md](docs/INCIDENT_REPORT_20260102.md)
**PostgreSQL:**
- Skrypty używają `localhost (127.0.0.1)`, NIE `10.22.68.249`
- Szczegóły: [08-critical-configurations.md](docs/architecture/08-critical-configurations.md#database-configuration)
**API Limity:**
- Gemini: 1,500 req/dzień (free tier)
- PageSpeed: 25,000 req/dzień
- Brave Search: 2,000 req/miesiąc
- Szczegóły: [06-external-integrations.md](docs/architecture/06-external-integrations.md)
## Technologie
| Warstwa | Technologia |

415
docs/architecture/01-system-context.md Normal file
View File

@ -0,0 +1,415 @@
# System Context Diagram (C4 Level 1)
**Document Version:** 1.0
**Last Updated:** 2026-01-10
**Status:** Production LIVE
**Diagram Type:** C4 Model - Level 1 (System Context)
---
## Overview
This diagram shows the **highest-level view** of the Norda Biznes Hub system and its external actors. It illustrates:
- **Who uses the system** (users, administrators)
- **What external systems** the platform integrates with
- **Primary relationships** between actors and the system
**Abstraction Level:** System Context (C4 Level 1)
**Audience:** All stakeholders (technical and non-technical)
**Purpose:** Understanding system boundaries and external dependencies
---
## System Context Diagram
```mermaid
graph TB
%% Define external actors (people)
Members["👥 Norda Biznes Members<br/>(Registered Users)<br/>80 member companies"]
Visitors["👤 Website Visitors<br/>(Anonymous Users)<br/>Public access"]
Admins["👨‍💼 System Administrators<br/>(Platform Managers)<br/>Content moderation & audits"]
%% Define the main system
NordaBiz["🏢 NORDA BIZNES HUB<br/>Business Directory & Networking Platform<br/><br/>Flask web application providing:<br/>- Company directory & profiles<br/>- AI-powered search & chat<br/>- Social media & SEO auditing<br/>- Community features (forum, events, messaging)"]
%% Define external systems
Gemini["🤖 Google Gemini AI API<br/>AI chat responses,<br/>content analysis,<br/>image recognition"]
BraveAPI["🔍 Brave Search API<br/>News monitoring,<br/>social media discovery"]
PageSpeed["📊 Google PageSpeed<br/>Insights API<br/>SEO & performance auditing"]
Places["📍 Google Places API<br/>(Business Profile)<br/>Reviews, ratings,<br/>business info"]
KRS["🏛️ KRS Open API<br/>(Polish Company Registry)<br/>Company verification,<br/>legal data"]
MSGraph["📧 Microsoft Graph API<br/>Email notifications<br/>via Outlook"]
ALEO["🌐 ALEO.com<br/>Company data scraping<br/>(NIP verification)"]
Rejestr["🔗 rejestr.io<br/>Company connections,<br/>board members,<br/>shareholders"]
%% User interactions with system
Members -->|"Browse companies<br/>Use AI chat<br/>Participate in forum<br/>Manage profile<br/>Send messages"| NordaBiz
Visitors -->|"Search companies<br/>View public profiles<br/>Access audit reports"| NordaBiz
Admins -->|"Moderate content<br/>Run SEO audits<br/>Manage users<br/>Track analytics"| NordaBiz
%% System interactions with external services
NordaBiz -->|"Generate chat responses<br/>Analyze images<br/>AI recommendations"| Gemini
NordaBiz -->|"Search news mentions<br/>Discover social profiles"| BraveAPI
NordaBiz -->|"Audit website SEO<br/>Performance metrics"| PageSpeed
NordaBiz -->|"Fetch business reviews<br/>Google My Business data"| Places
NordaBiz -->|"Verify company data<br/>Fetch KRS records"| KRS
NordaBiz -->|"Send email notifications<br/>OAuth authentication"| MSGraph
NordaBiz -->|"Verify NIP numbers<br/>Company legal status"| ALEO
NordaBiz -->|"Analyze company connections<br/>Board member relationships"| Rejestr
%% Styling
classDef systemStyle fill:#1168bd,stroke:#0b4884,color:#ffffff,stroke-width:4px
classDef personStyle fill:#08427b,stroke:#052e56,color:#ffffff,stroke-width:2px
classDef externalStyle fill:#999999,stroke:#666666,color:#ffffff,stroke-width:2px
class NordaBiz systemStyle
class Members,Visitors,Admins personStyle
class Gemini,BraveAPI,PageSpeed,Places,KRS,MSGraph,ALEO,Rejestr externalStyle
```
---
## Actor Descriptions
### 👥 Norda Biznes Members (Registered Users)
**Count:** 80 member companies
**Authentication:** Required (email/password)
**Capabilities:**
- Browse and search company directory
- Use AI chat assistant for company recommendations
- Create and manage company profile
- Participate in community forum
- Send private messages to other members
- RSVP to events
- Post classified ads
**Representative Users:**
- PIXLAB Sp. z o.o.
- PORTA KMI Poland
- GRAAL S.A.
- Hotel SPA Wieniawa
- Chopin Telewizja Kablowa
---
### 👤 Website Visitors (Anonymous Users)
**Authentication:** None
**Capabilities:**
- Search company directory
- View public company profiles
- Access public audit reports (SEO, Social Media, GBP, IT)
- View news/announcements
- Browse events calendar
**Access Restrictions:**
- Cannot view full contact details
- Cannot access AI chat
- Cannot participate in forum
- Cannot send messages
---
### 👨‍💼 System Administrators
**Count:** 2-3 admin accounts
**Authentication:** Required with `is_admin=True` flag
**Capabilities:**
- Moderate forum posts and news submissions
- Approve/reject company recommendations
- Run SEO and social media audits
- Manage user accounts (activate, deactivate, promote to admin)
- Track analytics (chat usage, AI costs, user engagement)
- Manage membership fees
- Configure system settings
**Admin Test Accounts:**
- `testadmin@nordabiznes.pl`
---
## External System Descriptions
### 🤖 Google Gemini AI API
**Provider:** Google AI Studio
**Purpose:** Generative AI for chat and content analysis
**Model:** gemini-2.5-flash (primary), gemini-2.5-pro (advanced)
**Integration Points:**
- AI chat responses with company context
- Image analysis for logo/photo descriptions
- AI-powered audit recommendations (GBP audit)
- Content relevance scoring (news filtering)
**Pricing:** $0.075-$1.25 per 1M input tokens
**Rate Limit:** No strict limit (cost-limited)
**Documentation:** [Google AI Studio](https://ai.google.dev/)
---
### 🔍 Brave Search API
**Provider:** Brave Software
**Purpose:** Web search for news monitoring and social media discovery
**Integration Points:**
- News mentions of member companies
- Social media profile discovery
- Press release detection
- Award/achievement tracking
**Pricing:** Free tier - 2,000 requests/month
**Rate Limit:** 2,000 req/month
**Documentation:** [Brave Search API](https://brave.com/search/api/)
---
### 📊 Google PageSpeed Insights API
**Provider:** Google Cloud
**Purpose:** Website performance and SEO auditing
**Integration Points:**
- SEO score calculation (0-100)
- Performance metrics (Core Web Vitals)
- Accessibility auditing
- Best practices assessment
**Pricing:** Free - 25,000 queries/day
**Rate Limit:** 25,000 req/day
**API Key:** `GOOGLE_PAGESPEED_API_KEY`
**Documentation:** [PageSpeed Insights API](https://developers.google.com/speed/docs/insights/v5/get-started)
---
### 📍 Google Places API (Business Profile)
**Provider:** Google Cloud
**Purpose:** Google My Business data retrieval
**Integration Points:**
- Business reviews and ratings
- Business hours and location
- Photo gallery
- Q&A content
- Google Maps integration
**Pricing:** Pay-per-use (Places API pricing)
**Rate Limit:** Quota-based
**Documentation:** [Places API](https://developers.google.com/maps/documentation/places/web-service/overview)
---
### 🏛️ KRS Open API
**Provider:** Polish Ministry of Justice
**Purpose:** Company registry data verification
**Integration Points:**
- Company legal verification (KRS number)
- Corporate structure data
- Board member information
- Share capital details
- Legal form validation
**Pricing:** Free (public data)
**Rate Limit:** Not strictly enforced
**Base URL:** `https://api-krs.ms.gov.pl/`
**Documentation:** [KRS API Docs](https://api-krs.ms.gov.pl/)
---
### 📧 Microsoft Graph API
**Provider:** Microsoft
**Purpose:** Email notifications via Outlook/Office 365
**Integration Points:**
- Send email notifications (verification, alerts)
- OAuth 2.0 authentication flow
- User mailbox access (delegated permissions)
**Authentication:** OAuth 2.0 with client credentials
**Pricing:** Included with Office 365 subscription
**Rate Limit:** Throttling based on tenant
**Documentation:** [Microsoft Graph](https://learn.microsoft.com/en-us/graph/overview)
---
### 🌐 ALEO.com
**Provider:** ALEO (Third-party service)
**Purpose:** NIP number verification and company data
**Integration Method:** Web scraping (Playwright)
**Integration Points:**
- NIP number validation
- Company legal status check
- Basic company information
**Authentication:** None (public web scraping)
**Rate Limit:** Self-imposed (polite scraping)
**Reliability:** Medium (subject to website changes)
---
### 🔗 rejestr.io
**Provider:** rejestr.io (Public company registry aggregator)
**Purpose:** Company relationship analysis
**Integration Method:** Web scraping (Playwright)
**Integration Points:**
- Board member identification
- Shareholder/ownership structure
- Cross-company relationships (who owns what)
- Beneficial owners
**Authentication:** None (public data)
**Rate Limit:** Self-imposed (polite scraping)
**Use Case:** Networking insights (who knows who in Norda Biznes)
---
## System Boundaries
### What is INSIDE the system boundary:
✅ Flask web application (app.py)
✅ PostgreSQL database
✅ Service layer (gemini_service.py, search_service.py, etc.)
✅ HTML templates and static assets
✅ Background audit scripts (scripts/*)
✅ Authentication and authorization logic
### What is OUTSIDE the system boundary:
❌ Nginx Proxy Manager (NPM) - Infrastructure
❌ Google Gemini AI - External API
❌ Brave Search - External API
❌ PageSpeed Insights - External API
❌ KRS API - External API
❌ Microsoft Graph - External API
❌ ALEO.com - External data source
❌ rejestr.io - External data source
**Note:** While NPM is critical infrastructure, it's considered external to the *application* boundary at this level of abstraction. It will be included in the Container diagram (C4 Level 2).
---
## Key Data Flows (High-Level)
### 1. Company Search Flow
```
Visitor → NordaBiz Hub → PostgreSQL FTS Search → Results
└→ Gemini AI (if chat-based)
```
### 2. AI Chat Flow
```
Member → NordaBiz Hub → Search Service (find relevant companies)
→ Gemini AI (generate response with context)
→ Member (AI response)
```
### 3. SEO Audit Flow
```
Admin → NordaBiz Hub → PageSpeed API → Audit data
→ PostgreSQL (store results)
→ Admin Dashboard (display)
```
### 4. News Monitoring Flow (Planned)
```
Background Job → Brave Search API → News articles
→ Gemini AI (relevance scoring)
→ PostgreSQL (pending moderation)
→ Admin (approve/reject)
→ Company Profile (display)
```
### 5. Email Notification Flow
```
System Event → NordaBiz Hub → MS Graph API → Outlook
→ User Email Inbox
```
---
## Security Considerations
### Authentication
- **Users:** Email/password (Flask-Login session)
- **External APIs:** API keys stored in `.env` file (never committed to git)
- **MS Graph:** OAuth 2.0 client credentials flow
### Authorization
- **Public routes:** No authentication required
- **User routes:** `@login_required` decorator
- **Admin routes:** `@login_required` + `is_admin=True` check
### Rate Limiting
- **Flask app:** 200 req/day, 50 req/hour per IP
- **External APIs:** Tracked via database (gemini_usage, seo_metrics)
### Data Protection
- **Passwords:** Hashed with bcrypt
- **Sessions:** Flask session cookies (encrypted)
- **HTTPS:** Forced via NPM (SSL termination)
- **CSRF:** Flask-WTF protection enabled
---
## Deployment Environment
**Production:**
- **URL:** https://nordabiznes.pl
- **Server:** NORDABIZ-01 (10.22.68.249)
- **Proxy:** R11-REVPROXY-01 (10.22.68.250)
- **Status:** LIVE since 2025-11-23
**Development:**
- **Local:** localhost:5000 or 5001
- **Database:** PostgreSQL via Docker (localhost:5433)
---
## Related Documentation
- **Next Level:** [Container Diagram (C4 Level 2)](./02-container-diagram.md) - Shows major containers (Flask app, database, proxy, etc.)
- **Infrastructure:** [Deployment Architecture](./03-deployment-architecture.md) - Physical deployment with IPs and ports
- **Components:** [Flask Application Components](./04-flask-components.md) - Internal application structure
- **Database:** [Database Schema](./05-database-schema.md) - Entity relationships
- **External APIs:** [External Integrations](./06-external-integrations.md) - Detailed API documentation
---
## Maintenance Notes
**When to update this diagram:**
- ✏️ New external API integration added
- ✏️ New user type or role introduced
- ✏️ System boundary changes (new subsystem added)
- ✏️ Major functionality added that changes how users interact with the system
**What NOT to update here:**
- ❌ Internal code refactoring (doesn't change system boundary)
- ❌ New database tables (covered in database schema diagram)
- ❌ New Flask routes (covered in component diagram)
- ❌ Infrastructure changes (covered in deployment diagram)
**Review frequency:** Quarterly or after major feature releases
---
## Glossary
| Term | Definition |
|------|------------|
| **C4 Model** | Context, Containers, Components, Code - hierarchical architecture diagram approach |
| **System Context** | Highest level view showing system boundary and external actors |
| **Actor** | Person or external system that interacts with our system |
| **System Boundary** | Line separating what's inside our system vs. external dependencies |
| **Norda Biznes** | Business association in Wejherowo with 80 member companies |
| **NIP** | Polish tax identification number (10 digits) |
| **KRS** | Polish National Court Register (company registry) |
| **REGON** | Polish statistical identification number (9 or 14 digits) |
| **FTS** | Full-Text Search (PostgreSQL feature) |
| **NPM** | Nginx Proxy Manager (reverse proxy) |
| **GBP** | Google Business Profile (formerly Google My Business) |
---
**Document Status:** ✅ Complete
**Diagram Validated:** 2026-01-10
**Mermaid Syntax:** v10.6+
**Renders in:** GitHub, GitLab, VS Code (with Mermaid extension)

1064
docs/architecture/02-container-diagram.md Normal file
View File

File diff suppressed because it is too large Load Diff

1214
docs/architecture/03-deployment-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

1712
docs/architecture/04-flask-components.md Normal file
View File

File diff suppressed because it is too large Load Diff

1233
docs/architecture/05-database-schema.md Normal file
View File

File diff suppressed because it is too large Load Diff

1069
docs/architecture/06-external-integrations.md Normal file
View File

File diff suppressed because it is too large Load Diff

1131
docs/architecture/07-network-topology.md Normal file
View File

File diff suppressed because it is too large Load Diff

1291
docs/architecture/08-critical-configurations.md Normal file
View File

File diff suppressed because it is too large Load Diff

1827
docs/architecture/09-security-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

2869
docs/architecture/10-api-endpoints.md Normal file
View File

File diff suppressed because it is too large Load Diff

2607
docs/architecture/11-troubleshooting-guide.md Normal file
View File

File diff suppressed because it is too large Load Diff

879
docs/architecture/MAINTENANCE.md Normal file
View File

@ -0,0 +1,879 @@
# 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)

687
docs/architecture/README.md Normal file
View File

@ -0,0 +1,687 @@
# 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 2.0 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.*

874
docs/architecture/flows/01-authentication-flow.md Normal file
View File

@ -0,0 +1,874 @@
# Authentication Flow
**Document Version:** 1.0
**Last Updated:** 2026-01-10
**Status:** Production LIVE
**Flow Type:** User Authentication & Session Management
---
## Overview
This document describes the **complete authentication flow** for the Norda Biznes Hub application, covering:
- **User Registration** with email verification
- **Login** with session management
- **Email Verification** process
- **Password Reset** flow
- **Session Management** and cookies
- **Authorization Levels** and access control
**Key Technology:**
- **Authentication Framework:** Flask-Login
- **Password Hashing:** PBKDF2:SHA256 (werkzeug.security)
- **Session Storage:** Server-side session cookies
- **Email Delivery:** Microsoft Graph API (OAuth 2.0)
- **CSRF Protection:** Flask-WTF
**Security Features:**
- Email verification required before login
- Secure session cookies (HttpOnly, Secure, SameSite=Lax)
- CSRF protection on all forms
- Password strength requirements
- Input sanitization against XSS
- Rate limiting on authentication endpoints
---
## 1. User Registration Flow
### 1.1 Registration Sequence Diagram
```mermaid
sequenceDiagram
actor User
participant Browser
participant Flask as Flask App<br/>(app.py)
participant DB as PostgreSQL<br/>(users table)
participant EmailSvc as Email Service<br/>(email_service.py)
participant MSGraph as Microsoft Graph API
User->>Browser: Navigate to /register
Browser->>Flask: GET /register
Flask->>Browser: Render register.html
User->>Browser: Fill form (email, password, name, company_nip)
Browser->>Flask: POST /register
Note over Flask: CSRF token validated (automatic)
Note over Flask: Input sanitization
Flask->>Flask: validate_email(email)
Flask->>Flask: validate_password(password)<br/>(8+ chars, uppercase, lowercase, digit)
Flask->>Flask: validate NIP format (10 digits)
Flask->>DB: SELECT * FROM users WHERE email = ?
DB->>Flask: Check if exists
alt Email already exists
Flask->>Browser: Flash "Email już jest zarejestrowany"
Browser->>User: Show error message
else Email available
Flask->>DB: SELECT * FROM companies WHERE nip = ? AND status = 'active'
DB->>Flask: Company data (if NORDA member)
Flask->>Flask: generate_password_hash(password)<br/>(PBKDF2:SHA256)
Flask->>Flask: secrets.token_urlsafe(32)<br/>(verification token)
Flask->>Flask: Calculate token expiry<br/>(now + 24 hours)
Flask->>DB: INSERT INTO users<br/>(email, password_hash, name,<br/>verification_token, is_verified=FALSE,<br/>company_id, is_norda_member)
DB->>Flask: User created (id)
Flask->>EmailSvc: send_verification_email(email, token)
EmailSvc->>MSGraph: POST /users/noreply@nordabiznes.pl/sendMail<br/>(OAuth 2.0 + Bearer token)
MSGraph->>EmailSvc: 202 Accepted
Flask->>Browser: Flash "Sprawdź email"<br/>Redirect to /login
Browser->>User: Show success message
end
```
### 1.2 Registration Implementation Details
**Route:** `POST /register`
**File:** `app.py` (lines ~3077-3183)
**Rate Limit:** 5 requests per hour per IP
**Input Fields:**
- `email` (required, max 255 chars)
- `password` (required, 8+ chars with complexity requirements)
- `name` (required, max 255 chars)
- `company_nip` (required, 10 digits)
**Validation Steps:**
1. **Email validation:** Regex pattern check
2. **Password validation:**
- Minimum 8 characters
- At least 1 uppercase letter
- At least 1 lowercase letter
- At least 1 digit
3. **NIP validation:** Must be exactly 10 digits
4. **Company membership check:** NIP lookup in `companies` table
**Database Operations:**
```sql
-- Check email uniqueness
SELECT * FROM users WHERE email = ?;
-- Verify company membership
SELECT * FROM companies WHERE nip = ? AND status = 'active';
-- Create user account
INSERT INTO users (
email, password_hash, name, company_nip,
verification_token, verification_token_expires,
is_verified, is_norda_member, company_id,
created_at
) VALUES (?, ?, ?, ?, ?, ?, FALSE, ?, ?, NOW());
```
**Security Measures:**
- **CSRF Protection:** Automatic via Flask-WTF
- **Input Sanitization:** `sanitize_input()` strips HTML/malicious patterns
- **Password Hashing:** PBKDF2:SHA256 (werkzeug default)
- **Rate Limiting:** 5 attempts/hour via Flask-Limiter
- **XSS Prevention:** All user inputs sanitized
**Email Verification Token:**
- Generated via `secrets.token_urlsafe(32)` (256-bit entropy)
- Stored in `users.verification_token` column
- Expires after 24 hours
- Single-use (cleared after verification)
---
## 2. Email Verification Flow
### 2.1 Email Verification Sequence Diagram
```mermaid
sequenceDiagram
actor User
participant Email as Email Client
participant Browser
participant Flask as Flask App<br/>(app.py)
participant DB as PostgreSQL
Note over User,Email: User receives verification email
User->>Email: Open verification email
Email->>Browser: Click link:<br/>https://nordabiznes.pl/verify-email/<token>
Browser->>Flask: GET /verify-email/<token>
Flask->>Flask: Extract token from URL
Flask->>DB: SELECT * FROM users<br/>WHERE verification_token = ?<br/>AND verification_token_expires > NOW()<br/>AND is_active = TRUE
alt Token valid and not expired
DB->>Flask: User found
alt User already verified
Flask->>Browser: Flash "Email został już zweryfikowany"<br/>Redirect to /login
else User not verified yet
Flask->>DB: UPDATE users SET<br/>is_verified = TRUE,<br/>verified_at = NOW(),<br/>verification_token = NULL,<br/>verification_token_expires = NULL<br/>WHERE id = ?
DB->>Flask: Update successful
Flask->>Browser: Flash "Email zweryfikowany!<br/>Możesz się teraz zalogować"<br/>Redirect to /login
Browser->>User: Show success message
end
else Token invalid or expired
Flask->>Browser: Flash "Link weryfikacyjny<br/>jest nieprawidłowy lub wygasł"<br/>Redirect to /login
Browser->>User: Show error message
end
```
### 2.2 Email Verification Implementation Details
**Route:** `GET /verify-email/<token>`
**File:** `app.py` (lines ~3369-3405)
**Rate Limit:** None (public endpoint)
**Verification Logic:**
```python
# Query user by token
user = db.query(User).filter(
User.verification_token == token,
User.verification_token_expires > datetime.now(),
User.is_active == True
).first()
if user and not user.is_verified:
user.is_verified = True
user.verified_at = datetime.now()
user.verification_token = None
user.verification_token_expires = None
db.commit()
```
**Token Expiry:**
- Verification tokens expire after **24 hours**
- Expired tokens cannot be used
- Users can request new verification email via `/resend-verification`
**Database Schema (users table):**
```sql
verification_token VARCHAR(255) NULL
verification_token_expires TIMESTAMP NULL
is_verified BOOLEAN DEFAULT FALSE
verified_at TIMESTAMP NULL
```
---
## 3. Login Flow
### 3.1 Login Sequence Diagram
```mermaid
sequenceDiagram
actor User
participant Browser
participant Flask as Flask App<br/>(app.py)
participant FlaskLogin as Flask-Login
participant DB as PostgreSQL
participant Session as Session Cookie
User->>Browser: Navigate to /login
Browser->>Flask: GET /login
Flask->>Browser: Render login.html with CSRF token
User->>Browser: Enter email & password<br/>(optional: remember me)
Browser->>Flask: POST /login<br/>(email, password, remember, csrf_token)
Note over Flask: CSRF token validated
Flask->>DB: SELECT * FROM users WHERE email = ?
alt User not found
DB->>Flask: No user
Flask->>Browser: Flash "Nieprawidłowy email lub hasło"
Browser->>User: Show error
else User found
DB->>Flask: User data
Flask->>Flask: check_password_hash(<br/>user.password_hash,<br/>password<br/>)
alt Password invalid
Flask->>Browser: Flash "Nieprawidłowy email lub hasło"
Browser->>User: Show error
else Password valid
alt User not active
Flask->>Browser: Flash "Konto zostało dezaktywowane"
Browser->>User: Show error
else User not verified
Flask->>Browser: Flash "Musisz potwierdzić adres email"
Browser->>User: Show error with resend link
else User active and verified
Flask->>FlaskLogin: login_user(user, remember=remember)
FlaskLogin->>Session: Set session cookie<br/>(secure, httponly, samesite=Lax)
Session->>Browser: Store session cookie
Flask->>DB: UPDATE users SET last_login = NOW() WHERE id = ?
DB->>Flask: Update successful
Flask->>Browser: Redirect to /dashboard<br/>(or 'next' URL if specified)
Browser->>User: Show dashboard
end
end
end
```
### 3.2 Login Implementation Details
**Route:** `POST /login`
**File:** `app.py` (lines ~3184-3240)
**Rate Limit:**
- **Development:** 1000 requests per hour
- **Production:** 5 requests per hour per IP
**Login Validation Steps:**
1. Check email exists in database
2. Verify password hash matches
3. Check `is_active = TRUE`
4. Require `is_verified = TRUE`
5. Create session via Flask-Login
6. Update `last_login` timestamp
**Session Configuration:**
```python
# app.py session settings (lines ~161-168)
app.config['SECRET_KEY'] = os.getenv('SECRET_KEY')
app.config['PERMANENT_SESSION_LIFETIME'] = timedelta(days=7)
app.config['SESSION_COOKIE_SECURE'] = True # HTTPS only in production
app.config['SESSION_COOKIE_HTTPONLY'] = True # No JS access
app.config['SESSION_COOKIE_SAMESITE'] = 'Lax' # CSRF protection
```
**Flask-Login Configuration:**
```python
# app.py Flask-Login setup (lines ~192-196)
login_manager = LoginManager()
login_manager.init_app(app)
login_manager.login_view = 'login'
login_manager.login_message = 'Zaloguj się, aby uzyskać dostęp do tej strony.'
```
**User Loader Function:**
```python
@login_manager.user_loader
def load_user(user_id):
"""Load user from database for Flask-Login"""
db = SessionLocal()
try:
return db.query(User).get(int(user_id))
except:
return None
finally:
db.close()
```
**Remember Me Functionality:**
- When enabled: Session cookie persists for **7 days**
- When disabled: Session cookie expires when browser closes
- Implemented via Flask-Login's `login_user(user, remember=True/False)`
**Next URL Redirect:**
```python
# Prevent open redirect vulnerability
next_page = request.args.get('next')
if next_page and not next_page.startswith('/'):
next_page = None
return redirect(next_page or url_for('dashboard'))
```
---
## 4. Session Management
### 4.1 Session Lifecycle
```mermaid
stateDiagram-v2
[*] --> Anonymous: User visits site
Anonymous --> Authenticated: Successful login
Authenticated --> Authenticated: Normal activity
Authenticated --> Anonymous: Logout
Authenticated --> Anonymous: Session expires (7 days)
Authenticated --> Anonymous: User deactivated
Anonymous --> [*]
```
### 4.2 Session Cookie Details
**Cookie Name:** `session` (Flask default)
**Storage:** Server-side (encrypted session data)
**Attributes:**
- `Secure` = True (HTTPS only in production)
- `HttpOnly` = True (prevents XSS cookie theft)
- `SameSite` = Lax (CSRF protection)
- `Max-Age` = 7 days (with remember me)
**Session Data Stored:**
- User ID (for user loader)
- CSRF token (automatic via Flask-WTF)
- Login timestamp
- Remember me flag
**Session Security:**
- Session cookie is **signed** with `SECRET_KEY`
- Session data is **encrypted** (Flask built-in)
- Session is **regenerated** on login (prevents session fixation)
- Session is **cleared** on logout
---
## 5. Logout Flow
### 5.1 Logout Sequence Diagram
```mermaid
sequenceDiagram
actor User
participant Browser
participant Flask as Flask App
participant FlaskLogin as Flask-Login
participant Session as Session Cookie
User->>Browser: Click "Wyloguj" button
Browser->>Flask: GET /logout
Note over Flask: @login_required decorator<br/>verifies user is authenticated
Flask->>FlaskLogin: logout_user()
FlaskLogin->>Session: Clear session data
Session->>Browser: Delete session cookie
Flask->>Browser: Flash "Wylogowano pomyślnie"<br/>Redirect to /
Browser->>User: Show homepage (logged out)
```
### 5.2 Logout Implementation Details
**Route:** `GET /logout`
**File:** `app.py` (lines ~3242-3248)
**Authentication:** Required (`@login_required`)
**Implementation:**
```python
@app.route('/logout')
@login_required
def logout():
"""User logout"""
logout_user() # Flask-Login clears session
flash('Wylogowano pomyślnie.', 'success')
return redirect(url_for('index'))
```
**What Happens on Logout:**
1. Flask-Login calls `logout_user()`
2. Session cookie is deleted
3. User object is removed from `current_user`
4. Browser redirected to homepage
5. All subsequent requests are anonymous
---
## 6. Password Reset Flow
### 6.1 Password Reset Sequence Diagram
```mermaid
sequenceDiagram
actor User
participant Browser
participant Flask as Flask App
participant DB as PostgreSQL
participant EmailSvc as Email Service
participant MSGraph as Microsoft Graph API
Note over User,Browser: Phase 1: Request Reset
User->>Browser: Navigate to /forgot-password
Browser->>Flask: GET /forgot-password
Flask->>Browser: Render forgot_password.html
User->>Browser: Enter email address
Browser->>Flask: POST /forgot-password (email)
Flask->>Flask: validate_email(email)
Flask->>DB: SELECT * FROM users<br/>WHERE email = ? AND is_active = TRUE
alt User found
DB->>Flask: User data
Flask->>Flask: secrets.token_urlsafe(32)<br/>(generate reset token)
Flask->>Flask: Calculate expiry (now + 1 hour)
Flask->>DB: UPDATE users SET<br/>reset_token = ?,<br/>reset_token_expires = ?<br/>WHERE email = ?
DB->>Flask: Update successful
Flask->>EmailSvc: send_password_reset_email(email, token)
EmailSvc->>MSGraph: POST /users/noreply@nordabiznes.pl/sendMail
MSGraph->>EmailSvc: 202 Accepted
Flask->>Browser: Flash "Sprawdź email"<br/>Redirect to /login
Browser->>User: Show message
else User not found
Note over Flask: Still show success message<br/>(prevent email enumeration)
Flask->>Browser: Flash "Sprawdź email"<br/>Redirect to /login
Browser->>User: Show message
end
Note over User,Browser: Phase 2: Reset Password
User->>Browser: Click link in email:<br/>https://nordabiznes.pl/reset-password/<token>
Browser->>Flask: GET /reset-password/<token>
Flask->>DB: SELECT * FROM users<br/>WHERE reset_token = ?<br/>AND reset_token_expires > NOW()
alt Token valid
DB->>Flask: User found
Flask->>Browser: Render reset_password.html<br/>(password form)
User->>Browser: Enter new password (twice)
Browser->>Flask: POST /reset-password/<token><br/>(new_password, confirm_password)
Flask->>Flask: validate_password(new_password)
Flask->>Flask: Check passwords match
Flask->>Flask: generate_password_hash(new_password)
Flask->>DB: UPDATE users SET<br/>password_hash = ?,<br/>reset_token = NULL,<br/>reset_token_expires = NULL<br/>WHERE reset_token = ?
DB->>Flask: Update successful
Flask->>Browser: Flash "Hasło zostało zmienione"<br/>Redirect to /login
Browser->>User: Show success message
else Token invalid or expired
Flask->>Browser: Flash "Link resetowania<br/>jest nieprawidłowy lub wygasł"<br/>Redirect to /forgot-password
Browser->>User: Show error
end
```
### 6.2 Password Reset Implementation Details
**Routes:**
- `POST /forgot-password` - Request reset
- `GET /reset-password/<token>` - Show reset form
- `POST /reset-password/<token>` - Process new password
**Files:** `app.py` (lines ~3251-3368)
**Rate Limit:** 5 requests per hour per IP
**Reset Token Properties:**
- Generated via `secrets.token_urlsafe(32)` (256-bit entropy)
- Expires after **1 hour**
- Single-use (cleared after successful reset)
- Stored in `users.reset_token` column
**Database Schema:**
```sql
reset_token VARCHAR(255) NULL
reset_token_expires TIMESTAMP NULL
```
**Security Considerations:**
- Reset tokens expire after 1 hour
- Tokens are cleared after use
- Password strength validation applied
- Email enumeration prevented (always show success message)
- Rate limiting prevents brute force
---
## 7. Authorization & Access Control
### 7.1 Authorization Levels
```mermaid
graph TB
subgraph "Authorization Hierarchy"
Public[👥 Public<br/>Anonymous Users]
Auth[🔐 Authenticated<br/>Logged-in Users]
Member[👔 NORDA Members<br/>is_norda_member=TRUE]
Admin[👨‍💼 Administrators<br/>is_admin=TRUE]
Public --> Auth
Auth --> Member
Member --> Admin
end
subgraph "Access Permissions"
PublicRoutes["Public Routes:<br/>/, /search, /company/*,<br/>/audit/*, /api/companies"]
AuthRoutes["Authenticated Routes:<br/>/dashboard, /chat,<br/>/forum/*, /wiadomosci/*,<br/>/kalendarz/*, /tablica/*"]
AdminRoutes["Admin Routes:<br/>/admin/*, /api/*/audit"]
end
Public --> PublicRoutes
Auth --> AuthRoutes
Admin --> AdminRoutes
```
### 7.2 Route Protection Decorators
**Public Access (No decorator):**
```python
@app.route('/')
def index():
"""Public company directory"""
# No authentication required
return render_template('index.html')
```
**Authenticated Users Only:**
```python
@app.route('/dashboard')
@login_required
def dashboard():
"""User dashboard - requires login"""
# current_user is automatically available
return render_template('dashboard.html', user=current_user)
```
**Admin Only (Custom check):**
```python
@app.route('/admin/users')
@login_required
def admin_users():
"""Admin user management"""
if not current_user.is_admin:
flash('Brak uprawnień administratora.', 'error')
return redirect(url_for('index'))
# Admin logic here
return render_template('admin/users.html')
```
### 7.3 Access Control Matrix
| Route Category | Public | Authenticated | NORDA Member | Admin |
|---------------|--------|---------------|--------------|-------|
| `/` (Company directory) | ✅ | ✅ | ✅ | ✅ |
| `/search` | ✅ | ✅ | ✅ | ✅ |
| `/company/<slug>` | ✅ | ✅ | ✅ | ✅ |
| `/audit/*/<slug>` | ✅ | ✅ | ✅ | ✅ |
| `/api/companies` | ✅ | ✅ | ✅ | ✅ |
| `/register`, `/login` | ✅ | ❌ | ❌ | ❌ |
| `/dashboard` | ❌ | ✅ | ✅ | ✅ |
| `/chat` | ❌ | ✅ | ✅ | ✅ |
| `/forum/*` | ❌ | ✅ | ✅ | ✅ |
| `/wiadomosci/*` | ❌ | ✅ | ✅ | ✅ |
| `/kalendarz/*` | ❌ | ✅ | ✅ | ✅ |
| `/tablica/*` | ❌ | ✅ | ✅ | ✅ |
| `/admin/*` | ❌ | ❌ | ❌ | ✅ |
| `/api/*/audit` | ❌ | ❌ | ❌ | ✅ |
**Legend:**
- ✅ Access granted
- ❌ Access denied (redirect to login or show error)
---
## 8. User Model Database Schema
### 8.1 Users Table Structure
```sql
CREATE TABLE users (
-- Primary Key
id SERIAL PRIMARY KEY,
-- Authentication
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
-- Profile
name VARCHAR(255),
phone VARCHAR(50),
-- Company Association
company_nip VARCHAR(10),
company_id INTEGER REFERENCES companies(id),
-- Status Flags
is_active BOOLEAN DEFAULT TRUE,
is_verified BOOLEAN DEFAULT FALSE,
is_admin BOOLEAN DEFAULT FALSE,
is_norda_member BOOLEAN DEFAULT FALSE,
-- Timestamps
created_at TIMESTAMP DEFAULT NOW(),
last_login TIMESTAMP,
verified_at TIMESTAMP,
-- Email Verification
verification_token VARCHAR(255),
verification_token_expires TIMESTAMP,
-- Password Reset
reset_token VARCHAR(255),
reset_token_expires TIMESTAMP,
-- Indexes
INDEX idx_users_email (email),
INDEX idx_users_company_id (company_id)
);
```
### 8.2 User Model (SQLAlchemy)
**File:** `database.py` (lines ~119-158)
```python
class User(Base, UserMixin):
"""User accounts with Flask-Login integration"""
__tablename__ = 'users'
# Authentication fields
id = Column(Integer, primary_key=True)
email = Column(String(255), unique=True, nullable=False, index=True)
password_hash = Column(String(255), nullable=False)
# Profile
name = Column(String(255))
company_nip = Column(String(10))
company_id = Column(Integer, ForeignKey('companies.id'), nullable=True)
phone = Column(String(50))
# Status
is_active = Column(Boolean, default=True)
is_verified = Column(Boolean, default=False)
is_admin = Column(Boolean, default=False)
is_norda_member = Column(Boolean, default=False)
# Timestamps
created_at = Column(DateTime, default=datetime.now)
last_login = Column(DateTime)
verified_at = Column(DateTime)
# Verification token
verification_token = Column(String(255))
verification_token_expires = Column(DateTime)
# Password reset token
reset_token = Column(String(255))
reset_token_expires = Column(DateTime)
# Relationships
company = relationship('Company', backref='users', lazy='joined')
conversations = relationship('AIChatConversation', back_populates='user')
forum_topics = relationship('ForumTopic', back_populates='author')
forum_replies = relationship('ForumReply', back_populates='author')
```
**UserMixin Methods (Flask-Login):**
- `is_authenticated` - Always True for logged-in users
- `is_active` - Returns `self.is_active`
- `is_anonymous` - Always False for logged-in users
- `get_id()` - Returns `str(self.id)` for session storage
---
## 9. Security Features Summary
### 9.1 Security Measures Implemented
| Feature | Implementation | Protection Against |
|---------|----------------|---------------------|
| **CSRF Protection** | Flask-WTF automatic tokens | Cross-Site Request Forgery |
| **Password Hashing** | PBKDF2:SHA256 (werkzeug) | Rainbow table attacks |
| **Secure Cookies** | HttpOnly, Secure, SameSite=Lax | XSS cookie theft, CSRF |
| **Email Verification** | Required before login | Fake accounts |
| **Input Sanitization** | `sanitize_input()` function | XSS attacks |
| **Rate Limiting** | Flask-Limiter (5 req/hour) | Brute force attacks |
| **Session Regeneration** | Flask-Login automatic | Session fixation |
| **Token Expiry** | 24h (verify), 1h (reset) | Token replay attacks |
| **Open Redirect Prevention** | Next URL validation | Phishing attacks |
| **Password Strength** | 8+ chars, complexity rules | Weak passwords |
### 9.2 Security Best Practices
**Implemented:**
✅ HTTPS enforced in production
✅ Password hashing with secure algorithm
✅ CSRF protection on all forms
✅ Session cookies with security flags
✅ Email verification required
✅ Rate limiting on auth endpoints
✅ Input sanitization
✅ Token expiry
✅ Open redirect prevention
**Potential Improvements:**
⚠️ Add account lockout after N failed attempts
⚠️ Implement 2FA (TOTP) for admins
⚠️ Add password history (prevent reuse)
⚠️ Log authentication events for auditing
⚠️ Add CAPTCHA on registration
⚠️ Implement session timeout (idle)
⚠️ Add IP-based rate limiting
---
## 10. Testing Accounts (Production)
### 10.1 Test Users
**IMPORTANT:** Use only these accounts for testing production features.
| Account | Email | Role | Purpose |
|---------|-------|------|---------|
| Test User | `test@nordabiznes.pl` | Regular User | Test user-level features |
| Test Admin | `testadmin@nordabiznes.pl` | Administrator | Test admin features |
**Test Account Credentials:**
- Password stored in CLAUDE.md (do not commit to repository)
- Accounts are pre-verified (`is_verified = TRUE`)
- Test Admin has `is_admin = TRUE` flag
**Usage:**
- Always use test accounts for production testing
- Never modify real user accounts for testing
- Test authentication flows, authorization, session management
---
## 11. Related Documentation
### 11.1 Architecture Documents
- [System Context Diagram](../01-system-context.md) - External actors and integrations
- [Container Diagram](../02-container-diagram.md) - Flask app and session storage
- [Flask Components](../04-flask-components.md) - Authentication routes and decorators
- [Database Schema](../05-database-schema.md) - Users table and relationships
### 11.2 Code Files
**Authentication Routes:**
- `app.py` lines ~3077-3500 (register, login, logout, verify, reset)
**User Model:**
- `database.py` lines ~119-158 (User model with Flask-Login)
**Email Service:**
- `email_service.py` (Microsoft Graph email sending)
**Security Utilities:**
- `app.py` - `sanitize_input()`, `validate_email()`, `validate_password()`
### 11.3 External Dependencies
- **Flask-Login:** User session management
- **Flask-WTF:** CSRF protection
- **Flask-Limiter:** Rate limiting
- **werkzeug.security:** Password hashing
- **secrets:** Cryptographic token generation
---
## 12. Maintenance & Updates
### 12.1 When to Update This Document
Update this document when:
- Authentication flow changes (new steps, validation)
- Session management changes (cookie settings, expiry)
- Security measures are added/modified
- New authorization levels are introduced
- User model schema changes
### 12.2 Verification Checklist
When updating authentication flow:
- [ ] Test registration with valid/invalid data
- [ ] Test email verification with valid/expired tokens
- [ ] Test login with correct/incorrect credentials
- [ ] Test session persistence (remember me)
- [ ] Test logout clears session
- [ ] Test password reset flow end-to-end
- [ ] Verify CSRF protection is active
- [ ] Verify rate limiting works
- [ ] Test authorization levels (public, user, admin)
- [ ] Verify security headers on cookies
### 12.3 Security Audit Checklist
Periodic security audit:
- [ ] Review password hashing algorithm (current: PBKDF2:SHA256)
- [ ] Check token expiry times (verify: 24h, reset: 1h)
- [ ] Verify session cookie security flags
- [ ] Review rate limiting thresholds
- [ ] Check for SQL injection vulnerabilities
- [ ] Test XSS prevention in inputs
- [ ] Verify CSRF protection coverage
- [ ] Review authentication logs for anomalies
- [ ] Test open redirect prevention
- [ ] Verify email verification enforcement
---
**Document End**
*This document is maintained as part of the Norda Biznes Hub architecture documentation. For questions or updates, contact the development team.*

1160
docs/architecture/flows/02-search-flow.md Normal file
View File

File diff suppressed because it is too large Load Diff

1443
docs/architecture/flows/03-ai-chat-flow.md Normal file
View File

File diff suppressed because it is too large Load Diff

1345
docs/architecture/flows/04-seo-audit-flow.md Normal file
View File

File diff suppressed because it is too large Load Diff

2057
docs/architecture/flows/05-news-monitoring-flow.md Normal file
View File

File diff suppressed because it is too large Load Diff

1295
docs/architecture/flows/06-http-request-flow.md Normal file
View File

File diff suppressed because it is too large Load Diff