maciejpi/nordabiz
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
4157138c2a
nordabiz/docs/PROJECT_CONTEXT.md

5.3 KiB
Raw Blame History

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: NORDABIZ-01 (10.22.68.249)
  • 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
  • pull on prod, run migrations via scripts/run_migration.py
  • 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