nordabiz/docs/architecture/01-system-context.md

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

---

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

---

Related Documentation

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