# NordaBiznes.pl - Project Context (Source of Truth)

This document captures the current, consolidated project knowledge for the
Norda Biznes Partner platform. It is intended for onboarding, maintenance,
and AI assistants. It is not a marketing page.

Last updated: 2026-02-03

---

## 1) Product Summary

- Name: Norda Biznes Partner
- Purpose: Business directory and networking platform for Norda Biznes members
- Production: https://nordabiznes.pl
- Status: LIVE since 2025-11-23
- Coverage: 80 member companies (100% of current membership)
- Target: 150 companies (marketing target)

Primary capabilities:
- Company directory and detailed profiles
- Advanced search (FTS + fuzzy + synonyms)
- AI chat assistant (Gemini)
- Admin dashboards: SEO, social, GBP, IT, news moderation
- User accounts with roles and permissions
- REST APIs for key features

---

## 2) Architecture Overview

High-level:
- 3-tier architecture: NPM Reverse Proxy -> Flask/Gunicorn -> PostgreSQL
- Security zones: Public -> DMZ -> App -> Data
- External APIs: Gemini, Brave Search, PageSpeed, Google Places, KRS, MS Graph

Key documentation:
- docs/architecture/01-system-context.md
- docs/architecture/02-container-diagram.md
- docs/architecture/03-deployment-architecture.md
- docs/architecture/04-flask-components.md
- docs/architecture/05-database-schema.md
- docs/architecture/06-external-integrations.md
- docs/architecture/07-network-topology.md
- docs/architecture/08-critical-configurations.md (CRITICAL)
- docs/architecture/09-security-architecture.md
- docs/architecture/flows/*

---

## 3) Codebase Layout

Core entrypoints:
- app.py: main Flask app, routes, init, services
- database.py: SQLAlchemy models and enums
- config.py: environment config (dev/prod/testing)
- extensions.py: CSRF, login, rate limiter

Services:
- gemini_service.py: Gemini SDK, models, cost tracking
- nordabiz_chat.py: AI chat engine + context
- search_service.py: unified search (NIP/REGON/FTS/fuzzy)
- krs_api_service.py, gbp_audit_service.py, it_audit_service.py, email_service.py

Blueprints:
- blueprints/* (auth, public, admin, audit, api, forum, membership, community,
  education, it_audit, reports, zopk, etc.)
- blueprints/__init__.py: phased registration + endpoint aliases

Templates and static:
- templates/: Jinja2 templates
- static/: CSS/JS/assets (custom, no JS framework)

---

## 4) Key Flows (Docs)

Detailed flows (Mermaid sequence diagrams):
- docs/architecture/flows/01-authentication-flow.md
- docs/architecture/flows/02-search-flow.md
- docs/architecture/flows/03-ai-chat-flow.md
- docs/architecture/flows/04-seo-audit-flow.md
- docs/architecture/flows/05-news-monitoring-flow.md
- docs/architecture/flows/06-http-request-flow.md (CRITICAL port 5000)

---

## 5) Data Model Highlights

database.py defines models for:
- Users, Companies, Categories, Services, Competencies
- Chat conversations and messages
- Audits: SEO, GBP, IT, KRS
- Social media, events, forum, classifieds, notifications
- Analytics and logging

Roles:
- SystemRole (UNAFFILIATED, MEMBER, EMPLOYEE, MANAGER, OFFICE_MANAGER, ADMIN)
- CompanyRole (NONE, VIEWER, EMPLOYEE, MANAGER)

---

## 6) AI and Search

Search:
- NIP/REGON direct lookup
- Synonym expansion (Polish)
- PostgreSQL FTS + pg_trgm fuzzy matching
- Scoring by fields (name/description/services/competencies/city)

AI Chat:
- Uses search_service for candidate companies
- Limits context size (company count and message history)
- Tracks cost in DB

Gemini:
- Model registry in gemini_service.py
- Supports Gemini 3 models and thinking mode

---

## 7) External Integrations

Configured APIs:
- Google Gemini (AI chat)
- Brave Search (news monitoring)
- Google PageSpeed (SEO audits)
- Google Places (GBP audit)
- KRS API (company registry)
- Microsoft Graph (email service)

Environment variables:
- docs/SECURITY.md (required + optional vars)
- .env (dev) and /var/www/nordabiznes/.env (prod)

---

## 8) Deployment and Ops

Production:
- App server: OVH VPS inpi-vps-waw01 (57.128.200.27)
- DB: PostgreSQL on same host (5432)
- Reverse proxy: NPM on 10.22.68.250
- Domain: nordabiznes.pl

Staging:
- Server: NORDABIZ-STAGING-01 (10.22.68.248)
- Domain: staging.nordabiznes.pl

CRITICAL CONFIG:
- NPM must forward to port 5000 (NOT 80)
- docs/architecture/08-critical-configurations.md
- Incident: docs/INCIDENT_REPORT_20260102.md

Deployment workflow:
- push to GitHub and Gitea
- pull on staging, test
- deploy to OVH VPS (57.128.200.27) via rsync, run migrations via sudo -u postgres psql
- restart systemd service

---

## 9) Testing

AI quality tests:
- run_ai_quality_tests.py
- tests/ai_quality_test_cases.json

Test structure:
- tests/unit, tests/integration, tests/e2e, tests/security, tests/smoke

---

## 10) Scripts

scripts/ includes:
- data imports (CEIDG/KRS)
- SEO/GBP/Social audits
- migrations and data fixes
- ZOPK knowledge pipeline

---

## 11) Known Documentation Gaps

ARCHITECTURE_VERIFICATION_REPORT.md lists warnings:
- Some models documented but not found in database.py
- Verify documentation vs code before relying on model lists

---

## 12) Where To Look First

Onboarding:
- README.md
- CLAUDE.md
- docs/DEVELOPMENT.md
- docs/architecture/README.md
- docs/architecture/08-critical-configurations.md

---

## 13) Update Policy

When changes are made:
- Update this file if it affects architecture, deployment, models, or key flows
- Keep it short and accurate; link to deeper docs for details