Maciej Pienczyn ff930f8724 fix: Pozostałe odniesienia "Biznes Hub" → "Biznes Partner"

- docs/architecture/01-system-context.md: diagram Mermaid
- docs/zabbix_setup.md: konfiguracja monitoringu

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-29 14:12:00 +01:00

14 KiB

Raw Blame History

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

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

🔍 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

📊 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

📍 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

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

📧 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

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

Next Level: Container Diagram (C4 Level 2) - Shows major containers (Flask app, database, proxy, etc.)
Infrastructure: Deployment Architecture - Physical deployment with IPs and ports
Components: Flask Application Components - Internal application structure
Database: Database Schema - Entity relationships
External APIs: External Integrations - 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)

14 KiB Raw Blame History