panel/README.md

eProjektant Wastpol - Project Management System

A comprehensive project management system built with Next.js 15 for managing construction and design projects. Tailored for Polish construction/engineering companies with full Polish localization, GIS integration, and enterprise-grade features.

🌟 Overview

eProjektant Wastpol is a production-ready, full-stack web application designed to manage the complete lifecycle of design and construction projects. It features advanced task tracking, contact management, document generation, file attachments, and automated workflows with role-based access control.

✨ Key Features

📋 Project Management

• Full Project Lifecycle Tracking - From registration to fulfillment
• Project Types: Design, Construction, or Combined (Design+Construction)
• Project Statuses: Registered, In Progress (Design/Construction), Fulfilled, Cancelled
• Contract Integration - Link multiple projects to contracts
• GIS Coordinates - Map integration with Polish coordinate systems (EPSG:2180)
• Advanced Search & Filtering - Filter by status, type, customer, assigned user
• User Assignment - Track project ownership and assignments
• Budget Tracking - Monitor project values (wartość zlecenia)
• Completion Tracking - Track planned vs actual completion dates
• Field History - Audit trail for critical field changes (finish dates, etc.)

📄 Contract Management

• Complete Contract CRUD - Create, read, update, delete contracts
• Customer & Investor Tracking - Separate fields for both parties
• Contract Numbers - Both company and customer contract numbering
• Multi-Project Contracts - One contract can have many projects
• Date Tracking - Signing dates and finish dates
• File Attachments - Upload contract documents

✅ Advanced Task System

• Task Templates - Reusable task templates for both design and construction
• Task Sets - Pre-configured groups of tasks for quick project setup
• Task Categories - Separate design and construction task libraries
• Custom Tasks - Add one-off tasks specific to individual projects
• Task Statuses: Not Started, In Progress, Completed, Cancelled
• Priority Levels - Task prioritization
• Max Wait Days - Built-in deadline tracking for each task type
• Task Assignment - Assign tasks to team members
• Task Notes - Detailed notes and comments per task
• Date Tracking - Started, completed, and due dates

👥 Contact Management

• Comprehensive Contact Database - Phone, email, company, position
• Contact Types: Project, Contractor, Office, Supplier, Other
• Many-to-Many Relationships - Link multiple contacts to projects
• Primary Contact Designation - Mark primary contacts per project
• CardDAV/Radicale Sync - Bi-directional sync with CardDAV servers
• Contact Export - Export contacts to VCard format
• Contact Statistics - Usage tracking and analytics

📄 Document Generation

• DOCX Template System - Upload Word templates with placeholders
• Dynamic Document Generation - Generate documents from project/contract data
• Template Variables - Support for project fields, contract data, coordinates
• Template Management - Upload, edit, soft-delete templates
• Download Generated Docs - Instant document generation and download

📎 File Management

• Generic Attachment System - Files for contracts, projects, and tasks
• Multi-File Upload - Upload multiple files simultaneously
• File Metadata - Track uploader, date, description, file type
• File Size Limit - 10MB per file
• Supported Types: PDF, Word, Excel, Images, Text
• Inline Viewing - View PDFs and images in browser
• File Descriptions - Editable descriptions for organization

🔔 Notification System

• In-App Notifications - Real-time notification center
• Notification Types: Task Assigned, Status Changes, Due Date Reminders, System Announcements, Mentions
• Priority Levels: Low, Normal, High, Urgent
• Read/Unread Tracking - Mark notifications as read
• Auto-Expire - Optional expiration dates
• Action URLs - Click to navigate to related resources
• Unread Count Badge - Visual indicator in navigation

🗺️ Geographic Information System (GIS)

• Interactive Maps - Leaflet-based map interface
• Polish Coordinate Systems - EPSG:2180 (Polish 1992), EPSG:3857 (Web Mercator)
• 8 Base Layers:
  • OpenStreetMap (default)
  • Polish Orthophoto (Standard & High Resolution WMTS)
  • Google Satellite, Hybrid, Roads
  • Esri Satellite
  • CartoDB Topographic
• 6 Overlay Layers (with transparency):
  • Polish Cadastral Data (WMS)
  • Polish Spatial Planning (WMS)
  • LP-Portal Roads, Street Names, Parcels, Survey Markers (WMS)
• Project Location Markers - Plot projects on map
• Route Planning - Optimization for project visits

🔐 Security & Authentication

• NextAuth.js v5 - Modern authentication with credential provider
• 5 User Roles:
  • Admin - Full system access, user management
  • Project Manager - Full access except user management
  • Team Lead - Specialized dashboard access
  • User - Standard project/task access
  • Read Only - View-only permissions
• Account Security:
  • Password hashing with bcrypt
  • Account lockout after 5 failed attempts (15-minute lock)
  • Secure session management
  • Failed login tracking
• Route Protection - Middleware-based authentication
• API Authorization - Per-route authorization middleware
• Audit Logging - Comprehensive security event tracking

📊 Audit & Compliance

• Comprehensive Audit Log - All user actions tracked
• Audit Event Types: Login, CRUD operations, file operations
• Field Change History - Track changes to critical fields
• System Notes - Auto-generated notes for status changes
• IP Address Tracking - Security monitoring
• User Agent Logging - Device/browser tracking
• Audit Statistics - Usage analytics and reporting
• Compliance Ready - Full audit trail for regulatory compliance

📈 Reporting & Export

• Excel Export - Export projects grouped by status
• PDF Generation - Generate PDF reports (jsPDF + AutoTable)
• Project Statistics - Dashboard with key metrics
• Audit Reports - Comprehensive activity reports
• Contact Statistics - Contact usage analytics
• Custom Reports - Extensible reporting framework

🌍 Internationalization

• Polish Primary - Full Polish translation (~1200+ keys)
• English Support - Complete English translation
• Client-Side i18n - Dynamic language switching
• Server-Side Translations - API response localization
• Date Formatting - Locale-aware date formatting
• Number Formatting - Currency and number localization

🔄 Automated Tasks

• Daily Database Backup - Automatic SQLite backups (keeps last 30)
• Due Date Reminders - Notifications 3 days and 1 day before deadline
• Cron Job Management - Admin interface for cron status/control
• Background Processing - Async task execution
• Notification System - Automated alerts to assigned users

🎨 Modern UI/UX

• Dark/Light Themes - User-selectable theme with system preference detection
• Responsive Design - Mobile-first, optimized for all screen sizes
• Component Library - Reusable UI components (40+ components)
• Loading States - Skeleton screens and spinners
• Error Handling - User-friendly error messages
• Toast Notifications - Non-intrusive feedback
• Modal Dialogs - Clean form interfaces
• Drag & Drop - File upload with drag-and-drop
• Search Autocomplete - Real-time search suggestions
• Badge System - Visual status indicators
• Tailwind CSS - Modern utility-first styling

🛠️ Tech Stack

Frontend

• Framework: Next.js 15.1.11 with App Router (React 19)
• Styling: Tailwind CSS 3.4 with custom theme
• UI Components: Custom component library (40+ components)
• State Management: React hooks + NextAuth session
• Forms: Native with Zod validation
• Maps: Leaflet 1.9.4 + React-Leaflet 5.0
• Charts: Recharts 2.15
• Date Handling: date-fns 4.1
• Projections: Proj4 + Proj4Leaflet for coordinate transformations

Backend

• Runtime: Node.js (v22.11.0)
• API: Next.js API Routes (Node.js runtime)
• Database: SQLite with better-sqlite3 11.10
• Authentication: NextAuth.js v5.0 (beta)
• Password Hashing: bcryptjs 3.0
• Validation: Zod 3.25
• Sessions: Custom SQLite session store

Document Processing

• DOCX: Docxtemplater 3.67 + PizZip 3.2
• Excel: ExcelJS 4.4 + XLSX 0.18
• PDF: jsPDF 3.0 + jsPDF-AutoTable 5.0
• Screenshots: html2canvas 1.4

Infrastructure

• Container: Docker with multi-stage builds
• Orchestration: Docker Compose
• Cron: Linux cron for scheduled tasks
• Timezone: Europe/Warsaw
• Proxy: Nginx (recommended for production)

Development Tools

• Testing:
  • Playwright 1.40 (E2E tests)
  • Jest 29.7 + Testing Library (unit/integration)
• Linting: ESLint 9 with Next.js config
• Type Safety: JSDoc annotations (future TypeScript migration ready)
• Version Control: Git
• CI/CD: Docker-based deployment pipeline

External Integrations

• Map Services:
  • Polish Geoportal (WMTS/WMS)
  • Google Maps
  • OpenStreetMap
  • Esri
  • CartoDB
  • LP-Portal (Polish cadastral data)
• CardDAV: Radicale server sync for contacts
• Email: SMTP support (configurable)

🚀 Getting Started

Prerequisites

• Node.js v16+ (v22.11.0 recommended for production)
• npm or yarn
• Docker & Docker Compose (optional, recommended for production)
• Git (for version control and git-based deployment)

Installation

Option 1: Local Development

1. Clone the repository

git clone <repository-url>
cd panel

2. Install dependencies

npm install

3. Initialize the database

The database will auto-initialize on first run, or you can manually run:

node src/lib/init-db.js

4. Create an admin user

npm run create-admin

Follow the prompts to create your first admin account.

5. Start development server

npm run dev

6. Open in browser

Navigate to http://localhost:3000

Option 2: Docker Development

1. Clone the repository

git clone <repository-url>
cd panel

2. Start with Docker Compose

docker-compose -f docker-compose.yml up --build

3. Create admin user (in container)

docker-compose exec app npm run create-admin

4. Open in browser

Navigate to http://localhost:3000

Option 3: Production Deployment with Docker

1. Set environment variables

Create a .env file:

NEXTAUTH_SECRET=your-very-secure-random-string-at-least-32-characters
NEXTAUTH_URL=https://yourdomain.com
GIT_REPO_URL=https://github.com/yourusername/panel.git
GIT_BRANCH=main

2. Deploy with Docker Compose

docker-compose -f docker-compose.prod.yml up -d

3. Setup cron jobs (inside container)

docker-compose exec app bash setup-cron.sh

4. Create admin user

docker-compose exec app npm run create-admin

The application will be available on port 3001 (mapped from internal 3000).

Configuration

Environment Variables

• NODE_ENV - Environment mode (development or production)
• NEXTAUTH_SECRET - Secret key for NextAuth.js sessions (min 32 chars)
• NEXTAUTH_URL - Full URL of your application
• AUTH_TRUST_HOST - Set to true for production behind reverse proxy
• TZ - Timezone (default: Europe/Warsaw)
• NODE_OPTIONS - Node.js options (default: --max-old-space-size=2048)

Docker Build Arguments

• GIT_REPO_URL - Git repository URL for deployment
• GIT_BRANCH - Branch to deploy (default: main)
• GIT_COMMIT - Specific commit to deploy (optional)

Database Setup

The application uses SQLite with automatic initialization. On first run:

1. Database file created at data/database.sqlite
2. All tables created automatically
3. Indexes created for performance
4. Default settings inserted

Database location: ./data/database.sqlite

Backup location: ./backups/

Migrations: Handled automatically via init-db.js with try-catch blocks

📁 Project Structure

panel/
├── src/
│   ├── app/                          # Next.js App Router
│   │   ├── api/                      # API Routes (25+ endpoints)
│   │   │   ├── admin/               # Admin endpoints
│   │   │   │   ├── users/           # User management CRUD
│   │   │   │   ├── settings/        # System settings
│   │   │   │   └── cron/            # Cron job management
│   │   │   ├── audit-logs/          # Audit log endpoints
│   │   │   ├── auth/                # Authentication
│   │   │   │   ├── [...nextauth]/   # NextAuth handler
│   │   │   │   └── change-password/ # Password change
│   │   │   ├── contacts/            # Contact management
│   │   │   ├── contracts/           # Contract CRUD
│   │   │   ├── files/               # File upload/download
│   │   │   ├── field-history/       # Field change history
│   │   │   ├── notes/               # Notes CRUD
│   │   │   ├── notifications/       # Notification system
│   │   │   ├── projects/            # Project CRUD + export
│   │   │   ├── project-tasks/       # Project task instances
│   │   │   ├── reports/             # Reporting endpoints
│   │   │   ├── tasks/               # Task templates
│   │   │   ├── task-sets/           # Task set management
│   │   │   └── templates/           # DOCX templates + generation
│   │   ├── admin/                   # Admin pages
│   │   │   ├── users/               # User management UI
│   │   │   └── settings/            # Settings UI
│   │   ├── auth/                    # Auth pages
│   │   │   ├── signin/              # Login page
│   │   │   └── error/               # Auth error page
│   │   ├── calendar/                # Calendar view
│   │   ├── contacts/                # Contact pages
│   │   ├── contracts/               # Contract pages
│   │   ├── dashboard/               # Team lead dashboard
│   │   ├── projects/                # Project pages
│   │   │   ├── [id]/                # Single project view
│   │   │   └── page.js              # Project list
│   │   ├── project-tasks/           # Project task pages
│   │   ├── settings/                # User settings
│   │   ├── tasks/                   # Task template pages
│   │   ├── task-sets/               # Task set pages
│   │   ├── templates/               # Template management pages
│   │   ├── layout.js                # Root layout with providers
│   │   ├── page.js                  # Home (redirects to projects)
│   │   └── globals.css              # Global styles
│   ├── components/                   # React Components (40+)
│   │   ├── ui/                      # Reusable UI components
│   │   │   ├── Navigation.js        # Main navigation
│   │   │   ├── Button.js            # Button component
│   │   │   ├── Card.js              # Card component
│   │   │   ├── Input.js             # Form inputs
│   │   │   ├── Badge.js             # Status badges
│   │   │   ├── SearchBar.js         # Search component
│   │   │   ├── PageContainer.js     # Page wrapper
│   │   │   └── States.js            # Loading/error states
│   │   ├── auth/                    # Auth components
│   │   │   └── AuthProvider.js      # Session provider
│   │   ├── reports/                 # Reporting components
│   │   ├── settings/                # Settings components
│   │   ├── project-view/            # Project detail components
│   │   ├── AuditLogViewer.js        # Audit log viewer
│   │   ├── ContactForm.js           # Contact form
│   │   ├── ContractForm.js          # Contract form
│   │   ├── DocumentGenerator.js     # DOCX generator
│   │   ├── FileUploadModal.js       # File upload UI
│   │   ├── FileAttachmentsList.js   # File list
│   │   ├── NoteForm.js              # Note editor
│   │   ├── ProjectForm.js           # Project form
│   │   ├── ProjectTaskForm.js       # Task form
│   │   ├── TaskTemplateForm.js      # Template form
│   │   ├── ThemeProvider.js         # Theme context
│   ├── lib/                          # Utilities & Backend Logic
│   │   ├── queries/                 # Database queries
│   │   │   ├── projects.js          # Project queries
│   │   │   ├── tasks.js             # Task queries
│   │   │   ├── contacts.js          # Contact queries
│   │   │   ├── contracts.js         # Contract queries
│   │   │   ├── notes.js             # Note queries
│   │   │   └── fieldHistory.js      # History queries
│   │   ├── schemas/                 # Zod validation schemas
│   │   ├── middleware/              # Auth middleware
│   │   │   ├── auth.js              # Auth wrappers
│   │   │   └── auditLog.js          # Audit middleware
│   │   ├── auth.js                  # NextAuth config
│   │   ├── db.js                    # Database connection
│   │   ├── init-db.js               # Database initialization
│   │   ├── auditLog.js              # Audit logging
│   │   ├── auditLogSafe.js          # Edge-safe audit logging
│   │   ├── notifications.js         # Notification system
│   │   ├── userManagement.js        # User CRUD
│   │   ├── radicale-sync.js         # CardDAV sync
│   │   ├── routeUtils.js            # Route optimization
│   │   ├── i18n.js                  # Internationalization
│   │   ├── serverTranslations.js    # Server-side i18n
│   │   └── utils.js                 # Utility functions
│   └── middleware.js                 # Next.js middleware (auth)
├── public/                           # Static assets
│   ├── uploads/                     # User uploads
│   │   ├── contracts/               # Contract files
│   │   ├── projects/                # Project files
│   │   └── tasks/                   # Task files
│   ├── templates/                   # DOCX template files
│   └── leaflet/                     # Leaflet assets
├── data/                            # SQLite database
│   └── database.sqlite              # Main database file
├── backups/                         # Database backups
├── templates/                       # Server-side templates
├── scripts/                         # Utility scripts
│   ├── create-admin.js              # Create admin user
│   ├── create-test-data.js          # Generate test data
│   └── create-sample-projects.js    # Sample data
├── __tests__/                       # Test files
│   ├── api/                         # API tests
│   ├── components/                  # Component tests
│   └── queries/                     # Query tests
├── e2e/                             # Playwright E2E tests
├── docs/                            # Documentation
│   └── MAP_LAYERS.md                # Map layer configuration
├── backup-db.mjs                    # Backup script
├── send-due-date-reminders.mjs      # Reminder script
├── export-projects-to-excel.mjs     # Export script
├── export-contacts-to-radicale.mjs  # CardDAV export
├── setup-cron.sh                    # Cron setup script
├── docker-entrypoint.sh             # Docker startup
├── Dockerfile                       # Production Docker image
├── Dockerfile.dev                   # Development Docker image
├── docker-compose.yml               # Development compose
├── docker-compose.prod.yml          # Production compose
├── next.config.mjs                  # Next.js config
├── tailwind.config.mjs              # Tailwind config
├── package.json                     # Dependencies
└── README.md                        # This file

📜 Available Scripts

Development

• npm run dev - Start development server on port 3000
• npm run build - Build for production (outputs to .next/)
• npm run start - Start production server
• npm run lint - Run ESLint for code quality

Testing

• npm test - Run Jest unit/integration tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate test coverage report
• npm run test:e2e - Run Playwright E2E tests
• npm run test:e2e:ui - Run Playwright tests with UI

Utilities

• npm run create-admin - Interactive admin user creation
• npm run export-projects - Export all projects to Excel file
• npm run send-due-date-reminders - Manually trigger due date reminders
• npm run test-due-date-reminders - Test reminder functionality

Production Scripts (run in container)

• backup-db.mjs - Create database backup (scheduled via cron)
• send-due-date-reminders.mjs - Send due date notifications (scheduled via cron)
• export-contacts-to-radicale.mjs - One-time CardDAV export
• setup-cron.sh - Setup automated cron jobs

🐳 Docker Commands

Development

# Start development environment
docker-compose up

# Rebuild and start
docker-compose up --build

# Stop containers
docker-compose down

# View logs
docker-compose logs -f

# Execute commands in container
docker-compose exec app npm run create-admin

Production

# Deploy production
docker-compose -f docker-compose.prod.yml up -d

# View production logs
docker-compose -f docker-compose.prod.yml logs -f app

# Restart production
docker-compose -f docker-compose.prod.yml restart

# Stop production
docker-compose -f docker-compose.prod.yml down

# Backup database
docker-compose -f docker-compose.prod.yml exec app node backup-db.mjs

# Access container shell
docker-compose -f docker-compose.prod.yml exec app bash

Git-Based Deployment

# Deploy from Git repository
GIT_REPO_URL=https://github.com/user/repo.git \
GIT_BRANCH=main \
docker-compose -f docker-compose.prod.yml up -d --build

# Deploy specific commit
GIT_REPO_URL=https://github.com/user/repo.git \
GIT_COMMIT=abc123 \
docker-compose -f docker-compose.prod.yml up -d --build

🗄️ Database Schema

The application uses SQLite with the following comprehensive schema:

Core Business Entities

contracts

• Contract management with customer/investor tracking
• Fields: contract_id, contract_number, customer_contract_number, contract_name, customer, investor, date_signed, finish_date

projects

• Design and construction project tracking
• Fields: project_id, contract_id (FK), project_name, project_number, address, plot, district, unit, city, investment_number, finish_date, completion_date, wp, contact, notes, wartosc_zlecenia, project_type, project_status, coordinates, created_by, assigned_to, created_at, updated_at
• Types: design, construction, design+construction
• Statuses: registered, in_progress_design, in_progress_construction, fulfilled, cancelled

tasks

• Reusable task templates
• Fields: task_id, name, description, max_wait_days, is_standard, task_category
• Categories: design, construction

task_sets

• Pre-configured task groups
• Fields: set_id, name, description, task_category, created_at, updated_at

task_set_templates

• Junction table for tasks in sets
• Fields: set_id (FK), task_template_id (FK), sort_order

project_tasks

• Task instances assigned to projects
• Fields: id, project_id (FK), task_template_id (FK), custom_task_name, custom_description, custom_max_wait_days, status, date_added, date_started, date_completed, priority, created_by, assigned_to, created_at, updated_at
• Statuses: not_started, pending, in_progress, completed, cancelled

notes

• Project and task notes
• Fields: note_id, project_id (FK), task_id (FK), note, note_date, created_by, is_system

contacts

• Contact database
• Fields: contact_id, name, phone, email, company, position, contact_type, notes, is_active, created_at, updated_at
• Types: project, contractor, office, supplier, other

project_contacts

• Many-to-many project-contact relationships
• Fields: project_id (FK), contact_id (FK), relationship_type, is_primary, added_at, added_by

Authentication & Security

users

• User accounts with roles
• Fields: id, name, username, password_hash, role, created_at, updated_at, is_active, last_login, failed_login_attempts, locked_until
• Roles: admin, project_manager, team_lead, user, read_only

sessions

• NextAuth session management
• Fields: id, session_token, user_id (FK), expires, created_at

audit_logs

• Comprehensive audit trail
• Fields: id, user_id (FK), action, resource_type, resource_id, ip_address, user_agent, timestamp, details

password_reset_tokens

• Password reset functionality
• Fields: id, user_id (FK), token, expires_at, used, created_at

File Management

file_attachments

• Generic file storage for entities
• Fields: file_id, entity_type, entity_id, original_filename, stored_filename, file_path, file_size, mime_type, description, uploaded_by, upload_date
• Entity types: contract, project, task

docx_templates

• DOCX template management
• Fields: template_id, template_name, description, original_filename, stored_filename, file_path, file_size, mime_type, is_active, created_at, created_by, updated_at

Audit & History

field_change_history

• Track field-level changes
• Fields: id, table_name, record_id, field_name, old_value, new_value, changed_by, changed_at, change_reason

Notifications

notifications

• In-app notification system
• Fields: id, user_id (FK), type, title, message, resource_type, resource_id, is_read, priority, created_at, expires_at, action_url
• Types: task_assigned, task_status_changed, project_updated, due_date_reminder, system_announcement, mention
• Priorities: low, normal, high, urgent

Settings

settings

• Application configuration
• Fields: key, value, description, updated_at, updated_by

Indexes

Performance-optimized with indexes on:

• User lookups (username, id)
• Session tokens
• Audit log queries (user_id + timestamp)
• Project/task assignments
• File entity lookups
• Contact relationships
• Notification queries

🔌 API Endpoints

Projects

• GET /api/projects - Get all projects with filters (status, type, customer, assigned user)
• POST /api/projects - Create new project (requires user auth)
• GET /api/projects/[id] - Get project by ID with contract details
• PUT /api/projects/[id] - Update project (requires user auth)
• DELETE /api/projects/[id] - Delete project (requires user auth)
• GET /api/projects/export - Export projects to Excel (read-only auth)

Contracts

• GET /api/contracts - Get all contracts (read-only auth)
• POST /api/contracts - Create new contract (requires user auth)
• GET /api/contracts/[id] - Get contract by ID (read-only auth)
• DELETE /api/contracts/[id] - Delete contract (requires user auth)

Tasks (Templates)

• GET /api/tasks - Get task templates with filters (category)
• POST /api/tasks - Create new task template (requires user auth)
• GET /api/tasks/[id] - Get task template by ID (read-only auth)
• PUT /api/tasks/[id] - Update task template (requires user auth)
• DELETE /api/tasks/[id] - Delete task template (requires user auth)

Task Sets

• GET /api/task-sets - Get all task sets with filters
• POST /api/task-sets - Create new task set (requires user auth)
• GET /api/task-sets/[id] - Get task set with tasks (read-only auth)
• PUT /api/task-sets/[id] - Update task set (requires user auth)
• DELETE /api/task-sets/[id] - Delete task set (requires user auth)

Project Tasks (Instances)

• GET /api/project-tasks - Get project tasks with filters (project_id, status)
• POST /api/project-tasks - Create new project task (requires user auth)
• GET /api/all-project-tasks - Get all project tasks across projects (read-only auth)
• PUT /api/project-tasks/[id] - Update project task (requires user auth)
• PATCH /api/project-tasks/[id] - Update task status (requires user auth)
• DELETE /api/project-tasks/[id] - Delete project task (requires user auth)

Contacts

• GET /api/contacts - Get all contacts with filters and stats (requires auth)
• POST /api/contacts - Create new contact (requires auth)
• GET /api/contacts/[id] - Get contact by ID (requires auth)
• PUT /api/contacts/[id] - Update contact (requires auth)
• DELETE /api/contacts/[id] - Delete contact (requires auth)
• POST /api/contacts/[id]/sync - Sync contact to Radicale (requires auth)

Notes

• GET /api/notes - Get notes with filters (project_id, task_id) (read-only auth)
• POST /api/notes - Create new note (requires user auth)
• PUT /api/notes/[id] - Update note (requires user auth)
• DELETE /api/notes - Delete note (requires user auth)

Files

• POST /api/files - Upload file (entity_type, entity_id, file)
• GET /api/files - Get files with filters (entity_type, entity_id)
• GET /api/files/[fileId] - Download/view file
• PUT /api/files/[fileId] - Update file metadata
• DELETE /api/files/[fileId] - Delete file

Templates (DOCX)

• GET /api/templates - Get all DOCX templates
• POST /api/templates - Upload new template
• PUT /api/templates/[id] - Update template metadata
• DELETE /api/templates/[id] - Soft-delete template
• POST /api/templates/generate - Generate document from template
• GET /api/templates/download/[filename] - Download template file

Notifications

• GET /api/notifications - Get user notifications (paginated)
• PUT /api/notifications - Mark notifications as read
• GET /api/notifications/unread-count - Get unread notification count

Audit Logs

• GET /api/audit-logs - Get audit logs with filters (requires auth)
• POST /api/audit-logs/log - Create audit log entry (internal use)
• GET /api/audit-logs/stats - Get audit statistics (requires auth)

Field History

• GET /api/field-history - Get field change history (table, record_id, field)

Reports

• GET /api/reports/project-stats - Get project statistics
• GET /api/reports/task-stats - Get task statistics
• GET /api/reports/user-activity - Get user activity stats

Admin (Admin Auth Required)

• GET /api/admin/users - Get all users
• POST /api/admin/users - Create new user
• GET /api/admin/users/[id] - Get user by ID
• PUT /api/admin/users/[id] - Update user
• DELETE /api/admin/users/[id] - Delete user
• GET /api/admin/settings - Get all settings
• PUT /api/admin/settings - Update setting
• GET /api/admin/cron - Get cron job status
• POST /api/admin/cron - Trigger cron action (backup, reminder)

Authentication

• GET /api/auth/[...nextauth] - NextAuth handlers
• POST /api/auth/[...nextauth] - NextAuth handlers
• POST /api/auth/change-password - Change user password

Dashboard

• GET /api/dashboard/stats - Get dashboard statistics
• GET /api/dashboard/team-tasks - Get team tasks (team lead)

Auth Middleware Levels:

• Public - No authentication required
• Read Auth (withReadAuth) - Any authenticated user
• User Auth (withUserAuth) - User role and above (excludes read-only)
• Admin Auth (withAdminAuth) - Admin and project_manager only

🗺️ Advanced Map Features

This project includes a comprehensive GIS system for visualizing project locations with support for Polish coordinate systems and multiple data layers.

Coordinate Systems

• EPSG:2180 - Polish 1992 coordinate system (native)
• EPSG:3857 - Web Mercator (Google Maps compatible)
• Dynamic Transformation - Proj4 handles conversions between systems

Base Layers (8 options)

1. OpenStreetMap - Default open-source street map
2. 🇵🇱 Polish Orthophoto (Standard) - WMTS aerial imagery (standard resolution)
3. 🇵🇱 Polish Orthophoto (High-Res) - WMTS aerial imagery (high resolution)
4. 🌍 Google Satellite - Global satellite imagery
5. 🌍 Google Hybrid - Satellite imagery with road/label overlays
6. 🌍 Google Roads - Google Maps road view
7. Satellite (Esri) - Alternative satellite imagery provider
8. Topographic - CartoDB topographic maps

Overlay Layers (6 transparent layers)

1. 📋 Polish Cadastral Data (WMS) - Property boundaries, 80% opacity
2. 🏗️ Polish Spatial Planning (WMS) - Zoning and planning data, 70% opacity
3. 🛣️ LP-Portal Roads (WMS) - Polish road network, 90% opacity
4. 🏷️ LP-Portal Street Names (WMS) - Street labels, 100% opacity
5. 📐 LP-Portal Parcels (WMS) - Property parcels, 60% opacity
6. 📍 LP-Portal Survey Markers (WMS) - Geodetic survey points, 80% opacity

Features

• Layer Switcher - Interactive control (📚 icon) to switch base layers and toggle overlays
• Project Markers - Plot all projects on map with clickable markers
• Popup Information - Click markers to see project details
• Dynamic Loading - WMTS/WMS layers configured via OGC GetCapabilities
• Route Planning - Optimize routes between project locations
• Search Integration - Find projects by location
• Responsive - Mobile-optimized map interface

Configuration

Map layers are easily configurable. See docs/MAP_LAYERS.md for:

• Adding new base layers
• Configuring WMS/WMTS sources
• Custom overlay creation
• Styling and opacity settings

Data Sources

• Geoportal.gov.pl - Official Polish government geospatial data
• LP-Portal - Polish cadastral and planning information
• Google Maps - Global satellite and road data
• OpenStreetMap - Community-driven open data
• Esri - Commercial satellite imagery
• CartoDB - Topographic map tiles

🔄 Automated Tasks & Cron Jobs

The system includes automated background tasks managed via Linux cron:

Daily Database Backup

Script: backup-db.mjs
Schedule: Daily (configurable via cron)
Features:

• Creates timestamped SQLite backup
• Stores in backups/ directory
• Retains last 30 backups (auto-cleanup)
• Sends notification to configured admin user
• Logs backup completion

Due Date Reminders

Script: send-due-date-reminders.mjs
Schedule: Daily (typically runs at night)
Features:

• Checks projects finishing in 3 days
• Checks projects finishing in 1 day
• Creates notifications for assigned users
• Skips fulfilled/cancelled projects
• Logs reminder activity

Cron Management

Setup: Run setup-cron.sh in Docker container
Admin Interface: /admin/cron - View status, trigger manual runs
Cron Status API: /api/admin/cron - Get cron job status

Manual Triggers

# Manual backup
docker-compose exec app node backup-db.mjs

# Manual reminders
docker-compose exec app node send-due-date-reminders.mjs

# Test reminders (dry run)
docker-compose exec app npm run test-due-date-reminders

🌐 CardDAV Integration (Radicale)

Synchronize contacts with external CardDAV servers (e.g., Radicale):

Features

• Bi-directional Sync - Push contacts to CardDAV server
• VCard Format - Standard vCard 3.0 format
• Automatic Sync - Option to sync on contact create/update
• Manual Export - One-time export script available
• Conflict Resolution - Handles existing contacts gracefully

Configuration

Configure in src/lib/radicale-sync.js:

• Radicale server URL
• Authentication credentials
• Collection name

Usage

# One-time export all contacts
node export-contacts-to-radicale.mjs

# Automatic sync (via API)
POST /api/contacts/[id]/sync

🎨 UI/UX Features

Theme System

• Dark Mode - Full dark theme support
• Light Mode - Clean light theme
• System Preference - Automatic detection
• Persistent - Theme choice saved per user
• Smooth Transitions - Animated theme switching

Responsive Design

• Mobile-First - Optimized for mobile devices
• Tablet Support - Adaptive layouts for tablets
• Desktop Optimized - Full-featured desktop experience
• Touch-Friendly - Large touch targets on mobile

Component Library

40+ reusable React components:

• Forms - Inputs, selects, textareas with validation
• Cards - Content containers with headers
• Buttons - Multiple variants and sizes
• Badges - Status indicators with color coding
• Modals - Dialog boxes for forms and confirmations
• Tables - Sortable, filterable data tables
• Loading States - Skeletons and spinners
• Error States - User-friendly error messages
• Navigation - Responsive navbar with dropdowns
• Search - Real-time search with highlighting

User Experience

• Auto-Save Indicators - Visual feedback on saves
• Validation Feedback - Inline form validation
• Confirmation Dialogs - Prevent accidental deletions
• Keyboard Shortcuts - Power user features
• Breadcrumbs - Easy navigation
• Progress Indicators - Upload/processing progress
• Tooltips - Helpful hints and information
• Toast Notifications - Non-intrusive feedback

🧪 Testing

Unit & Integration Tests (Jest)

npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

Test Suites:

• API endpoint tests (__tests__/api/)
• Component tests (__tests__/components/)
• Query function tests (__tests__/queries/)
• Utility function tests (__tests__/utils/)

End-to-End Tests (Playwright)

npm run test:e2e         # Run E2E tests
npm run test:e2e:ui      # Interactive UI mode

Test Scenarios:

• User authentication flows
• Project creation workflow
• Task management
• File uploads
• Form validations
• Navigation

Test Coverage

• API Routes: Comprehensive endpoint testing
• Database Queries: All CRUD operations
• Authentication: Login, logout, session management
• Authorization: Role-based access control
• Components: Critical UI components
• Business Logic: Core functionality

🚀 Deployment

Production Checklist

1. Environment Variables

   • Set strong NEXTAUTH_SECRET (min 32 chars)
   • Configure NEXTAUTH_URL to production domain
   • Set NODE_ENV=production

2. Database

   • Ensure data/ directory is persistent (volume mount)
   • Set up backup schedule (cron)
   • Test database initialization

3. File Storage

   • Mount persistent volumes for uploads/, templates/, backups/
   • Set appropriate permissions
   • Configure backup strategy

4. Reverse Proxy (recommended: Nginx)

   • SSL/TLS certificates (Let's Encrypt)
   • Gzip compression
   • Static file caching
   • Rate limiting
   • Request size limits

5. Security

   • Change default admin password
   • Enable firewall rules
   • Configure CORS if needed
   • Set up monitoring

6. Cron Jobs

   • Run setup-cron.sh in container
   • Verify backup schedule
   • Test reminder notifications

7. Monitoring

   • Set up log aggregation
   • Configure error tracking
   • Monitor disk space (backups)
   • Database performance monitoring

Nginx Example Configuration

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    client_max_body_size 10M;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Backup Strategy

1. Database: Daily automated backups via cron (last 30 retained)
2. Files: Regular volume backups of uploads/ and templates/
3. Configuration: Version control for config files
4. Off-site: Copy backups to external storage weekly

Scaling Considerations

• Vertical Scaling: Increase RAM/CPU for Docker container
• Database: SQLite suitable for 100s of concurrent users
• File Storage: Mount NFS/S3 for distributed storage
• Caching: Add Redis for session storage (future)
• CDN: Serve static assets via CDN (future)

📚 Documentation

Additional documentation available in the /docs directory:

• docs/MAP_LAYERS.md - Map layer configuration guide
• DEPLOYMENT_GUIDE_TEMPLATE.md - Detailed deployment instructions
• DOCKER_GIT_DEPLOYMENT.md - Git-based deployment guide
• CONTACTS_SYSTEM_README.md - Contact management details
• RADICALE_SYNC_README.md - CardDAV sync documentation
• DOCX_TEMPLATES_README.md - Document template system
• route_planning_readme.md - Route optimization features
• ROADMAP.md - Future feature roadmap

🔧 Troubleshooting

Common Issues

Database locked error

• Ensure only one process accesses database
• Check for hung connections
• Restart application

File upload fails

• Verify uploads/ directory exists and is writable
• Check disk space
• Confirm file size under 10MB

Map layers not loading

• Check network connectivity to external services
• Verify CORS configuration
• Check browser console for errors

Cron jobs not running

• Verify cron service is running in container
• Check setup-cron.sh was executed
• Review cron logs: docker-compose exec app crontab -l

Authentication issues

• Clear browser cookies
• Verify NEXTAUTH_SECRET is set
• Check session expiration
• Review audit logs for failed attempts

Debug Mode

# View detailed logs
docker-compose logs -f app

# Access container shell
docker-compose exec app bash

# Check database
docker-compose exec app sqlite3 data/database.sqlite

# Test API endpoints
curl -X GET http://localhost:3001/api/projects

🤝 Contributing

Development Workflow

1. Fork & Clone

git clone <your-fork-url>
cd panel
git remote add upstream <original-repo-url>

2. Create Feature Branch

git checkout -b feature/amazing-feature

3. Make Changes

• Write code following existing patterns
• Add tests for new features
• Update documentation
• Follow ESLint rules

4. Test

npm run lint
npm test
npm run test:e2e

5. Commit

git add .
git commit -m "feat: add amazing feature"

Use conventional commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• style: - Formatting
• refactor: - Code restructure
• test: - Tests
• chore: - Maintenance

6. Push & PR

git push origin feature/amazing-feature

Create Pull Request on GitHub

Code Standards

• ESLint: Follow Next.js recommended config
• Components: Functional components with hooks
• Naming: Descriptive names, camelCase for variables
• Files: PascalCase for components, kebab-case for utils
• Comments: JSDoc for functions, inline for complex logic
• Formatting: Consistent indentation (tabs)

Database Migrations

Add migrations in src/lib/init-db.js:

try {
  db.exec(`ALTER TABLE table_name ADD COLUMN new_column TEXT;`);
} catch (e) {
  // Column already exists
}

<EFBFBD> Documentation

Core Documentation

• Main README - This file - complete project overview
• Development Roadmap - Feature priorities, timelines, and future plans
• Documentation Index - Complete documentation directory

Feature Guides

• Contacts System - Contact management and CardDAV integration
• DOCX Templates - Document generation system with troubleshooting
• Radicale CardDAV Sync - Automatic contact synchronization
• Route Planning - Multi-point route optimization
• Map Layers Configuration - WMTS/WMS layer setup guide

Deployment Guides

• Advanced Deployment - Detailed deployment strategies
• Git-Based Deployment - CI/CD and repository deployment

---

<EFBFBD>📄 License

This project is private and proprietary. All rights reserved.

Unauthorized copying, modification, distribution, or use of this software is strictly prohibited.

---

📞 Support

For issues, questions, or feature requests, please contact the development team or create an issue in the repository.

---

Built with ❤️ for Wastpol | Version 0.1.1 | January 2026