# Norda Biznes Partner

**Production-ready Flask web application** providing a business directory and networking platform for members of the Norda Biznes association from Wejherowo and surrounding area.

**🚀 Status:** LIVE in production since 2025-11-23
**🌐 URL:** https://nordabiznes.pl
**📊 Coverage:** 80 member companies (100% of Norda Biznes membership)

---

## Table of Contents

- [Overview](#overview)
- [Quick Start](#quick-start)
- [Features](#features)
- [Technology Stack](#technology-stack)
- [Project Structure](#project-structure)
- [Development Environment Setup](#development-environment-setup)
- [Testing & Quality Assurance](#testing--quality-assurance)
- [Deployment & Production](#deployment--production)
- [API Documentation](#api-documentation)
- [Common Commands Reference](#common-commands-reference)
- [Contributing](#contributing)
- [Troubleshooting](#troubleshooting)
- [Resources & Documentation](#resources--documentation)
- [Roadmap & Future Enhancements](#roadmap--future-enhancements)
- [Contact](#contact)

---

## Quick Start

**For experienced developers who want to get running immediately:**

```bash
# 1. Clone and setup
git clone https://github.com/pienczyn/nordabiz.git
cd nordabiz
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 2. Start PostgreSQL (Docker)
docker compose up -d

# 3. Initialize database
docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql

# 4. Configure environment
cp .env.example .env
# Edit .env and add your API keys (see Development Environment Setup for details)

# 5. Run the application
python3 app.py

# 6. Open http://localhost:5000
```

**Required API Keys:**
- **Google Gemini API** (for AI chat): https://ai.google.dev/ - Free tier: 200 req/day
- **Google PageSpeed Insights** (for SEO audits): https://developers.google.com/speed/docs/insights/v5/get-started - Free tier: 25,000 req/day
- **Google Places API** (for GBP audits): https://console.cloud.google.com/apis/credentials - Free tier: $200/month credit

For detailed setup instructions, see [Development Environment Setup](#development-environment-setup).

---

## Overview

Norda Biznes Partner is a **Flask-powered web platform** built with PostgreSQL, featuring AI-driven search capabilities, comprehensive company profiles, and administrative tools for managing member data. The platform integrates Google Gemini AI for intelligent company recommendations, automated news monitoring via Brave Search API, and comprehensive SEO/social media auditing tools.

**Key Capabilities:**
- **Company Directory** - Complete catalog of 80 member companies with verified data
- **AI Chat Assistant** - Google Gemini 3 Flash-powered conversational search
- **Advanced Search** - Multi-mode search with FTS, fuzzy matching, and synonym expansion
- **Admin Panels** - News moderation, SEO audit, social media tracking, GBP/IT audits
- **User Authentication** - Secure login with email confirmation and role-based access
- **RESTful API** - JSON endpoints for programmatic access to company data

## Technology Stack

### Backend
- **Python** 3.9+ - Core programming language
- **Flask** 3.0.0 - Web application framework
- **SQLAlchemy** 2.0.23 - ORM and database abstraction layer
- **PostgreSQL** - Primary relational database (production and development)
- **Gunicorn** - WSGI HTTP server for production deployment

### Security & Authentication
- **Flask-Login** 0.6.3 - User session management and authentication
- **Flask-WTF** 1.2.1 - CSRF protection and form validation
- **Flask-Limiter** 3.5.0 - Rate limiting (200 req/day, 50 req/hour)

### AI & Machine Learning
- **Google Gemini AI** (google-generativeai 0.3.2)
  - Models: gemini-3-flash-preview (default), gemini-3-pro-preview (advanced)
  - Features: Multi-turn conversations, context-aware recommendations, AI-powered search
  - Limits: Free tier (200 requests/day)

### External API Integrations
1. **Google Gemini AI** - Conversational AI and company recommendations
2. **Google PageSpeed Insights** - SEO and performance analysis (25,000 req/day)
3. **Google Maps/Places** - Business verification and geocoding
4. **Microsoft Graph API** - Email service (OAuth2 with MSAL)
5. **KRS Open API** - Polish business registry data
6. **Brave Search API** - News monitoring and company mentions (2,000 req/month)

### Frontend
- **Jinja2** - Server-side HTML template rendering (30+ templates)
- **CSS3** - Custom styling with Fluent Design System inspiration
- **Vanilla JavaScript** (ES6+) - Dynamic UI interactions, AJAX, form validation
- **No external frameworks** - Custom UI components (modals, toasts, cards, tables)

### SEO & Web Analysis
- **BeautifulSoup4** 4.12.3 - HTML parsing and meta tag extraction
- **lxml** 5.1.0 - Fast XML/HTML processing with XPath support
- **python-whois** 0.9.4 - Domain information and WHOIS lookup

### Infrastructure & Deployment
- **Nginx Proxy Manager** - Reverse proxy on R11-REVPROXY-01 (10.22.68.250)
- **Let's Encrypt** - SSL/TLS certificates with auto-renewal
- **Docker** - PostgreSQL container for local development
- **systemd** - Service management (nordabiznes.service)
- **Git** - Version control (GitHub + Gitea internal)

### Database
- **PostgreSQL** - Primary database with advanced features:
  - Full-text search (FTS) with tsvector
  - Fuzzy matching with pg_trgm extension
  - JSONB for flexible data storage
  - 20+ tables (Company, User, Chat, News, Social Media, SEO, etc.)
  - psycopg2-binary 2.9.9 adapter

### Utilities
- **Flask-Mail** 0.9.1 - Email functionality
- **requests** 2.31.0 - HTTP client for external API calls
- **feedparser** 6.0.10 - RSS/Atom feed parsing
- **python-dotenv** 1.0.0 - Environment variable management

---

## Features

### User-Facing Features

#### 🏢 Company Directory & Catalog
- **80 member companies** with 100% coverage of Norda Biznes membership
- **6 business categories:** IT, Construction, Services, Production, Trade, Other
- **Comprehensive company profiles** with verified data (NIP, REGON, KRS)
- **Detailed information:** Contact details, services, competencies, social media presence
- **Website technical analysis** for each company
- **Data quality levels:** Basic, enhanced, and complete profiles

#### 🔍 Advanced Search & Discovery
- **Multi-mode search system** with AI-powered capabilities
- **Direct lookup:** NIP/REGON exact matching
- **Keyword search:** Company name, description, services, competencies
- **Synonym expansion:** Automatic keyword expansion (e.g., "strony" → www, web, portal)
- **Full-text search:** PostgreSQL FTS with tsvector indexing
- **Fuzzy matching:** pg_trgm for typo tolerance
- **Weighted scoring:** Prioritized results by relevance

#### 💬 AI Chat Assistant
- **Conversational AI** powered by Google Gemini 3 Flash
- **Context-aware recommendations** for company discovery
- **Multi-turn conversations** with full history tracking
- **Answer questions** about member companies and services
- **Find companies** by service, competency, or business need
- **Quality assurance:** 15 test cases with 70% pass threshold
- **Rate limiting:** 200 requests/day, 50 requests/hour

#### 🔐 User Authentication & Accounts
- **Secure registration** with email confirmation
- **User profiles** with company affiliation tracking
- **Password reset** functionality
- **Session management** with Flask-Login
- **CSRF protection** on all forms
- **Role-based access** (user vs admin)

#### 🔔 Notifications System
- **Real-time notifications** for user activity
- **Notification types:** New news, news approved/rejected
- **JSON API** for programmatic access
- **Unread count** tracking

### Admin Features (Requires Admin Access)

#### 📰 News Monitoring & Moderation
- **Automated news monitoring** via Brave Search API
- **AI-powered relevance scoring** (0.0-1.0) with Google Gemini
- **News categorization:** News mentions, press releases, awards
- **Admin moderation dashboard** with approve/reject workflow
- **Bulk actions** for efficient moderation
- **Display on company profiles** for approved news

#### 📱 Social Media Audit
- **Track 6 platforms:** Facebook, Instagram, LinkedIn, YouTube, TikTok, Twitter/X
- **Profile verification** and validation
- **Activity monitoring:** Last checked, followers count
- **Missing profile identification** for outreach opportunities
- **Current coverage:** 115 profiles across 53 companies (66% coverage)
- **Batch audit processing** for efficiency

#### 🎯 SEO Dashboard & Audit
- **Comprehensive SEO audits** using Google PageSpeed Insights API
- **Performance scoring** (0-100) for each company website
- **Accessibility scoring** for WCAG compliance
- **Best practices scoring** for web standards
- **On-page SEO analysis:** Meta tags, headings, images
- **Technical SEO checks:** robots.txt, sitemap, canonical tags
- **Historical tracking** of SEO improvements
- **Batch processing** with rate limiting (25,000 req/day)

#### 🏪 Google Business Profile (GBP) Audit
- **Field-by-field completeness checking**
- **Weighted scoring algorithm** (100 points total)
- **AI-powered recommendations** via Google Gemini
- **Historical tracking** of profile improvements
- **Photo requirements analysis**

#### 💻 IT Infrastructure Audit
- **Security posture scoring** (50% weight)
- **Collaboration readiness assessment** (30% weight)
- **Completeness scoring** (20% weight)
- **Maturity level classification**
- **Cross-company collaboration matching**
- **Security elements:** EDR, MFA, Firewall, Backup, DR, VPN, Monitoring

#### 💬 Forum Management
- **Discussion forum** for member engagement
- **Topic and reply moderation**
- **Community discussions**

#### 📅 Calendar Management
- **Events and meetings calendar**
- **Event creation and management**
- **Member calendar access**

#### 👥 User Management
- **User account administration**
- **Permission management**
- **Admin role assignment**

### Technical Features

#### 🔌 RESTful API
- **JSON endpoints** for programmatic access:
  - `GET /api/companies` - Companies list
  - `GET /api/verify-nip` - NIP verification
  - `GET /api/notifications` - User notifications
  - `GET /health` - Health check
- **Authentication required** for protected endpoints

#### 🛡️ Security & Rate Limiting
- **Flask-Login** for session management
- **Flask-WTF** for CSRF protection on all forms
- **Flask-Limiter** for rate limiting (200 req/day, 50 req/hour)
- **Secure password hashing**
- **SQL injection protection** via SQLAlchemy ORM
- **XSS protection** via Jinja2 auto-escaping
- **API key management** via environment variables

#### 🗄️ Database Architecture
- **PostgreSQL** primary database with 20+ tables
- **SQLAlchemy 2.0** ORM with advanced features
- **Full-text search** with tsvector indexing
- **Fuzzy matching** with pg_trgm extension
- **JSONB support** for flexible data storage
- **Migration system** for schema versioning

#### 🌍 Multi-Environment Deployment
- **Development:** PostgreSQL via Docker (localhost:5433)
- **Production:** NORDABIZ-01 server (VM 249, 10.22.68.249)
- **Reverse proxy:** NPM on R11-REVPROXY-01
- **SSL/TLS:** Let's Encrypt with auto-renewal
- **Domain:** nordabiznes.pl (DNS in OVH)
- **WSGI:** Gunicorn production server

#### 🔗 External API Integrations
- **Google Gemini AI** - Conversational AI (200 req/day)
- **Google PageSpeed Insights** - SEO audits (25,000 req/day)
- **Google Maps/Places** - Business verification
- **Microsoft Graph API** - Email service
- **KRS Open API** - Polish business registry
- **Brave Search API** - News monitoring (2,000 req/month)

#### ✅ Data Verification & Quality Control
- **NIP verification** via KRS API
- **REGON validation**
- **KRS number verification**
- **Data completeness checks**
- **Quality levels:** Basic, enhanced, complete
- **Automated verification scripts**

#### 🧪 AI Quality Testing Framework
- **Automated AI response evaluation**
- **15 test cases** in 8 business categories
- **70% pass threshold** for quality assurance
- **JSON-based test configuration**
- **Detailed evaluation reports**

## Project Structure

```
nordabiz/
├── app.py                      # Main Flask application (routes, auth, API)
├── database.py                 # SQLAlchemy models (20+ tables)
├── gemini_service.py           # Google Gemini AI integration
├── nordabiz_chat.py            # AI chat engine with company context
├── search_service.py           # Unified search (FTS, fuzzy, synonyms)
├── email_service.py            # Microsoft Graph email integration
├── krs_api_service.py          # Polish business registry API
├── gbp_audit_service.py        # Google Business Profile audit
├── it_audit_service.py         # IT infrastructure audit
├── templates/                  # Jinja2 HTML templates (30+ files)
│   ├── base.html               # Base template with navigation and auth
│   ├── index.html              # Company directory listing
│   ├── company_detail.html     # Detailed company profile page
│   ├── chat.html               # AI chat interface
│   ├── admin/                  # Admin dashboards and tools (15 files)
│   ├── auth/                   # Authentication flows (5 files)
│   ├── forum/                  # Community forum (3 files)
│   ├── calendar/               # Events calendar (4 files)
│   ├── messages/               # Private messaging (4 files)
│   └── errors/                 # Error pages (404, 500)
├── static/                     # Static assets (CSS, images)
│   ├── css/                    # Fluent Design stylesheets
│   │   ├── microsoft-fluent.css
│   │   └── fluent-nordabiz.css
│   └── img/companies/          # Company logos (80 images)
├── database/                   # Database schemas and migrations
│   ├── schema.sql              # Main PostgreSQL schema
│   ├── README.md               # Database documentation
│   └── migrations/             # Versioned migrations (6 files)
├── scripts/                    # Production automation scripts
│   ├── seo_audit.py            # SEO audit tool (PageSpeed Insights)
│   ├── social_media_audit.py   # Social media presence audit
│   ├── seo_analyzer.py         # On-page SEO analysis
│   └── company-data-collector.js  # Node.js web scraper
├── tests/                      # Test suite (7 files)
│   ├── ai_quality_evaluator.py # AI testing framework
│   ├── ai_quality_test_cases.json  # 15 test cases in 8 categories
│   ├── test_admin_seo_dashboard.py
│   ├── test_gbp_audit_field_checks.py
│   ├── test_it_audit_collaboration.py
│   └── test_social_media_audit.py
├── data/                       # Source data files
│   ├── companies-basic.json    # 80 company profiles
│   └── data-sources.md         # Data source documentation
├── requirements.txt            # Python dependencies (16 packages)
├── docker-compose.yml          # PostgreSQL development database
├── .env.example                # Environment variables template
├── CLAUDE.md                   # Project documentation for AI
└── deployment_checklist.md     # Production deployment guide
```

## Development Environment Setup

Follow these steps to set up the development environment on your local machine.

### Prerequisites

- **Python 3.9+** - Core programming language
- **PostgreSQL 15+** - Database (via Docker or native installation)
- **Git** - Version control
- **Docker** (optional) - For containerized PostgreSQL

### Installation Steps

#### 1. Clone the Repository

```bash
git clone https://github.com/pienczyn/nordabiz.git
cd nordabiz
```

#### 2. Create Virtual Environment

```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate
```

#### 3. Install Python Dependencies

```bash
pip install -r requirements.txt
```

This will install all required packages including:
- Flask 3.0.0 (web framework)
- SQLAlchemy 2.0.23 (ORM)
- psycopg2-binary 2.9.9 (PostgreSQL adapter)
- google-generativeai 0.3.2 (Gemini AI)
- Flask-Login, Flask-WTF, Flask-Limiter (security)
- And more (see `requirements.txt` for complete list)

#### 4. Set Up PostgreSQL Database

**Option A: Using Docker (Recommended for Development)**

```bash
# Start PostgreSQL container
docker compose up -d

# Verify container is running
docker ps | grep nordabiz-postgres
```

This creates a PostgreSQL 15 database on `localhost:5433` with:
- Database: `nordabiz`
- User: `nordabiz_app`
- Password: `dev_password`

**Option B: Native PostgreSQL Installation**

```bash
# Install PostgreSQL (example for Ubuntu/Debian)
sudo apt install postgresql-15 postgresql-contrib-15

# Create database and user
sudo -u postgres psql
```

```sql
CREATE DATABASE nordabiz;
CREATE USER nordabiz_app WITH PASSWORD 'your_password_here';
GRANT ALL PRIVILEGES ON DATABASE nordabiz TO nordabiz_app;
\q
```

#### 5. Initialize Database Schema

```bash
# Apply schema (Docker setup)
docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql

# Or for native PostgreSQL
psql -U nordabiz_app -d nordabiz -h localhost < database/schema.sql
```

#### 6. Configure Environment Variables

Create `.env` file in the project root:

```bash
cp .env.example .env
```

Edit `.env` and configure the following variables:

```bash
# Flask Configuration
SECRET_KEY=your-super-secret-key-change-this
FLASK_ENV=development

# Server Configuration
PORT=5000
HOST=0.0.0.0

# Database Configuration (for Docker setup)
DATABASE_URL=postgresql://nordabiz_app:dev_password@localhost:5433/nordabiz

# Google Gemini API (required for AI chat)
GOOGLE_GEMINI_API_KEY=your_gemini_api_key_here

# Google PageSpeed Insights API (optional, for SEO audits)
GOOGLE_PAGESPEED_API_KEY=your_pagespeed_api_key_here

# Google Places API (optional, for GBP audits)
GOOGLE_PLACES_API_KEY=your_places_api_key_here

# Email Configuration (optional, for user verification)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password_here
MAIL_DEFAULT_SENDER=noreply@norda-biznes.info

# Application URLs
APP_URL=http://localhost:5000
VERIFY_EMAIL_URL=http://localhost:5000/verify-email
```

**Getting API Keys:**
- **Gemini API**: https://ai.google.dev/ (free tier: 200 requests/day)
- **PageSpeed Insights**: https://developers.google.com/speed/docs/insights/v5/get-started (free tier: 25,000 requests/day)
- **Google Places**: https://console.cloud.google.com/apis/credentials (free tier: $200/month credit)

#### 7. Run the Application

```bash
# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Run Flask development server
python3 app.py
```

The application will start on `http://localhost:5000`

**Default ports:**
- Flask app: `5000` (or `5001` if 5000 is occupied)
- PostgreSQL (Docker): `5433` (mapped from container's 5432)

#### 8. Verify Installation

Open your browser and navigate to:
- **Main app**: http://localhost:5000
- **Health check**: http://localhost:5000/health
- **API test**: http://localhost:5000/api/companies

### Development Workflow

```bash
# Start PostgreSQL (if using Docker)
docker compose up -d

# Activate virtual environment
source venv/bin/activate

# Run application
python3 app.py

# In another terminal: Run tests
python -m pytest tests/

# Stop PostgreSQL when done
docker compose down
```

### Troubleshooting

**Database Connection Issues:**
```bash
# Check PostgreSQL is running (Docker)
docker ps | grep nordabiz-postgres

# Check PostgreSQL logs
docker logs nordabiz-postgres

# Restart PostgreSQL container
docker compose restart
```

**Port Already in Use:**
```bash
# Change PORT in .env file
PORT=5001

# Or stop conflicting service
lsof -ti:5000 | xargs kill -9
```

**Missing Dependencies:**
```bash
# Reinstall all dependencies
pip install -r requirements.txt --force-reinstall
```

**Database Schema Issues:**
```bash
# Reset database (Docker)
docker compose down -v  # WARNING: Deletes all data!
docker compose up -d
docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql
```

For more detailed database setup and management, see `database/README.md`.

## Testing & Quality Assurance

The Norda Biznes Partner includes a comprehensive testing framework to ensure code quality, AI accuracy, and feature reliability. The test suite covers unit tests for individual components and specialized AI quality evaluation.

### Test Suite Overview

The `tests/` directory contains the following test modules:

```
tests/
├── ai_quality_evaluator.py          # AI testing framework
├── ai_quality_test_cases.json       # 15 test cases in 8 categories
├── test_admin_seo_dashboard.py      # SEO dashboard functionality tests
├── test_gbp_audit_field_checks.py   # Google Business Profile audit tests
├── test_it_audit_collaboration.py   # IT infrastructure audit tests
├── test_seo_audit.py                # SEO audit service tests
├── test_social_media_audit.py       # Social media audit tests
└── results/                         # Test results and reports (generated)
```

### Running Tests

#### AI Quality Tests

The AI Quality Testing Framework evaluates the accuracy and relevance of AI chat responses using predefined test cases.

**Basic Usage:**

```bash
# Run all AI quality tests (standard output)
python run_ai_quality_tests.py

# Run with verbose output showing details for each test
python run_ai_quality_tests.py --verbose
# or
python run_ai_quality_tests.py -v

# Run with verbose output AND save results to JSON file
python run_ai_quality_tests.py -v -s

# Run only high-priority test cases (quick validation)
python run_ai_quality_tests.py -q
```

**Test Results:**

Test results are displayed in the console and optionally saved to `tests/results/` directory with timestamps:
- `ai_quality_report_20260110_143000.json` - Detailed test results with scores and metrics

**AI Test Categories:**

The AI quality tests cover 8 business categories with 15 test cases:
1. **IT/Web Development** - Testing recommendations for IT services, web development
2. **Services/Legal** - Legal services, law firms
3. **Services/Accounting** - Accounting, bookkeeping services
4. **Production/Metal** - Metal production, manufacturing
5. **Construction** - Construction companies, contractors
6. **HVAC** - Heating, ventilation, air conditioning
7. **Energy/Renewable** - Renewable energy, solar panels
8. **IT/Security** - IT security, cybersecurity services

**Quality Thresholds:**
- **Pass Threshold:** 70% - Tests must achieve at least 70% accuracy to pass
- **Scoring:** Each test case is scored 0.0-1.0 based on:
  - Company relevance (did it find the right companies?)
  - Response accuracy (is the information correct?)
  - Context understanding (did it understand the query intent?)

#### Unit Tests

Run unit tests for specific components using pytest:

```bash
# Run all unit tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_admin_seo_dashboard.py

# Run with verbose output
python -m pytest tests/ -v

# Run with coverage report
python -m pytest tests/ --cov=.
```

#### Manual Testing in Production

**⚠️ IMPORTANT:** Always use test accounts for production verification.

**Test Accounts:**

| Account | Email | Purpose |
|---------|-------|---------|
| Test User | `test@nordabiznes.pl` | Test user-facing features (directory, search, chat) |
| Test Admin | `testadmin@nordabiznes.pl` | Test admin features (moderation, audits, management) |

**Testing Workflow:**

1. **User Features:**
   - Company directory browsing
   - Search functionality
   - AI chat conversations
   - User registration and authentication
   - Notifications

2. **Admin Features:**
   - News moderation (`/admin/news`)
   - SEO dashboard (`/admin/seo`)
   - Social media audit (`/admin/social-media`)
   - GBP audit (`/admin/gbp-audit`)
   - IT audit (`/admin/it-audit`)
   - User management (`/admin/users`)

### Quality Assurance Process

#### Pre-Deployment QA Checklist

Before deploying to production, ensure all quality checks pass:

1. **Code Quality:**
   ```bash
   # Check Python syntax
   python -m py_compile app.py

   # Check all Python files
   find . -name "*.py" -exec python -m py_compile {} \;
   ```

2. **AI Quality:**
   ```bash
   # Run AI quality tests with 70% pass threshold
   python run_ai_quality_tests.py -v
   # Expected: Pass rate ≥ 70%
   ```

3. **Unit Tests:**
   ```bash
   # Run all unit tests
   python -m pytest tests/ -v
   # Expected: All tests pass
   ```

4. **Database Integrity:**
   ```bash
   # Verify database schema (development)
   psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "\dt"

   # Check for data quality issues
   python verify_all_companies_data.py
   ```

5. **API Endpoints:**
   ```bash
   # Test health endpoint
   curl http://localhost:5000/health
   # Expected: {"status": "healthy"}

   # Test companies API
   curl http://localhost:5000/api/companies | jq '.total'
   # Expected: 80
   ```

#### Continuous Quality Monitoring

**Development:**
- Run AI quality tests after chat engine modifications
- Run unit tests after feature changes
- Verify test account functionality weekly

**Production:**
- Monitor health endpoint: `https://nordabiznes.pl/health`
- Review application logs: `sudo journalctl -u nordabiznes -f`
- Track AI chat analytics: `/admin/chat-analytics`
- Monitor rate limits and API usage

### Test Coverage

Current test coverage by feature area:

| Feature Area | Test Coverage | Test Files |
|--------------|---------------|------------|
| **AI Chat Engine** | ✅ Comprehensive | `ai_quality_evaluator.py`, `ai_quality_test_cases.json` |
| **SEO Audit** | ✅ Comprehensive | `test_admin_seo_dashboard.py`, `test_seo_audit.py` |
| **GBP Audit** | ✅ Comprehensive | `test_gbp_audit_field_checks.py` |
| **IT Audit** | ✅ Comprehensive | `test_it_audit_collaboration.py` |
| **Social Media Audit** | ✅ Comprehensive | `test_social_media_audit.py` |
| **Search Service** | ⚠️ Manual Testing | SearchService integration tests needed |
| **Authentication** | ⚠️ Manual Testing | User registration/login flow tests needed |
| **API Endpoints** | ⚠️ Manual Testing | API integration tests needed |

### Adding New Tests

#### AI Quality Test Cases

To add a new AI quality test case, edit `tests/ai_quality_test_cases.json`:

```json
{
  "test_id": "new_test_01",
  "category": "Services/Consulting",
  "priority": "high",
  "query": "Szukam firmy doradczej w Wejherowie",
  "expected_companies": [
    "Firma A",
    "Firma B"
  ],
  "notes": "Testing consulting service recommendations"
}
```

#### Unit Tests

Create a new test file in `tests/` following the pattern:

```python
"""
Test module for [feature name]
"""
import pytest
from database import SessionLocal, init_db
# Import modules to test

def test_feature_functionality():
    """Test basic feature functionality"""
    # Arrange
    db = SessionLocal()

    # Act
    result = feature_function()

    # Assert
    assert result is not None
    assert result.status == "success"

    db.close()
```

### Troubleshooting Tests

**AI Tests Failing:**

```bash
# Check Gemini API key is configured
grep GOOGLE_GEMINI_API_KEY .env

# Verify database has companies data
python -c "from database import SessionLocal, Company; db = SessionLocal(); print(db.query(Company).count())"
# Expected: 80
```

**Database Connection Errors:**

```bash
# Ensure PostgreSQL is running
docker ps | grep nordabiz-postgres

# Test database connection
psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT 1;"
```

**Import Errors:**

```bash
# Ensure all dependencies are installed
pip install -r requirements.txt

# Verify virtual environment is activated
which python
# Expected: /path/to/nordabiz/venv/bin/python
```

For detailed test implementation and examples, see the `tests/` directory and individual test modules.

## Deployment & Production

The application is live in production at **https://nordabiznes.pl** since November 23, 2025.

### Production Environment

| Component | Details |
|-----------|---------|
| **Server** | NORDABIZ-01 (VM 249, IP: 10.22.68.249) |
| **Database** | PostgreSQL 15 on 10.22.68.249:5432 |
| **Reverse Proxy** | Nginx Proxy Manager on R11-REVPROXY-01 (VM 119, IP: 10.22.68.250) |
| **Domain** | nordabiznes.pl (DNS managed via OVH) |
| **SSL/TLS** | Let's Encrypt with automatic renewal |
| **WSGI Server** | Gunicorn |
| **Service Manager** | systemd (`nordabiznes.service`) |
| **Application Path** | `/var/www/nordabiznes` |
| **Application User** | `www-data` |

### Git Repositories

The project maintains two Git remotes for redundancy and deployment:

| Remote | Repository | Purpose |
|--------|------------|---------|
| **origin** (GitHub) | `git@github.com:pienczyn/nordabiz.git` | Cloud backup, public access, CI/CD ready |
| **inpi** (Gitea) | `git@10.22.68.180:maciejpi/nordabiz.git` | Internal backup, deployment source |

**Gitea Access:** https://10.22.68.180:3000/ (requires HTTPS)

### Deployment Workflow

```
┌─────────────┐   git push    ┌─────────────┐   git pull    ┌─────────────┐
│ Development │ ────────────► │    Gitea    │ ◄──────────── │ Production  │
│   (Local)   │               │   (INPI)    │               │   Server    │
└─────────────┘               └─────────────┘               └─────────────┘
      │
      └──── git push ────► GitHub (cloud backup)
```

#### Deployment Steps

**1. Push Changes from Development:**

```bash
# Push to both remotes (from local development)
git push origin master && git push inpi master
```

**2. Deploy to Production:**

```bash
# SSH to production server
ssh maciejpi@10.22.68.249

# Navigate to application directory
cd /var/www/nordabiznes

# Pull latest changes (as www-data user)
sudo -u www-data git pull

# Restart the application service
sudo systemctl restart nordabiznes

# Verify deployment
curl -I https://nordabiznes.pl/health
# Expected: HTTP/2 200
```

#### Pre-Deployment Checklist

Before deploying to production, always:

1. **Test locally** - Verify changes work in development environment
2. **Syntax check** - Run `python -m py_compile app.py` to check for syntax errors
3. **Database migrations** - Apply any schema changes to production database
4. **Environment variables** - Ensure new `.env` variables are configured on production
5. **Dependencies** - Update `requirements.txt` if new packages were added

**For comprehensive deployment procedures, see [`deployment_checklist.md`](deployment_checklist.md).**

### Production Configuration

**Critical NPM Proxy Configuration:**

```
Nginx Proxy Manager (10.22.68.250) → Backend (10.22.68.249:5000) ✓
```

**⚠️ IMPORTANT:** The NPM proxy must forward to port **5000** (Gunicorn), NOT port 80 (nginx). Forwarding to port 80 causes redirect loops.

**Environment Variables:**

Production uses similar `.env` configuration as development, but with production-specific values:
- `FLASK_ENV=production`
- `DATABASE_URL=postgresql://nordabiz_app:***@localhost:5432/nordabiz`
- `APP_URL=https://nordabiznes.pl`
- Production API keys (Google Gemini, PageSpeed, Places, etc.)

### Production Monitoring & Maintenance

**Service Management:**

```bash
# Check service status
sudo systemctl status nordabiznes

# View application logs
sudo journalctl -u nordabiznes -f

# Restart service
sudo systemctl restart nordabiznes

# Stop service
sudo systemctl stop nordabiznes

# Start service
sudo systemctl start nordabiznes
```

**Database Backup:**

Production server uses Proxmox Backup Server for automated VM snapshots and disaster recovery.

**Health Check:**

The application provides a health endpoint for monitoring:
- **URL:** https://nordabiznes.pl/health
- **Expected Response:** `{"status": "healthy"}`

### Production Access

**SSH Access:**

```bash
# Always SSH as maciejpi user (NOT root!)
ssh maciejpi@10.22.68.249
```

**Test Accounts:**

For testing functionality in production:

| Account | Email | Role |
|---------|-------|------|
| Test User | `test@nordabiznes.pl` | Regular user (company directory, search, chat) |
| Test Admin | `testadmin@nordabiznes.pl` | Administrator (admin panels, moderation) |

**⚠️ IMPORTANT:** Always use test accounts for production verification. Never test with real user accounts.

### Troubleshooting Production Issues

**Application Not Responding:**

```bash
# Check if service is running
sudo systemctl status nordabiznes

# Check application logs for errors
sudo journalctl -u nordabiznes -n 100

# Restart service
sudo systemctl restart nordabiznes
```

**Database Connection Issues:**

```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Test database connectivity
psql -U nordabiz_app -d nordabiz -h localhost -c "SELECT 1;"
```

**Redirect Loop / 502 Errors:**

Verify NPM proxy configuration forwards to port 5000:
```bash
curl -I https://nordabiznes.pl/health
```

If issues persist, check NPM configuration on R11-REVPROXY-01 (Proxy Host ID: 27).

**For detailed incident reports and troubleshooting guides, see `docs/INCIDENT_REPORT_20260102.md`.**

## API Documentation

The Norda Biznes Partner provides a comprehensive RESTful API for programmatic access to company data, user management, and administrative functions. All API endpoints return JSON responses.

### Base URL

- **Development:** `http://localhost:5000`
- **Production:** `https://nordabiznes.pl`

### Authentication

API endpoints requiring authentication expect a valid session cookie (`session`). Users must be logged in via the web interface or obtain a session through the login endpoint.

### Public API Endpoints

These endpoints are accessible without authentication:

| Endpoint | Method | Description | Response |
|----------|--------|-------------|----------|
| `/health` | GET | Health check endpoint for monitoring | `{"status": "healthy"}` |
| `/api/companies` | GET | Retrieve list of all companies with filtering options | Array of company objects with full details |
| `/api/verify-nip` | POST | Verify NIP number via KRS API | Company data or error message |
| `/api/verify-krs` | GET/POST | Verify KRS number and retrieve company data | KRS registry information |
| `/api/model-info` | GET | Get information about AI model configuration | Model name, version, capabilities |
| `/api/check-email` | POST | Check if email address is already registered | `{"exists": true/false}` |

**Example - Get Companies:**
```bash
curl https://nordabiznes.pl/api/companies
```

**Example - Verify NIP:**
```bash
curl -X POST https://nordabiznes.pl/api/verify-nip \
  -H "Content-Type: application/json" \
  -d '{"nip": "5882436505"}'
```

### User API Endpoints

These endpoints require user authentication (regular or admin):

#### Chat & NordaGPT

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/chat/start` | POST | Start a new AI chat conversation |
| `/api/chat/<conversation_id>/message` | POST | Send a message in an existing conversation |
| `/api/chat/<conversation_id>/history` | GET | Retrieve conversation history |
| `/api/chat/feedback` | POST | Submit feedback on AI chat response (thumbs up/down) |

**Example - Start Chat:**
```bash
curl -X POST https://nordabiznes.pl/api/chat/start \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION" \
  -d '{"message": "Szukam firm IT w Wejherowie"}'
```

#### Notifications

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/notifications` | GET | Get user notifications (new news, approvals, etc.) |
| `/api/notifications/<notification_id>/read` | POST | Mark specific notification as read |
| `/api/notifications/read-all` | POST | Mark all notifications as read |
| `/api/notifications/unread-count` | GET | Get count of unread notifications |

**Example - Get Notifications:**
```bash
curl https://nordabiznes.pl/api/notifications \
  -H "Cookie: session=YOUR_SESSION"
```

#### Messages

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/messages/unread-count` | GET | Get count of unread private messages |

#### Recommendations

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/recommendations/<company_id>` | GET | Get recommendations for a company |
| `/api/recommendations/create` | POST | Create a new recommendation |
| `/api/recommendations/<rec_id>/edit` | POST | Edit existing recommendation |
| `/api/recommendations/<rec_id>/delete` | POST | Delete a recommendation |

### Admin API Endpoints

These endpoints require admin privileges (`is_admin=True`):

#### SEO Audits

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/seo/audit` | GET | Get all SEO audit results |
| `/api/seo/audit/<slug>` | GET | Get SEO audit for specific company |
| `/api/seo/audit` | POST | Trigger new SEO audit for company |

**Example - Trigger SEO Audit:**
```bash
curl -X POST https://nordabiznes.pl/api/seo/audit \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_ADMIN_SESSION" \
  -d '{"company_id": 26, "url": "https://example.com"}'
```

#### Google Business Profile Audits

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/gbp/audit/health` | GET | Check GBP audit service health |
| `/api/gbp/audit` | GET | Get all GBP audit results |
| `/api/gbp/audit/<slug>` | GET | Get GBP audit for specific company |
| `/api/gbp/audit` | POST | Trigger new GBP audit |

#### Social Media Audits

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/social/audit` | POST | Trigger social media profile audit |

#### IT Infrastructure Audits

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/it-audit/matches/<company_id>` | GET | Get collaboration matches for company |
| `/api/it-audit/history/<company_id>` | GET | Get IT audit history for company |
| `/api/it-audit/export` | GET | Export IT audit data (CSV format) |

#### User Management

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/admin/users/ai-parse` | POST | Parse user data from natural language using AI |
| `/api/admin/users/bulk-create` | POST | Create multiple users from parsed data |

#### Analytics & Monitoring

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/admin/chat-stats` | GET | Get AI chat usage statistics |
| `/api/admin/logs` | GET | Retrieve application logs |
| `/api/admin/logs/stream` | GET | Stream application logs (SSE) |
| `/api/admin/logs/clear` | POST | Clear application logs |
| `/api/admin/test-log` | POST | Generate test log entry |

### Company Refresh Endpoint

| Endpoint | Method | Description | Auth Required |
|----------|--------|-------------|---------------|
| `/api/company/<company_id>/refresh-krs` | POST | Refresh company data from KRS registry | User (company owner or admin) |

### Rate Limiting

The API implements rate limiting to ensure fair usage:

- **Global limit:** 200 requests per day per IP
- **Burst limit:** 50 requests per hour per IP
- **AI Chat:** 200 requests per day (Google Gemini free tier)
- **SEO Audits:** 25,000 requests per day (Google PageSpeed Insights free tier)
- **News Monitoring:** 2,000 requests per month (Brave Search API free tier)

### Error Responses

All API endpoints return standard HTTP status codes:

| Status Code | Meaning |
|-------------|---------|
| **200** | Success - Request completed successfully |
| **201** | Created - Resource created successfully |
| **400** | Bad Request - Invalid parameters or missing required fields |
| **401** | Unauthorized - Authentication required |
| **403** | Forbidden - Insufficient permissions (admin required) |
| **404** | Not Found - Resource does not exist |
| **429** | Too Many Requests - Rate limit exceeded |
| **500** | Internal Server Error - Server error occurred |

**Error Response Format:**
```json
{
  "error": "Error message",
  "details": "Additional error details (optional)"
}
```

### API Response Examples

**Success Response - Company List:**
```json
{
  "companies": [
    {
      "id": 1,
      "name": "PIXLAB Sp. z o.o.",
      "slug": "pixlab-sp-z-o-o",
      "category": "IT",
      "description": "Innowacyjne rozwiązania IT...",
      "nip": "5882436505",
      "website": "https://pixlab.pl",
      "email": "biuro@pixlab.pl",
      "phone": "+48 58 xxx xx xx",
      "city": "Wejherowo",
      "services": ["Strony WWW", "Aplikacje webowe"],
      "competencies": ["Python", "Flask", "React"]
    }
  ],
  "total": 80
}
```

**Success Response - SEO Audit:**
```json
{
  "company_id": 26,
  "company_name": "PIXLAB Sp. z o.o.",
  "url": "https://pixlab.pl",
  "seo_score": 92,
  "performance_score": 88,
  "accessibility_score": 95,
  "best_practices_score": 90,
  "audited_at": "2026-01-10T10:30:00Z"
}
```

**Error Response - Authentication Required:**
```json
{
  "error": "Authentication required",
  "details": "Please log in to access this endpoint"
}
```

### Web Interface Endpoints

In addition to JSON API endpoints, the application provides web interface routes:

#### Public Routes

- `/` - Company directory listing
- `/company/<slug>` - Company profile page
- `/search` - Search interface
- `/chat` - AI chat interface
- `/aktualnosci` - News feed
- `/forum` - Discussion forum
- `/kalendarz` - Events calendar
- `/tablica` - Classifieds board
- `/nowi-czlonkowie` - New members

#### Authentication Routes

- `/register` - User registration
- `/login` - User login
- `/logout` - User logout
- `/forgot-password` - Password recovery
- `/reset-password/<token>` - Password reset
- `/verify-email/<token>` - Email verification
- `/resend-verification` - Resend verification email

#### User Dashboard Routes

- `/dashboard` - User dashboard
- `/wiadomosci` - Private messages
- `/company/<slug>/recommend` - Submit recommendation

#### Admin Dashboard Routes

- `/admin/news` - News moderation panel
- `/admin/seo` - SEO audit dashboard
- `/admin/gbp-audit` - Google Business Profile audit
- `/admin/social-media` - Social media audit
- `/admin/social-audit` - Social media batch audit
- `/admin/it-audit` - IT infrastructure audit
- `/admin/forum` - Forum management
- `/admin/kalendarz` - Calendar management
- `/admin/users` - User management
- `/admin/fees` - Membership fees management
- `/admin/recommendations` - Recommendations moderation
- `/admin/chat-analytics` - AI chat analytics
- `/admin/digital-maturity` - Digital maturity assessment
- `/admin/debug` - Debug panel

#### Audit Detail Routes

- `/audit/seo/<slug>` - SEO audit details for company
- `/audit/social/<slug>` - Social media audit details
- `/audit/gbp/<slug>` - GBP audit details
- `/audit/it/<slug>` - IT audit details

### API Best Practices

1. **Always check the `/health` endpoint** before making API calls to ensure the service is available
2. **Implement exponential backoff** for rate-limited requests
3. **Cache responses** when appropriate to reduce API load
4. **Use HTTPS** in production for secure communication
5. **Handle errors gracefully** and provide meaningful error messages to users
6. **Log API requests** for debugging and monitoring purposes

### Further Documentation

For detailed information about specific features:
- **AI Chat:** See `nordabiz_chat.py` and `tests/ai_quality_test_cases.json`
- **Search System:** See `search_service.py` for SearchService implementation
- **Database Schema:** See `database/schema.sql` and `database.py`
- **External APIs:** See `CLAUDE.md` for integration details

## Common Commands Reference

Quick reference for frequently used development, testing, and deployment commands.

### Development Commands

```bash
# Start development environment
source venv/bin/activate              # Activate virtual environment
docker compose up -d                  # Start PostgreSQL container
python3 app.py                        # Run Flask development server

# Stop development environment
docker compose down                   # Stop PostgreSQL container
deactivate                            # Deactivate virtual environment
```

### Database Commands

```bash
# Database management
docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql  # Apply schema
psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "\dt"                          # List tables
psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT COUNT(*) FROM companies;"  # Count companies

# Database reset (⚠️ WARNING: Deletes all data!)
docker compose down -v                # Remove volumes
docker compose up -d                  # Recreate database
docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql  # Reapply schema
```

### Testing Commands

```bash
# Run AI quality tests
python run_ai_quality_tests.py         # Standard output
python run_ai_quality_tests.py -v      # Verbose mode
python run_ai_quality_tests.py -v -s   # Verbose + save results
python run_ai_quality_tests.py -q      # Quick (high-priority only)

# Run unit tests
python -m pytest tests/                            # All tests
python -m pytest tests/test_admin_seo_dashboard.py # Specific test
python -m pytest tests/ -v                         # Verbose output
python -m pytest tests/ --cov=.                    # With coverage

# Data verification
python verify_all_companies_data.py    # Check data quality
```

### Git & Deployment Commands

```bash
# Development: Push to both remotes
git push origin master && git push inpi master

# Production: Deploy to server
ssh maciejpi@10.22.68.249
cd /var/www/nordabiznes
sudo -u www-data git pull
sudo systemctl restart nordabiznes
curl -I https://nordabiznes.pl/health  # Verify deployment
```

### Production Service Management

```bash
# Service control (on production server)
sudo systemctl status nordabiznes      # Check status
sudo systemctl restart nordabiznes     # Restart service
sudo systemctl start nordabiznes       # Start service
sudo systemctl stop nordabiznes        # Stop service

# View logs
sudo journalctl -u nordabiznes -f      # Follow logs (live)
sudo journalctl -u nordabiznes -n 100  # Last 100 entries
```

### Health & Monitoring Commands

```bash
# Check application health
curl http://localhost:5000/health                    # Local
curl -I https://nordabiznes.pl/health                # Production

# Test API endpoints
curl http://localhost:5000/api/companies | jq '.total'          # Count companies
curl http://localhost:5000/api/model-info | jq '.model_name'    # Check AI model

# Check database connectivity
psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT 1;"  # Development
psql -U nordabiz_app -d nordabiz -h localhost -c "SELECT 1;"          # Production
```

### Audit Scripts

```bash
# Run audit scripts
cd scripts/
python seo_audit.py --company-id 26                    # Single company SEO audit
python seo_audit.py --batch 1-10                       # Batch SEO audit
python social_media_audit.py --company-id 26           # Social media audit
```

### Pre-Deployment Checklist Commands

```bash
# Before deployment, run these checks:
python -m py_compile app.py                            # Syntax check
python run_ai_quality_tests.py -v                      # AI quality (≥70%)
python -m pytest tests/ -v                             # Unit tests
python verify_all_companies_data.py                    # Data integrity
curl http://localhost:5000/health                      # Health check
```

For more detailed command documentation, see [`CLAUDE.md`](CLAUDE.md) and [`deployment_checklist.md`](deployment_checklist.md).

## Contributing

We welcome contributions to improve the Norda Biznes Partner platform! Here's how you can help.

### Development Workflow

1. **Fork and clone** the repository
2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
3. **Make your changes** following our code conventions (see below)
4. **Test thoroughly**:
   - Run AI quality tests: `python run_ai_quality_tests.py -v`
   - Run unit tests: `python -m pytest tests/ -v`
   - Verify manually in browser
5. **Commit your changes**: Use clear, descriptive commit messages
6. **Push to your fork**: `git push origin feature/your-feature-name`
7. **Create a Pull Request** with detailed description of changes

### Code Conventions

**Python Code:**
- Follow **PEP 8** style guide
- Use **4 spaces** for indentation (no tabs)
- **Type hints** where appropriate
- **Docstrings** for all functions and classes
- **No print statements** in production code (use `app.logger`)

**Jinja2 Templates:**
- **IMPORTANT**: The `{% block extra_js %}` in `base.html` is already inside a `<script>` tag
- **DO NOT** add your own `<script>` tags inside `extra_js` blocks (causes nesting errors)
- Correct: `{% block extra_js %}function foo() {...}{% endblock %}`
- Wrong: `{% block extra_js %}<script>function foo() {...}</script>{% endblock %}`

**Database Changes:**
- **Never edit production database directly**
- **Always test on development database** (Docker on port 5433) first
- **Create migration scripts** for schema changes in `database/migrations/`
- **Grant permissions** after creating new tables/sequences:
  ```sql
  GRANT ALL ON TABLE table_name TO nordabiz_app;
  GRANT USAGE, SELECT ON SEQUENCE sequence_name TO nordabiz_app;
  ```

**Git Commits:**
- Use **descriptive commit messages**
- Format: `"category: brief description"` (e.g., `"fix: Correct SEO scoring algorithm"`)
- Reference issue numbers when applicable: `"feat: Add GBP audit dashboard (#123)"`

### Testing Requirements

All contributions must include appropriate tests:

- **New features**: Add AI quality test cases to `tests/ai_quality_test_cases.json` if AI-related
- **Bug fixes**: Add regression tests to prevent future occurrences
- **API changes**: Update API documentation in README.md
- **All tests must pass** before PR can be merged (≥70% AI quality threshold)

### Code Review Process

1. All pull requests require review before merging
2. Automated checks must pass (syntax, tests)
3. Maintainers will review code for:
   - Code quality and conventions
   - Test coverage
   - Documentation updates
   - Security considerations
4. Address review feedback promptly
5. Once approved, maintainers will merge

### Documentation

When adding or modifying features:

- **Update README.md** if user-facing changes
- **Update CLAUDE.md** if architectural changes
- **Add inline code comments** for complex logic
- **Update API documentation** if endpoints change
- **Update deployment_checklist.md** if deployment process changes

### Questions or Need Help?

- Check [`CLAUDE.md`](CLAUDE.md) for comprehensive project documentation
- Review existing issues and pull requests
- Contact: biuro@norda-biznes.info

## Troubleshooting

Comprehensive troubleshooting guide for common issues.

### Development Environment Issues

#### Database Connection Errors

**Problem:** Cannot connect to PostgreSQL database

```bash
# Check if PostgreSQL container is running
docker ps | grep nordabiz-postgres

# If not running, start it
docker compose up -d

# Check logs for errors
docker logs nordabiz-postgres

# Test connection manually
psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "SELECT 1;"
```

**Problem:** "FATAL: password authentication failed"

```bash
# Ensure you're using the correct credentials from docker-compose.yml
# Development: nordabiz_app / dev_password on port 5433
# Check your .env file DATABASE_URL matches docker-compose.yml
```

#### Port Already in Use

**Problem:** Flask fails to start - port 5000 in use

```bash
# Option 1: Find and kill process using port 5000
lsof -ti:5000 | xargs kill -9

# Option 2: Use different port in .env
echo "PORT=5001" >> .env
python3 app.py
```

#### Missing Dependencies

**Problem:** ImportError or ModuleNotFoundError

```bash
# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate on Windows
which python  # Should show path to venv/bin/python

# Reinstall all dependencies
pip install -r requirements.txt --force-reinstall

# If specific package fails, try upgrading pip first
pip install --upgrade pip
pip install -r requirements.txt
```

#### Database Schema Issues

**Problem:** Missing tables or schema errors

```bash
# Reset database (⚠️ WARNING: Deletes all data!)
docker compose down -v
docker compose up -d
docker exec -i nordabiz-postgres psql -U nordabiz_app -d nordabiz < database/schema.sql

# Verify tables exist
psql -U nordabiz_app -d nordabiz -h localhost -p 5433 -c "\dt"
```

### Testing Issues

#### AI Tests Failing

**Problem:** AI quality tests below 70% threshold

```bash
# Check Gemini API key is configured
grep GOOGLE_GEMINI_API_KEY .env

# Verify database has companies data
python -c "from database import SessionLocal, Company; db = SessionLocal(); print(f'Companies: {db.query(Company).count()}'); db.close()"
# Expected: 80 companies

# Check API rate limits (200 req/day)
# Wait if limit exceeded, or use different API key
```

**Problem:** Import errors in tests

```bash
# Ensure all dependencies installed
pip install -r requirements.txt

# Verify virtual environment activated
which python  # Should point to venv/bin/python

# Try running from project root
cd /path/to/nordabiz
python run_ai_quality_tests.py -v
```

### Production Issues

#### Application Not Responding

**Problem:** nordabiznes.pl not loading

```bash
# SSH to production server
ssh maciejpi@10.22.68.249

# Check service status
sudo systemctl status nordabiznes

# If stopped, start it
sudo systemctl start nordabiznes

# Check logs for errors
sudo journalctl -u nordabiznes -n 100

# Restart if needed
sudo systemctl restart nordabiznes

# Verify health
curl -I https://nordabiznes.pl/health
```

#### Redirect Loop / 502 Errors

**Problem:** Browser shows redirect loop or 502 Bad Gateway

**Cause:** NPM proxy forwarding to wrong port (80 instead of 5000)

**Solution:**
1. Access Nginx Proxy Manager: http://10.22.68.250:81
2. Find Proxy Host for nordabiznes.pl (ID: 27)
3. **Verify Forward Port is 5000** (NOT 80)
4. Save and test: `curl -I https://nordabiznes.pl/health`

See [`docs/INCIDENT_REPORT_20260102.md`](docs/INCIDENT_REPORT_20260102.md) for detailed incident analysis.

#### Database Connection Issues in Production

**Problem:** Application can't connect to database

```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U nordabiz_app -d nordabiz -h localhost -c "SELECT 1;"

# Check logs
sudo journalctl -u postgresql -n 50

# Restart if needed
sudo systemctl restart postgresql
```

#### Permission Denied Errors

**Problem:** Git pull or file write errors

**Cause:** Running commands as wrong user

**Solution:**
```bash
# Always use www-data for application operations
sudo -u www-data git pull
sudo -u www-data python3 verify_all_companies_data.py

# SSH as maciejpi (NOT root!)
ssh maciejpi@10.22.68.249
```

### API & External Service Issues

#### Google API Errors

**Problem:** Gemini/PageSpeed/Places API errors

```bash
# Check API keys are configured
grep GOOGLE .env

# Verify API key validity at:
# - Gemini: https://ai.google.dev/
# - PageSpeed: https://developers.google.com/speed/docs/insights/v5/get-started
# - Places: https://console.cloud.google.com/apis/credentials

# Check rate limits:
# - Gemini: 200 requests/day
# - PageSpeed: 25,000 requests/day
# - Places: $200/month credit
```

**Problem:** "Invalid API key" errors

**Solution:** Regenerate API key in Google Cloud Console and update `.env`

### Common Error Messages

| Error | Cause | Solution |
|-------|-------|----------|
| `sqlalchemy.exc.OperationalError` | Database not accessible | Check PostgreSQL is running, verify credentials |
| `werkzeug.exceptions.NotFound` | Route doesn't exist | Check URL path, verify route in app.py |
| `jinja2.exceptions.TemplateNotFound` | Missing template file | Verify template exists in templates/ directory |
| `InFailedSqlTransaction` | Database transaction failed | Check database logs, ensure rollback after errors |
| `flask_limiter.errors.RateLimitExceeded` | Too many requests | Wait for rate limit reset, or increase limits |

### Getting Additional Help

If issues persist after trying these solutions:

1. **Check documentation**: [`CLAUDE.md`](CLAUDE.md) has extensive troubleshooting
2. **Review logs**:
   - Development: Check Flask console output
   - Production: `sudo journalctl -u nordabiznes -n 200`
3. **Database logs**: `docker logs nordabiz-postgres` (dev) or `sudo journalctl -u postgresql` (prod)
4. **Check health endpoint**: `curl -I https://nordabiznes.pl/health`
5. **Contact support**: biuro@norda-biznes.info

For detailed database troubleshooting, see [`database/README.md`](database/README.md).

## Resources & Documentation

Additional documentation and resources for developers.

### Project Documentation

| Document | Description | Location |
|----------|-------------|----------|
| **CLAUDE.md** | Comprehensive project documentation for AI and developers | [`CLAUDE.md`](CLAUDE.md) |
| **deployment_checklist.md** | Production deployment procedures | [`deployment_checklist.md`](deployment_checklist.md) |
| **database/README.md** | Database schema and management guide | [`database/README.md`](database/README.md) |
| **database/schema.sql** | Complete PostgreSQL schema | [`database/schema.sql`](database/schema.sql) |
| **data/data-sources.md** | Data source documentation | [`data/data-sources.md`](data/data-sources.md) |

### Incident Reports

| Report | Date | Description |
|--------|------|-------------|
| **INCIDENT_REPORT_20260102.md** | 2026-01-02 | NPM proxy redirect loop incident | [`docs/INCIDENT_REPORT_20260102.md`](docs/INCIDENT_REPORT_20260102.md) |

### Key Files Reference

**Core Application:**
- `app.py` - Main Flask application (routes, authentication, admin panels)
- `database.py` - SQLAlchemy models (20+ tables)
- `requirements.txt` - Python dependencies (16 packages)

**Service Modules:**
- `gemini_service.py` - Google Gemini AI integration
- `nordabiz_chat.py` - AI chat engine with company context
- `search_service.py` - Unified search service (FTS, fuzzy, synonyms)
- `email_service.py` - Microsoft Graph email integration
- `krs_api_service.py` - Polish business registry API
- `gbp_audit_service.py` - Google Business Profile audit
- `it_audit_service.py` - IT infrastructure audit

**Configuration:**
- `.env.example` - Environment variables template
- `docker-compose.yml` - PostgreSQL development database
- `.gitignore` - Git ignore patterns

**Testing:**
- `run_ai_quality_tests.py` - AI quality test runner
- `tests/ai_quality_test_cases.json` - 15 test cases in 8 categories
- `tests/ai_quality_evaluator.py` - AI testing framework

### External Resources

**API Documentation:**
- [Google Gemini AI](https://ai.google.dev/) - AI chat and recommendations
- [Google PageSpeed Insights API](https://developers.google.com/speed/docs/insights/v5/get-started) - SEO audits
- [Google Places API](https://developers.google.com/maps/documentation/places/web-service/overview) - Business verification
- [KRS Open API](https://api-krs.ms.gov.pl/) - Polish business registry
- [Brave Search API](https://brave.com/search/api/) - News monitoring

**Technology Documentation:**
- [Flask 3.0](https://flask.palletsprojects.com/) - Web framework
- [SQLAlchemy 2.0](https://docs.sqlalchemy.org/) - ORM
- [PostgreSQL](https://www.postgresql.org/docs/) - Database
- [Jinja2](https://jinja.palletsprojects.com/) - Template engine

### Git Repositories

| Repository | URL | Purpose |
|------------|-----|---------|
| **GitHub** (origin) | https://github.com/pienczyn/nordabiz | Cloud backup, public access |
| **Gitea** (inpi) | https://10.22.68.180:3000/maciejpi/nordabiz | Internal backup, deployment source |

### Production Environment

- **Server:** NORDABIZ-01 (VM 249, IP: 10.22.68.249)
- **Reverse Proxy:** R11-REVPROXY-01 (VM 119, IP: 10.22.68.250)
- **URL:** https://nordabiznes.pl
- **Status:** LIVE since 2025-11-23

For production access and monitoring, see [Deployment & Production](#deployment--production).

## Roadmap & Future Enhancements

While the platform is fully functional and in production, the following features are planned for future releases:

### Enhanced Company Profiles
- [ ] Photo galleries for company showcases
- [ ] Product/service catalog with detailed descriptions
- [ ] Company achievements and awards timeline
- [ ] Employee directory and team profiles

### Networking & Collaboration
- [ ] Direct messaging system between member companies
- [ ] Collaboration opportunities board
- [ ] Joint project proposals and consortium building
- [ ] Recommendation and referral system

### B2B Marketplace
- [ ] Dedicated marketplace for B2B offers
- [ ] Business partner matching algorithm
- [ ] RFP/RFQ posting and bidding system
- [ ] Contract management tools

### Analytics & Reporting
- [ ] Company analytics dashboard
- [ ] Member engagement metrics
- [ ] Platform usage statistics
- [ ] Custom reporting tools

### Integration & Automation
- [ ] Newsletter system for member updates
- [ ] CRM integration capabilities
- [ ] Automated data enrichment workflows
- [ ] Third-party service integrations

**Note:** Features are prioritized based on member feedback and business value. See `CLAUDE.md` for detailed roadmap planning.

---

## Contact

**Norda Biznes - Regionalna Izba Przedsiębiorców**

- **Address**: ul. 12 Marca 238/5, 84-200 Wejherowo
- **Email**: biuro@norda-biznes.info
- **Phone**: +48 729 716 400
- **Website**: https://norda-biznes.info
- **Platform**: https://nordabiznes.pl

---

## License

Project created for Norda Biznes - Regional Chamber of Entrepreneurs

© 2025 Norda Biznes. All rights reserved.
