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

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