209 lines
5.3 KiB
Markdown
209 lines
5.3 KiB
Markdown
# 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
|
|
|