Iniital Commit

.dockerignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# Development files
+.pre-commit-config.yaml
+pytest.ini
+requirements-dev.txt
+docker-compose.yml
+
+# Tests
+tests/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Environment
+.env
+.env.local
+
+# Scripts
+scripts/
+
+# Build artifacts
+*.egg-info/
+dist/
+build/

.env.example

@@ -23,127 +23,3 @@ ALGORITHM=HS256
 ACCESS_TOKEN_EXPIRE_MINUTES=30
 REFRESH_TOKEN_EXPIRE_DAYS=7
 
-# ============================================
-# REDIS (CACHING & CELERY)
-# ============================================
-REDIS_URL=redis://localhost:6379/0
-CACHE_TTL_SECONDS=300
-
-# ============================================
-# CELERY (BACKGROUND TASKS)
-# ============================================
-CELERY_BROKER_URL=redis://localhost:6379/0
-CELERY_RESULT_BACKEND=redis://localhost:6379/0
-CELERY_TASK_ALWAYS_EAGER=False
-
-# ============================================
-# PAYMENT GATEWAYS
-# ============================================
-# M-Pesa (Safaricom)
-MPESA_ENVIRONMENT=sandbox  # or 'production'
-MPESA_CONSUMER_KEY=your-mpesa-consumer-key
-MPESA_CONSUMER_SECRET=your-mpesa-consumer-secret
-MPESA_SHORTCODE=174379
-MPESA_PASSKEY=your-mpesa-passkey
-MPESA_CALLBACK_URL=https://your-domain.com/api/v1/webhooks/mpesa
-
-# Bank API (if applicable)
-BANK_API_URL=https://api.bank.com
-BANK_API_KEY=your-bank-api-key
-
-# ============================================
-# GOOGLE MAPS API
-# ============================================
-GOOGLE_MAPS_API_KEY=your-google-maps-api-key
-GOOGLE_MAPS_DISTANCE_MATRIX_ENABLED=True
-
-# ============================================
-# SMS PROVIDER (AFRICA'S TALKING)
-# ============================================
-AFRICASTALKING_USERNAME=your-username
-AFRICASTALKING_API_KEY=your-api-key
-AFRICASTALKING_SENDER_ID=SwiftOps
-
-# ============================================
-# EMAIL PROVIDER (SENDGRID)
-# ============================================
-SENDGRID_API_KEY=your-sendgrid-api-key
-FROM_EMAIL=noreply@swiftops.com
-FROM_NAME=SwiftOps Platform
-
-# ============================================
-# FILE STORAGE
-# ============================================
-STORAGE_PROVIDER=supabase  # Options: 'supabase', 's3', 'local'
-
-# Supabase Storage
-SUPABASE_STORAGE_BUCKET=documents
-
-# AWS S3 (if using S3)
-AWS_ACCESS_KEY_ID=your-aws-access-key
-AWS_SECRET_ACCESS_KEY=your-aws-secret-key
-AWS_S3_BUCKET=swiftops-documents
-AWS_REGION=us-east-1
-
-# Local Storage (for development)
-LOCAL_STORAGE_PATH=./uploads
-
-# ============================================
-# CORS CONFIGURATION
-# ============================================
-CORS_ORIGINS=http://localhost:3000,http://localhost:5173,https://your-frontend-domain.com
-CORS_ALLOW_CREDENTIALS=True
-
-# ============================================
-# RATE LIMITING
-# ============================================
-RATE_LIMIT_ENABLED=True
-RATE_LIMIT_PER_MINUTE=60
-RATE_LIMIT_PER_HOUR=1000
-
-# ============================================
-# MONITORING & LOGGING
-# ============================================
-SENTRY_DSN=your-sentry-dsn-here
-SENTRY_ENVIRONMENT=development
-
-# ============================================
-# FEATURE FLAGS
-# ============================================
-ENABLE_OFFLINE_MODE=True
-ENABLE_AUTO_ASSIGNMENT=False
-ENABLE_LOCATION_TRACKING=True
-ENABLE_PAYMENT_GATEWAY=True
-ENABLE_SMS_NOTIFICATIONS=True
-ENABLE_EMAIL_NOTIFICATIONS=True
-
-# ============================================
-# BUSINESS RULES CONFIGURATION
-# ============================================
-# Ticket Assignment
-MAX_SELF_ASSIGNED_TICKETS=3
-AUTO_ASSIGNMENT_RADIUS_KM=50
-
-# SLA Configuration (hours)
-SLA_URGENT_HOURS=24
-SLA_HIGH_HOURS=48
-SLA_NORMAL_HOURS=72
-SLA_LOW_DAYS=7
-
-# Location Verification
-ARRIVAL_VERIFICATION_RADIUS_METERS=100
-MAX_TRAVEL_SPEED_KMH=120
-
-# File Upload Limits
-MAX_FILE_UPLOAD_MB=50
-MAX_FILES_PER_TICKET=20
-ALLOWED_FILE_TYPES=pdf,jpg,jpeg,png,doc,docx,xls,xlsx
-
-# Payroll
-PAYROLL_GENERATION_DAY=Friday
-PAYROLL_GENERATION_HOUR=18
-
-# ============================================
-# TESTING
-# ============================================
-TEST_DATABASE_URL=postgresql://postgres:password@localhost:5432/swiftops_test

.gitignore

@@ -48,6 +48,7 @@ venv.bak/
 # ============================================
 # VSCode
 .vscode/
+.kiro/
 *.code-workspace
 
 # PyCharm
@@ -173,3 +174,16 @@ credentials/
 # ============================================
 poetry.lock
 Pipfile.lock
+
+# ============================================
+# Development Files (Not for HF Spaces)
+# ============================================
+# Keep these locally but don't deploy to Hugging Face
+docker-compose.yml
+.pre-commit-config.yaml
+pytest.ini
+
+# Optional: Uncomment to exclude from deployment
+# requirements-dev.txt
+# scripts/
+# tests/

.space

@@ -0,0 +1,3 @@
+# Hugging Face Spaces Configuration
+sdk: docker
+app_port: 7860

Dockerfile

@@ -1,27 +1,13 @@
-# Multi-stage build for production optimization
-FROM python:3.11-slim as base
+FROM python:3.11-slim
 
-# Set environment variables
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    PIP_NO_CACHE_DIR=1 \
-    PIP_DISABLE_PIP_VERSION_CHECK=1
-
-# Set work directory
 WORKDIR /app
 
 # Install system dependencies
 RUN apt-get update && apt-get install -y \
     gcc \
     postgresql-client \
-    curl \
     && rm -rf /var/lib/apt/lists/*
 
-# ============================================
-# Development Stage
-# ============================================
-FROM base as development
-
 # Copy requirements
 COPY requirements.txt .
 
@@ -29,47 +15,12 @@ COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy application code
-COPY . .
-
-# Expose port
-EXPOSE 8000
-
-# Default command (can be overridden in docker-compose)
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
-
-# ============================================
-# Production Stage
-# ============================================
-FROM base as production
-
-# Copy requirements
-COPY requirements.txt .
-
-# Install Python dependencies (production only)
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Create non-root user
-RUN useradd -m -u 1000 appuser && \
-    chown -R appuser:appuser /app
-
-# Copy application code
-COPY --chown=appuser:appuser . .
-
-# Switch to non-root user
-USER appuser
-
-# Expose port
-EXPOSE 8000
+COPY src/ ./src/
+COPY alembic/ ./alembic/
+COPY alembic.ini .
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:8000/health || exit 1
+# Expose port (Hugging Face Spaces uses port 7860 by default)
+EXPOSE 7860
 
-# Production command (use gunicorn with uvicorn workers)
-CMD ["gunicorn", "app.main:app", \
-     "--workers", "4", \
-     "--worker-class", "uvicorn.workers.UvicornWorker", \
-     "--bind", "0.0.0.0:8000", \
-     "--access-logfile", "-", \
-     "--error-logfile", "-", \
-     "--log-level", "info"]
+# Run database migrations and start application
+CMD alembic upgrade head && uvicorn src.app.main:app --host 0.0.0.0 --port 7860

README.md

@@ -1,479 +1,31 @@
-# SwiftOps Backend API
-
-**Field Service Management Platform - FastAPI Backend**
-
-A scalable, production-ready FastAPI backend for managing field service operations including ticket management, payroll processing, inventory tracking, and financial workflows.
-
----
-
-## 🏗️ Architecture Overview
-
-```
-backend/
-├── app/
-│   ├── __init__.py
-│   ├── main.py                      # FastAPI application entry point
-│   ├── config.py                    # Configuration management (env vars, settings)
-│   │
-│   ├── api/                         # API Layer - HTTP endpoints
-│   │   ├── __init__.py
-│   │   ├── deps.py                  # Shared dependencies (auth, db session)
-│   │   ├── v1/                      # API version 1
-│   │   │   ├── __init__.py
-│   │   │   ├── router.py            # Main router aggregator
-│   │   │   ├── auth.py              # Authentication endpoints
-│   │   │   ├── users.py             # User management
-│   │   │   ├── projects.py          # Project CRUD
-│   │   │   ├── tickets.py           # Ticket operations
-│   │   │   ├── assignments.py       # Ticket assignment logic
-│   │   │   ├── payroll.py           # Payroll generation & management
-│   │   │   ├── inventory.py         # Inventory tracking
-│   │   │   ├── finance.py           # Financial transactions
-│   │   │   ├── customers.py         # Customer management
-│   │   │   ├── subscriptions.py     # Subscription lifecycle
-│   │   │   ├── incidents.py         # Support incidents
-│   │   │   ├── sales_orders.py      # Sales order processing
-│   │   │   ├── analytics.py         # Dashboard & reporting
-│   │   │   └── webhooks.py          # Payment gateway webhooks
-│   │   │
-│   │   └── websockets/              # WebSocket endpoints
-│   │       ├── __init__.py
-│   │       ├── location.py          # Real-time location tracking
-│   │       └── notifications.py     # Real-time notifications
-│   │
-│   ├── core/                        # Core Business Logic
-│   │   ├── __init__.py
-│   │   ├── auth.py                  # JWT handling, password hashing
-│   │   ├── security.py              # RLS, permissions, RBAC
-│   │   ├── exceptions.py            # Custom exception classes
-│   │   └── middleware.py            # Custom middleware (logging, CORS)
-│   │
-│   ├── services/                    # Business Logic Layer
-│   │   ├── __init__.py
-│   │   ├── ticket_service.py        # Ticket lifecycle, assignment logic
-│   │   ├── payroll_service.py       # Payroll calculation, generation
-│   │   ├── inventory_service.py     # Inventory allocation, tracking
-│   │   ├── finance_service.py       # Transaction workflows, approvals
-│   │   ├── sla_service.py           # SLA calculation, monitoring
-│   │   ├── location_service.py      # GPS validation, distance calculation
-│   │   ├── notification_service.py  # Email, SMS, push notifications
-│   │   ├── payment_service.py       # Payment gateway integration
-│   │   ├── subscription_service.py  # Subscription activation, lifecycle
-│   │   └── analytics_service.py     # Metrics, dashboard data
-│   │
-│   ├── models/                      # SQLAlchemy ORM Models
-│   │   ├── __init__.py
-│   │   ├── base.py                  # Base model with common fields
-│   │   ├── user.py                  # User, UserFinancialAccounts
-│   │   ├── organization.py          # Clients, Contractors
-│   │   ├── project.py               # Projects, ProjectTeam, ProjectRoles
-│   │   ├── ticket.py                # Tickets, TicketAssignments, TicketStatusHistory
-│   │   ├── customer.py              # Customers, SalesOrders, Subscriptions
-│   │   ├── incident.py              # Incidents
-│   │   ├── inventory.py             # ProjectInventory, InventoryAssignments
-│   │   ├── finance.py               # ProjectFinance, UserPayroll, PaymentLogs
-│   │   ├── timesheet.py             # Timesheets
-│   │   └── document.py              # Documents
-│   │
-│   ├── schemas/                     # Pydantic Schemas (Request/Response)
-│   │   ├── __init__.py
-│   │   ├── user.py                  # UserCreate, UserUpdate, UserResponse
-│   │   ├── project.py               # ProjectCreate, ProjectUpdate, ProjectResponse
-│   │   ├── ticket.py                # TicketCreate, TicketUpdate, TicketResponse
-│   │   ├── payroll.py               # PayrollCreate, PayrollCalculation
-│   │   ├── inventory.py             # InventoryAssignment, InventoryDistribution
-│   │   ├── finance.py               # TransactionCreate, TransactionApproval
-│   │   └── common.py                # Shared schemas (Pagination, Filters)
-│   │
-│   ├── repositories/                # Data Access Layer (Repository Pattern)
-│   │   ├── __init__.py
-│   │   ├── base.py                  # Base repository with CRUD operations
-│   │   ├── user_repository.py       # User-specific queries
-│   │   ├── ticket_repository.py     # Ticket-specific queries
-│   │   ├── payroll_repository.py    # Payroll-specific queries
-│   │   └── finance_repository.py    # Finance-specific queries
-│   │
-│   ├── tasks/                       # Background Tasks (Celery)
-│   │   ├── __init__.py
-│   │   ├── celery_app.py            # Celery configuration
-│   │   ├── payroll_tasks.py         # Weekly payroll generation
-│   │   ├── sla_tasks.py             # SLA monitoring, alerts
-│   │   ├── notification_tasks.py    # Send emails, SMS
-│   │   ├── invoice_tasks.py         # Generate contractor invoices
-│   │   └── analytics_tasks.py       # Pre-compute dashboard metrics
-│   │
-│   ├── integrations/                # External Service Integrations
-│   │   ├── __init__.py
-│   │   ├── supabase.py              # Supabase client (Auth, Storage, Realtime)
-│   │   ├── mpesa.py                 # M-Pesa payment gateway
-│   │   ├── google_maps.py           # Google Maps API (geocoding, distance)
-│   │   ├── sms_provider.py          # SMS gateway (Africa's Talking, Twilio)
-│   │   ├── email_provider.py        # Email service (SendGrid, AWS SES)
-│   │   └── storage.py               # File storage (Supabase Storage, S3)
-│   │
-│   ├── utils/                       # Utility Functions
-│   │   ├── __init__.py
-│   │   ├── date_utils.py            # Date/time helpers
-│   │   ├── location_utils.py        # GPS calculations, distance
-│   │   ├── validation.py            # Custom validators
-│   │   ├── formatters.py            # Data formatting helpers
-│   │   └── constants.py             # Application constants
-│   │
-│   └── db/                          # Database Configuration
-│       ├── __init__.py
-│       ├── session.py               # Database session management
-│       ├── base.py                  # Base class for all models
-│       └── migrations/              # Alembic migrations
-│           └── versions/
-│
-├── tests/                           # Test Suite
-│   ├── __init__.py
-│   ├── conftest.py                  # Pytest fixtures
-│   ├── unit/                        # Unit tests
-│   │   ├── test_services/
-│   │   ├── test_repositories/
-│   │   └── test_utils/
-│   ├── integration/                 # Integration tests
-│   │   ├── test_api/
-│   │   └── test_tasks/
-│   └── e2e/                         # End-to-end tests
-│
-├── scripts/                         # Utility Scripts
-│   ├── seed_data.py                 # Seed database with test data
-│   ├── generate_payroll.py          # Manual payroll generation
-│   └── migrate_data.py              # Data migration scripts
-│
-├── .env.example                     # Environment variables template
-├── .gitignore
-├── requirements.txt                 # Python dependencies
-├── pyproject.toml                   # Poetry configuration (alternative)
-├── Dockerfile                       # Docker container definition
-├── docker-compose.yml               # Local development setup
-└── README.md                        # This file
-```
-
----
-
-## 🎯 Core Functions & Responsibilities
-
-### **1. Authentication & Authorization**
-**Module**: `app/api/v1/auth.py`, `app/core/auth.py`, `app/core/security.py`
-
-**Functions**:
-- User login/logout (JWT token generation)
-- Password reset flow
-- Role-based access control (RBAC)
-- Row-level security (RLS) enforcement
-- Multi-tenancy isolation (client/contractor scoping)
-
-**Supabase Integration**:
-- Uses Supabase Auth for user authentication
-- Validates JWT tokens from Supabase
-- Syncs user roles with custom `Users` table
-
----
-
-### **2. Ticket Management**
-**Module**: `app/services/ticket_service.py`, `app/api/v1/tickets.py`
-
-**Functions**:
-- Create tickets from sales orders, incidents, or tasks
-- Ticket assignment logic (manual, auto-assignment)
-- Limit self-assignment to 3 tickets per agent
-- Status transitions with validation
-- SLA deadline calculation and monitoring
-- GPS-based arrival verification
-- Ticket completion workflow
-
-**Business Rules**:
-```python
-# Example: Ticket Assignment Logic
-def assign_ticket(ticket_id, user_id):
-    # 1. Check user has < 3 active assignments
-    # 2. Verify user is in project team
-    # 3. Check user's region matches ticket region
-    # 4. Create TicketAssignment record
-    # 5. Update ticket status to 'assigned'
-    # 6. Send notification to agent
-    # 7. Update SLA target date
-```
-
----
-
-### **3. Payroll Processing**
-**Module**: `app/services/payroll_service.py`, `app/api/v1/payroll.py`
-
-**Functions**:
-- Weekly payroll generation (automated via Celery)
-- Calculate earnings based on compensation type:
-  - Flat rate (fixed weekly amount)
-  - Commission (% of package price)
-  - Hybrid (base + commission)
-  - Hourly (based on timesheet hours)
-- Apply deductions (advances, penalties)
-- Generate payroll reports
-- Mark payroll as paid with payment reference
-
-**Business Rules**:
-```python
-# Example: Payroll Calculation
-def calculate_payroll(user_id, project_id, period_start, period_end):
-    role = get_user_project_role(user_id, project_id)
-    tickets_closed = count_tickets_closed(user_id, period_start, period_end)
-    hours_worked = sum_timesheet_hours(user_id, period_start, period_end)
-    
-    if role.compensation_type == 'flat_rate':
-        earnings = role.flat_rate_amount
-    elif role.compensation_type == 'commission':
-        earnings = sum_ticket_values(tickets) * role.commission_percentage
-    elif role.compensation_type == 'hybrid':
-        earnings = role.base_amount + (sum_ticket_values(tickets) * role.commission_percentage)
-    elif role.compensation_type == 'hourly':
-        earnings = hours_worked * role.hourly_rate
-    
-    deductions = get_user_deductions(user_id, period_start, period_end)
-    total = earnings - deductions
-    
-    return create_payroll_record(...)
-```
-
----
-
-### **4. Inventory Management**
-**Module**: `app/services/inventory_service.py`, `app/api/v1/inventory.py`
-
-**Functions**:
-- Allocate inventory to regional hubs
-- Issue equipment to field agents
-- Track serial numbers and unit identifiers
-- Prevent duplicate assignments (same serial issued twice)
-- Handle returns (tools) and installations (equipment)
-- Optimistic locking for concurrent updates
-- Inventory reconciliation reports
-
-**Business Rules**:
-```python
-# Example: Inventory Assignment
-def assign_inventory_to_agent(distribution_id, user_id, unit_identifier):
-    # 1. Check unit_identifier not already assigned
-    # 2. Verify quantity_available > 0
-    # 3. Check user is in same region as distribution
-    # 4. Create InventoryAssignment record
-    # 5. Update distribution.quantity_issued
-    # 6. Use optimistic locking (version field)
-```
+# SwiftOps Backend
 
 ---
-
-### **5. Financial Management**
-**Module**: `app/services/finance_service.py`, `app/api/v1/finance.py`
-
-**Functions**:
-- Record project expenses (inflows/outflows)
-- Approval workflow (pending → approved → paid)
-- Link to entities (tickets, payroll, invoices)
-- Payment gateway integration (M-Pesa, bank transfers)
-- Transaction reconciliation
-- Financial reporting and audit trails
-
-**Business Rules**:
-```python
-# Example: Expense Approval Workflow
-def approve_expense(expense_id, approver_id):
-    # 1. Check approver has 'dispatcher' or 'project_manager' role
-    # 2. Verify expense is in 'pending' status
-    # 3. Validate location_verified = TRUE (if required)
-    # 4. Update status to 'approved'
-    # 5. Create ProjectFinance record
-    # 6. Send notification to incurred_by_user
-```
-
----
-
-### **6. Location Tracking**
-**Module**: `app/services/location_service.py`, `app/api/websockets/location.py`
-
-**Functions**:
-- Real-time GPS tracking via WebSocket
-- Validate agent arrival at customer site
-- Calculate distance between agent and customer
-- Journey tracking (breadcrumb trail)
-- Fraud detection (impossible travel speeds)
-- Update user current location
-
-**Business Rules**:
-```python
-# Example: Arrival Verification
-def verify_arrival(ticket_id, agent_location):
-    ticket = get_ticket(ticket_id)
-    customer_location = get_customer_location(ticket.customer_id)
-    
-    distance = calculate_distance(agent_location, customer_location)
-    
-    if distance <= 100:  # Within 100 meters
-        mark_arrived(ticket_id, agent_location, verified=True)
-    else:
-        mark_arrived(ticket_id, agent_location, verified=False)
-```
-
----
-
-### **7. SLA Monitoring**
-**Module**: `app/services/sla_service.py`, `app/tasks/sla_tasks.py`
-
-**Functions**:
-- Calculate SLA deadlines based on priority
-- Monitor tickets approaching deadline
-- Send alerts to managers and agents
-- Mark tickets as SLA violated
-- Generate SLA compliance reports
-
-**Background Task** (runs every hour):
-```python
-@celery_app.task
-def monitor_sla_violations():
-    # 1. Find tickets with sla_target_date < now() and status != 'completed'
-    # 2. Mark sla_violated = TRUE
-    # 3. Send notifications to project managers
-    # 4. Log SLA violation event
-```
-
----
-
-### **8. Payment Gateway Integration**
-**Module**: `app/services/payment_service.py`, `app/integrations/mpesa.py`
-
-**Functions**:
-- Initiate M-Pesa payments (B2C, B2B)
-- Handle payment callbacks/webhooks
-- Retry failed payments
-- Log all payment attempts (PaymentLogs)
-- Reconcile payments with transactions
-
-**Webhook Handler**:
-```python
-@router.post("/webhooks/mpesa")
-async def mpesa_callback(payload: dict):
-    # 1. Validate webhook signature
-    # 2. Parse payment result
-    # 3. Update ProjectFinance status
-    # 4. Create PaymentLog entry
-    # 5. Send notification to user
-```
-
+title: SwiftOps API
+emoji: 🚀
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
 ---
 
-### **9. Subscription Management**
-**Module**: `app/services/subscription_service.py`, `app/api/v1/subscriptions.py`
-
-**Functions**:
-- Activate subscriptions after installation
-- Validate activation requirements (dynamic per project)
-- Manage subscription lifecycle (active, suspended, cancelled)
-- Link subscriptions to tickets and sales orders
-
-**Business Rules**:
-```python
-# Example: Subscription Activation
-def activate_subscription(subscription_id, activation_data):
-    subscription = get_subscription(subscription_id)
-    project = get_project(subscription.project_id)
-    
-    # Validate dynamic activation requirements
-    for requirement in project.activation_requirements:
-        if requirement['required'] and requirement['field'] not in activation_data:
-            raise ValidationError(f"Missing required field: {requirement['label']}")
-    
-    # Update subscription
-    subscription.status = 'active'
-    subscription.activation_date = date.today()
-    subscription.activation_details = activation_data
-    subscription.activated_by_user_id = current_user.id
-```
-
----
-
-### **10. Analytics & Reporting**
-**Module**: `app/services/analytics_service.py`, `app/api/v1/analytics.py`
-
-**Functions**:
-- Dashboard metrics (tickets, revenue, SLA compliance)
-- Agent performance reports
-- Project financial summaries
-- Inventory utilization reports
-- Pre-computed aggregations (via Celery)
-
-**Background Task** (runs daily):
-```python
-@celery_app.task
-def compute_daily_metrics():
-    # 1. Calculate tickets closed per agent
-    # 2. Compute average completion time
-    # 3. Calculate SLA compliance rate
-    # 4. Store in cache (Redis)
-```
-
----
-
-## 🔗 Supabase Integration Points
-
-### **1. Authentication**
-```python
-# app/integrations/supabase.py
-from supabase import create_client
-
-supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
-
-# Verify JWT token from frontend
-def verify_token(token: str):
-    user = supabase.auth.get_user(token)
-    return user
-```
-
-### **2. Storage (File Uploads)**
-```python
-# Upload ticket photos, receipts
-def upload_document(file, bucket="documents"):
-    path = f"{user_id}/{ticket_id}/{filename}"
-    supabase.storage.from_(bucket).upload(path, file)
-    return supabase.storage.from_(bucket).get_public_url(path)
-```
+Field Service Management Platform for African Telecom
 
-### **3. Realtime (WebSocket)**
-```python
-# Subscribe to ticket updates
-supabase.realtime.channel('tickets')
-    .on('postgres_changes', 
-        event='UPDATE', 
-        schema='public', 
-        table='Tickets',
-        callback=handle_ticket_update)
-    .subscribe()
-```
+## 🚀 Quick Start
 
-### **4. Database (Direct Queries)**
-```python
-# Use Supabase client for simple queries (optional)
-# For complex queries, use SQLAlchemy ORM
-tickets = supabase.table('Tickets').select('*').eq('status', 'open').execute()
-```
-
----
-
-## 🚀 Getting Started
-
-### **Prerequisites**
+### Prerequisites
 - Python 3.11+
-- PostgreSQL 15+ (Supabase)
-- Redis (for caching and Celery)
+- PostgreSQL 15+
+- Redis 7+
 - Docker & Docker Compose (optional)
 
-### **Installation**
+### Installation
 
 1. **Clone the repository**
 ```bash
-git clone <repo-url>
-cd backend
+git clone <repository-url>
+cd swiftops-backend
 ```
 
 2. **Create virtual environment**
@@ -490,7 +42,7 @@ pip install -r requirements.txt
 4. **Set up environment variables**
 ```bash
 cp .env.example .env
-# Edit .env with your Supabase credentials
+# Edit .env with your configuration
 ```
 
 5. **Run database migrations**
@@ -500,90 +52,38 @@ alembic upgrade head
 
 6. **Start the development server**
 ```bash
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
-```
-
-7. **Start Celery worker** (in separate terminal)
-```bash
-celery -A app.tasks.celery_app worker --loglevel=info
+uvicorn src.app.main:app --reload
 ```
 
-8. **Start Celery beat** (scheduler, in separate terminal)
-```bash
-celery -A app.tasks.celery_app beat --loglevel=info
-```
+The API will be available at `http://localhost:8000`
 
----
+API Documentation: `http://localhost:8000/api/docs`
 
-## 🐳 Docker Setup
+### Using Docker
 
 ```bash
-# Start all services (API, Celery, Redis)
 docker-compose up -d
-
-# View logs
-docker-compose logs -f api
-
-# Stop services
-docker-compose down
 ```
 
----
-
-## 📝 Environment Variables
+## 📁 Project Structure
 
-```bash
-# .env.example
-
-# Application
-APP_NAME=SwiftOps API
-APP_VERSION=1.0.0
-DEBUG=True
-ENVIRONMENT=development
-
-# Database (Supabase PostgreSQL)
-DATABASE_URL=postgresql://user:password@host:5432/dbname
-SUPABASE_URL=https://your-project.supabase.co
-SUPABASE_KEY=your-anon-key
-SUPABASE_SERVICE_KEY=your-service-role-key
-
-# JWT
-SECRET_KEY=your-secret-key-here
-ALGORITHM=HS256
-ACCESS_TOKEN_EXPIRE_MINUTES=30
-
-# Redis
-REDIS_URL=redis://localhost:6379/0
-
-# Celery
-CELERY_BROKER_URL=redis://localhost:6379/0
-CELERY_RESULT_BACKEND=redis://localhost:6379/0
-
-# Payment Gateways
-MPESA_CONSUMER_KEY=your-mpesa-key
-MPESA_CONSUMER_SECRET=your-mpesa-secret
-MPESA_SHORTCODE=174379
-MPESA_PASSKEY=your-passkey
-
-# Google Maps
-GOOGLE_MAPS_API_KEY=your-google-maps-key
-
-# SMS Provider (Africa's Talking)
-AFRICASTALKING_USERNAME=your-username
-AFRICASTALKING_API_KEY=your-api-key
-
-# Email Provider (SendGrid)
-SENDGRID_API_KEY=your-sendgrid-key
-FROM_EMAIL=noreply@swiftops.com
-
-# File Storage
-STORAGE_PROVIDER=supabase  # or 's3'
-AWS_ACCESS_KEY_ID=your-aws-key
-AWS_SECRET_ACCESS_KEY=your-aws-secret
-AWS_S3_BUCKET=your-bucket-name
 ```
-
----
+swiftops-backend/
+├── src/app/              # Application code
+│   ├── api/              # API endpoints
+│   ├── core/             # Core utilities
+│   ├── models/           # Database models
+│   ├── schemas/          # Pydantic schemas
+│   ├── services/         # Business logic
+│   ├── repositories/     # Data access
+│   ├── tasks/            # Background tasks
+│   ├── integrations/     # External services
+│   └── utils/            # Utilities
+├── tests/                # Test suite
+├── alembic/              # Database migrations
+├── docs/                 # Documentation
+└── scripts/              # Utility scripts
+```
 
 ## 🧪 Testing
 
@@ -592,183 +92,71 @@ AWS_S3_BUCKET=your-bucket-name
 pytest
 
 # Run with coverage
-pytest --cov=app --cov-report=html
+pytest --cov=src/app --cov-report=html
 
 # Run specific test file
-pytest tests/unit/test_services/test_payroll_service.py
-
-# Run integration tests only
-pytest tests/integration/
+pytest tests/unit/services/test_ticket_service.py
 ```
 
----
-
-## 📚 API Documentation
+## 📚 Documentation
 
-Once the server is running, visit:
-- **Swagger UI**: http://localhost:8000/docs
-- **ReDoc**: http://localhost:8000/redoc
-- **OpenAPI JSON**: http://localhost:8000/openapi.json
+- [API Documentation](http://localhost:8000/api/docs)
+- [Database Schema](docs/schema/schema.sql)
+- [Build Plan](docs/agent/COMPREHENSIVE_BUILD_PLAN.md)
+- [Backend Features](docs/prod/BACKEND_FEATURES.md)
 
----
-
-## 🏛️ Design Patterns & Best Practices
-
-### **1. Repository Pattern**
-Separates data access logic from business logic.
-
-```python
-# app/repositories/ticket_repository.py
-class TicketRepository:
-    def get_by_id(self, ticket_id: UUID) -> Ticket:
-        return db.query(Ticket).filter(Ticket.id == ticket_id).first()
-    
-    def get_open_tickets(self, project_id: UUID) -> List[Ticket]:
-        return db.query(Ticket).filter(
-            Ticket.project_id == project_id,
-            Ticket.status == 'open',
-            Ticket.deleted_at.is_(None)
-        ).all()
-```
+## 🔧 Development
 
-### **2. Service Layer Pattern**
-Encapsulates business logic.
-
-```python
-# app/services/ticket_service.py
-class TicketService:
-    def __init__(self, ticket_repo: TicketRepository):
-        self.ticket_repo = ticket_repo
-    
-    def assign_ticket(self, ticket_id: UUID, user_id: UUID):
-        # Business logic here
-        ticket = self.ticket_repo.get_by_id(ticket_id)
-        self._validate_assignment(ticket, user_id)
-        assignment = self._create_assignment(ticket, user_id)
-        self._send_notification(user_id, ticket)
-        return assignment
-```
+### Code Quality
 
-### **3. Dependency Injection**
-Use FastAPI's dependency injection system.
-
-```python
-# app/api/deps.py
-def get_db():
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
-
-def get_current_user(token: str = Depends(oauth2_scheme)):
-    # Validate token and return user
-    return user
-
-# Usage in endpoint
-@router.get("/tickets")
-def get_tickets(
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    return ticket_service.get_tickets(db, current_user)
-```
+```bash
+# Format code
+black src/ tests/
 
-### **4. Optimistic Locking**
-Prevent concurrent update conflicts.
-
-```python
-def update_inventory_distribution(distribution_id, updates, version):
-    distribution = db.query(ProjectInventoryDistribution).filter(
-        ProjectInventoryDistribution.id == distribution_id,
-        ProjectInventoryDistribution.version == version
-    ).first()
-    
-    if not distribution:
-        raise ConcurrentUpdateError("Record was modified by another user")
-    
-    # Apply updates
-    distribution.quantity_issued += updates.quantity
-    distribution.version += 1
-    db.commit()
-```
+# Sort imports
+isort src/ tests/
 
-### **5. Soft Deletes**
-Always filter out soft-deleted records.
+# Lint code
+flake8 src/ tests/
 
-```python
-# Base repository method
-def get_active(self, model_class):
-    return db.query(model_class).filter(model_class.deleted_at.is_(None))
+# Type checking
+mypy src/
 ```
 
----
-
-## 🔐 Security Considerations
-
-1. **Row-Level Security (RLS)**
-   - Enforce tenant isolation at database level
-   - Use Supabase RLS policies
-
-2. **API Rate Limiting**
-   - Implement rate limiting per client/user
-   - Use Redis for rate limit tracking
-
-3. **Input Validation**
-   - Use Pydantic schemas for all inputs
-   - Validate file uploads (type, size)
-
-4. **Audit Logging**
-   - Log all financial transactions
-   - Track who created/updated records
+### Database Migrations
 
-5. **Secrets Management**
-   - Never commit secrets to git
-   - Use environment variables or secret managers
-
----
-
-## 📈 Scalability Considerations
-
-1. **Database Connection Pooling**
-   - Use SQLAlchemy connection pool
-   - Configure pool size based on load
-
-2. **Caching Strategy**
-   - Cache frequently accessed data (Redis)
-   - Invalidate cache on updates
+```bash
+# Create new migration
+alembic revision --autogenerate -m "description"
 
-3. **Background Jobs**
-   - Offload heavy tasks to Celery
-   - Use task queues for async processing
+# Apply migrations
+alembic upgrade head
 
-4. **Horizontal Scaling**
-   - Stateless API design
-   - Load balance across multiple instances
+# Rollback migration
+alembic downgrade -1
+```
 
-5. **Database Optimization**
-   - Use indexes effectively
-   - Monitor slow queries
-   - Consider read replicas for reporting
+### Background Tasks
 
----
+```bash
+# Start Celery worker
+celery -A src.app.tasks.celery_app worker --loglevel=info
 
-## 🤝 Contributing
+# Start Celery beat (scheduler)
+celery -A src.app.tasks.celery_app beat --loglevel=info
 
-1. Create a feature branch
-2. Write tests for new features
-3. Follow PEP 8 style guide
-4. Update documentation
-5. Submit pull request
+# Monitor with Flower
+celery -A src.app.tasks.celery_app flower
+```
 
----
+## 🚀 Deployment
 
-## 📄 License
+See [Deployment Guide](docs/prod/DEPLOYMENT.md) for production deployment instructions.
 
-[Your License Here]
+## 📝 License
 
----
+Proprietary - All rights reserved
 
-## 📞 Support
+## 👥 Team
 
-For questions or issues, contact: [your-email@example.com]
+SwiftOps Development Team

alembic.ini

@@ -0,0 +1,41 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+version_path_separator = os
+sqlalchemy.url = postgresql://swiftops:swiftops_dev@localhost:5432/swiftops_db
+
+[post_write_hooks]
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/env.py

@@ -0,0 +1,68 @@
+"""
+Alembic Environment Configuration
+"""
+from logging.config import fileConfig
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+from alembic import context
+import sys
+from pathlib import Path
+
+# Add src directory to path
+sys.path.append(str(Path(__file__).resolve().parents[1]))
+
+from app.core.database import Base
+from app.config import settings
+
+# Import all models to ensure they're registered with Base
+from app.models import user, organization, project, ticket, customer, incident, inventory, finance, timesheet, document, media, audit_log
+
+# this is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set sqlalchemy.url from settings
+config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
+
+# add your model's MetaData object here for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

docs/README.md

@@ -0,0 +1,774 @@
+# SwiftOps Backend API
+
+**Field Service Management Platform - FastAPI Backend**
+
+A scalable, production-ready FastAPI backend for managing field service operations including ticket management, payroll processing, inventory tracking, and financial workflows.
+
+---
+
+## 🏗️ Architecture Overview
+
+```
+backend/
+├── app/
+│   ├── __init__.py
+│   ├── main.py                      # FastAPI application entry point
+│   ├── config.py                    # Configuration management (env vars, settings)
+│   │
+│   ├── api/                         # API Layer - HTTP endpoints
+│   │   ├── __init__.py
+│   │   ├── deps.py                  # Shared dependencies (auth, db session)
+│   │   ├── v1/                      # API version 1
+│   │   │   ├── __init__.py
+│   │   │   ├── router.py            # Main router aggregator
+│   │   │   ├── auth.py              # Authentication endpoints
+│   │   │   ├── users.py             # User management
+│   │   │   ├── projects.py          # Project CRUD
+│   │   │   ├── tickets.py           # Ticket operations
+│   │   │   ├── assignments.py       # Ticket assignment logic
+│   │   │   ├── payroll.py           # Payroll generation & management
+│   │   │   ├── inventory.py         # Inventory tracking
+│   │   │   ├── finance.py           # Financial transactions
+│   │   │   ├── customers.py         # Customer management
+│   │   │   ├── subscriptions.py     # Subscription lifecycle
+│   │   │   ├── incidents.py         # Support incidents
+│   │   │   ├── sales_orders.py      # Sales order processing
+│   │   │   ├── analytics.py         # Dashboard & reporting
+│   │   │   └── webhooks.py          # Payment gateway webhooks
+│   │   │
+│   │   └── websockets/              # WebSocket endpoints
+│   │       ├── __init__.py
+│   │       ├── location.py          # Real-time location tracking
+│   │       └── notifications.py     # Real-time notifications
+│   │
+│   ├── core/                        # Core Business Logic
+│   │   ├── __init__.py
+│   │   ├── auth.py                  # JWT handling, password hashing
+│   │   ├── security.py              # RLS, permissions, RBAC
+│   │   ├── exceptions.py            # Custom exception classes
+│   │   └── middleware.py            # Custom middleware (logging, CORS)
+│   │
+│   ├── services/                    # Business Logic Layer
+│   │   ├── __init__.py
+│   │   ├── ticket_service.py        # Ticket lifecycle, assignment logic
+│   │   ├── payroll_service.py       # Payroll calculation, generation
+│   │   ├── inventory_service.py     # Inventory allocation, tracking
+│   │   ├── finance_service.py       # Transaction workflows, approvals
+│   │   ├── sla_service.py           # SLA calculation, monitoring
+│   │   ├── location_service.py      # GPS validation, distance calculation
+│   │   ├── notification_service.py  # Email, SMS, push notifications
+│   │   ├── payment_service.py       # Payment gateway integration
+│   │   ├── subscription_service.py  # Subscription activation, lifecycle
+│   │   └── analytics_service.py     # Metrics, dashboard data
+│   │
+│   ├── models/                      # SQLAlchemy ORM Models
+│   │   ├── __init__.py
+│   │   ├── base.py                  # Base model with common fields
+│   │   ├── user.py                  # User, UserFinancialAccounts
+│   │   ├── organization.py          # Clients, Contractors
+│   │   ├── project.py               # Projects, ProjectTeam, ProjectRoles
+│   │   ├── ticket.py                # Tickets, TicketAssignments, TicketStatusHistory
+│   │   ├── customer.py              # Customers, SalesOrders, Subscriptions
+│   │   ├── incident.py              # Incidents
+│   │   ├── inventory.py             # ProjectInventory, InventoryAssignments
+│   │   ├── finance.py               # ProjectFinance, UserPayroll, PaymentLogs
+│   │   ├── timesheet.py             # Timesheets
+│   │   └── document.py              # Documents
+│   │
+│   ├── schemas/                     # Pydantic Schemas (Request/Response)
+│   │   ├── __init__.py
+│   │   ├── user.py                  # UserCreate, UserUpdate, UserResponse
+│   │   ├── project.py               # ProjectCreate, ProjectUpdate, ProjectResponse
+│   │   ├── ticket.py                # TicketCreate, TicketUpdate, TicketResponse
+│   │   ├── payroll.py               # PayrollCreate, PayrollCalculation
+│   │   ├── inventory.py             # InventoryAssignment, InventoryDistribution
+│   │   ├── finance.py               # TransactionCreate, TransactionApproval
+│   │   └── common.py                # Shared schemas (Pagination, Filters)
+│   │
+│   ├── repositories/                # Data Access Layer (Repository Pattern)
+│   │   ├── __init__.py
+│   │   ├── base.py                  # Base repository with CRUD operations
+│   │   ├── user_repository.py       # User-specific queries
+│   │   ├── ticket_repository.py     # Ticket-specific queries
+│   │   ├── payroll_repository.py    # Payroll-specific queries
+│   │   └── finance_repository.py    # Finance-specific queries
+│   │
+│   ├── tasks/                       # Background Tasks (Celery)
+│   │   ├── __init__.py
+│   │   ├── celery_app.py            # Celery configuration
+│   │   ├── payroll_tasks.py         # Weekly payroll generation
+│   │   ├── sla_tasks.py             # SLA monitoring, alerts
+│   │   ├── notification_tasks.py    # Send emails, SMS
+│   │   ├── invoice_tasks.py         # Generate contractor invoices
+│   │   └── analytics_tasks.py       # Pre-compute dashboard metrics
+│   │
+│   ├── integrations/                # External Service Integrations
+│   │   ├── __init__.py
+│   │   ├── supabase.py              # Supabase client (Auth, Storage, Realtime)
+│   │   ├── mpesa.py                 # M-Pesa payment gateway
+│   │   ├── google_maps.py           # Google Maps API (geocoding, distance)
+│   │   ├── sms_provider.py          # SMS gateway (Africa's Talking, Twilio)
+│   │   ├── email_provider.py        # Email service (SendGrid, AWS SES)
+│   │   └── storage.py               # File storage (Supabase Storage, S3)
+│   │
+│   ├── utils/                       # Utility Functions
+│   │   ├── __init__.py
+│   │   ├── date_utils.py            # Date/time helpers
+│   │   ├── location_utils.py        # GPS calculations, distance
+│   │   ├── validation.py            # Custom validators
+│   │   ├── formatters.py            # Data formatting helpers
+│   │   └── constants.py             # Application constants
+│   │
+│   └── db/                          # Database Configuration
+│       ├── __init__.py
+│       ├── session.py               # Database session management
+│       ├── base.py                  # Base class for all models
+│       └── migrations/              # Alembic migrations
+│           └── versions/
+│
+├── tests/                           # Test Suite
+│   ├── __init__.py
+│   ├── conftest.py                  # Pytest fixtures
+│   ├── unit/                        # Unit tests
+│   │   ├── test_services/
+│   │   ├── test_repositories/
+│   │   └── test_utils/
+│   ├── integration/                 # Integration tests
+│   │   ├── test_api/
+│   │   └── test_tasks/
+│   └── e2e/                         # End-to-end tests
+│
+├── scripts/                         # Utility Scripts
+│   ├── seed_data.py                 # Seed database with test data
+│   ├── generate_payroll.py          # Manual payroll generation
+│   └── migrate_data.py              # Data migration scripts
+│
+├── .env.example                     # Environment variables template
+├── .gitignore
+├── requirements.txt                 # Python dependencies
+├── pyproject.toml                   # Poetry configuration (alternative)
+├── Dockerfile                       # Docker container definition
+├── docker-compose.yml               # Local development setup
+└── README.md                        # This file
+```
+
+---
+
+## 🎯 Core Functions & Responsibilities
+
+### **1. Authentication & Authorization**
+**Module**: `app/api/v1/auth.py`, `app/core/auth.py`, `app/core/security.py`
+
+**Functions**:
+- User login/logout (JWT token generation)
+- Password reset flow
+- Role-based access control (RBAC)
+- Row-level security (RLS) enforcement
+- Multi-tenancy isolation (client/contractor scoping)
+
+**Supabase Integration**:
+- Uses Supabase Auth for user authentication
+- Validates JWT tokens from Supabase
+- Syncs user roles with custom `Users` table
+
+---
+
+### **2. Ticket Management**
+**Module**: `app/services/ticket_service.py`, `app/api/v1/tickets.py`
+
+**Functions**:
+- Create tickets from sales orders, incidents, or tasks
+- Ticket assignment logic (manual, auto-assignment)
+- Limit self-assignment to 3 tickets per agent
+- Status transitions with validation
+- SLA deadline calculation and monitoring
+- GPS-based arrival verification
+- Ticket completion workflow
+
+**Business Rules**:
+```python
+# Example: Ticket Assignment Logic
+def assign_ticket(ticket_id, user_id):
+    # 1. Check user has < 3 active assignments
+    # 2. Verify user is in project team
+    # 3. Check user's region matches ticket region
+    # 4. Create TicketAssignment record
+    # 5. Update ticket status to 'assigned'
+    # 6. Send notification to agent
+    # 7. Update SLA target date
+```
+
+---
+
+### **3. Payroll Processing**
+**Module**: `app/services/payroll_service.py`, `app/api/v1/payroll.py`
+
+**Functions**:
+- Weekly payroll generation (automated via Celery)
+- Calculate earnings based on compensation type:
+  - Flat rate (fixed weekly amount)
+  - Commission (% of package price)
+  - Hybrid (base + commission)
+  - Hourly (based on timesheet hours)
+- Apply deductions (advances, penalties)
+- Generate payroll reports
+- Mark payroll as paid with payment reference
+
+**Business Rules**:
+```python
+# Example: Payroll Calculation
+def calculate_payroll(user_id, project_id, period_start, period_end):
+    role = get_user_project_role(user_id, project_id)
+    tickets_closed = count_tickets_closed(user_id, period_start, period_end)
+    hours_worked = sum_timesheet_hours(user_id, period_start, period_end)
+    
+    if role.compensation_type == 'flat_rate':
+        earnings = role.flat_rate_amount
+    elif role.compensation_type == 'commission':
+        earnings = sum_ticket_values(tickets) * role.commission_percentage
+    elif role.compensation_type == 'hybrid':
+        earnings = role.base_amount + (sum_ticket_values(tickets) * role.commission_percentage)
+    elif role.compensation_type == 'hourly':
+        earnings = hours_worked * role.hourly_rate
+    
+    deductions = get_user_deductions(user_id, period_start, period_end)
+    total = earnings - deductions
+    
+    return create_payroll_record(...)
+```
+
+---
+
+### **4. Inventory Management**
+**Module**: `app/services/inventory_service.py`, `app/api/v1/inventory.py`
+
+**Functions**:
+- Allocate inventory to regional hubs
+- Issue equipment to field agents
+- Track serial numbers and unit identifiers
+- Prevent duplicate assignments (same serial issued twice)
+- Handle returns (tools) and installations (equipment)
+- Optimistic locking for concurrent updates
+- Inventory reconciliation reports
+
+**Business Rules**:
+```python
+# Example: Inventory Assignment
+def assign_inventory_to_agent(distribution_id, user_id, unit_identifier):
+    # 1. Check unit_identifier not already assigned
+    # 2. Verify quantity_available > 0
+    # 3. Check user is in same region as distribution
+    # 4. Create InventoryAssignment record
+    # 5. Update distribution.quantity_issued
+    # 6. Use optimistic locking (version field)
+```
+
+---
+
+### **5. Financial Management**
+**Module**: `app/services/finance_service.py`, `app/api/v1/finance.py`
+
+**Functions**:
+- Record project expenses (inflows/outflows)
+- Approval workflow (pending → approved → paid)
+- Link to entities (tickets, payroll, invoices)
+- Payment gateway integration (M-Pesa, bank transfers)
+- Transaction reconciliation
+- Financial reporting and audit trails
+
+**Business Rules**:
+```python
+# Example: Expense Approval Workflow
+def approve_expense(expense_id, approver_id):
+    # 1. Check approver has 'dispatcher' or 'project_manager' role
+    # 2. Verify expense is in 'pending' status
+    # 3. Validate location_verified = TRUE (if required)
+    # 4. Update status to 'approved'
+    # 5. Create ProjectFinance record
+    # 6. Send notification to incurred_by_user
+```
+
+---
+
+### **6. Location Tracking**
+**Module**: `app/services/location_service.py`, `app/api/websockets/location.py`
+
+**Functions**:
+- Real-time GPS tracking via WebSocket
+- Validate agent arrival at customer site
+- Calculate distance between agent and customer
+- Journey tracking (breadcrumb trail)
+- Fraud detection (impossible travel speeds)
+- Update user current location
+
+**Business Rules**:
+```python
+# Example: Arrival Verification
+def verify_arrival(ticket_id, agent_location):
+    ticket = get_ticket(ticket_id)
+    customer_location = get_customer_location(ticket.customer_id)
+    
+    distance = calculate_distance(agent_location, customer_location)
+    
+    if distance <= 100:  # Within 100 meters
+        mark_arrived(ticket_id, agent_location, verified=True)
+    else:
+        mark_arrived(ticket_id, agent_location, verified=False)
+```
+
+---
+
+### **7. SLA Monitoring**
+**Module**: `app/services/sla_service.py`, `app/tasks/sla_tasks.py`
+
+**Functions**:
+- Calculate SLA deadlines based on priority
+- Monitor tickets approaching deadline
+- Send alerts to managers and agents
+- Mark tickets as SLA violated
+- Generate SLA compliance reports
+
+**Background Task** (runs every hour):
+```python
+@celery_app.task
+def monitor_sla_violations():
+    # 1. Find tickets with sla_target_date < now() and status != 'completed'
+    # 2. Mark sla_violated = TRUE
+    # 3. Send notifications to project managers
+    # 4. Log SLA violation event
+```
+
+---
+
+### **8. Payment Gateway Integration**
+**Module**: `app/services/payment_service.py`, `app/integrations/mpesa.py`
+
+**Functions**:
+- Initiate M-Pesa payments (B2C, B2B)
+- Handle payment callbacks/webhooks
+- Retry failed payments
+- Log all payment attempts (PaymentLogs)
+- Reconcile payments with transactions
+
+**Webhook Handler**:
+```python
+@router.post("/webhooks/mpesa")
+async def mpesa_callback(payload: dict):
+    # 1. Validate webhook signature
+    # 2. Parse payment result
+    # 3. Update ProjectFinance status
+    # 4. Create PaymentLog entry
+    # 5. Send notification to user
+```
+
+---
+
+### **9. Subscription Management**
+**Module**: `app/services/subscription_service.py`, `app/api/v1/subscriptions.py`
+
+**Functions**:
+- Activate subscriptions after installation
+- Validate activation requirements (dynamic per project)
+- Manage subscription lifecycle (active, suspended, cancelled)
+- Link subscriptions to tickets and sales orders
+
+**Business Rules**:
+```python
+# Example: Subscription Activation
+def activate_subscription(subscription_id, activation_data):
+    subscription = get_subscription(subscription_id)
+    project = get_project(subscription.project_id)
+    
+    # Validate dynamic activation requirements
+    for requirement in project.activation_requirements:
+        if requirement['required'] and requirement['field'] not in activation_data:
+            raise ValidationError(f"Missing required field: {requirement['label']}")
+    
+    # Update subscription
+    subscription.status = 'active'
+    subscription.activation_date = date.today()
+    subscription.activation_details = activation_data
+    subscription.activated_by_user_id = current_user.id
+```
+
+---
+
+### **10. Analytics & Reporting**
+**Module**: `app/services/analytics_service.py`, `app/api/v1/analytics.py`
+
+**Functions**:
+- Dashboard metrics (tickets, revenue, SLA compliance)
+- Agent performance reports
+- Project financial summaries
+- Inventory utilization reports
+- Pre-computed aggregations (via Celery)
+
+**Background Task** (runs daily):
+```python
+@celery_app.task
+def compute_daily_metrics():
+    # 1. Calculate tickets closed per agent
+    # 2. Compute average completion time
+    # 3. Calculate SLA compliance rate
+    # 4. Store in cache (Redis)
+```
+
+---
+
+## 🔗 Supabase Integration Points
+
+### **1. Authentication**
+```python
+# app/integrations/supabase.py
+from supabase import create_client
+
+supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
+
+# Verify JWT token from frontend
+def verify_token(token: str):
+    user = supabase.auth.get_user(token)
+    return user
+```
+
+### **2. Storage (File Uploads)**
+```python
+# Upload ticket photos, receipts
+def upload_document(file, bucket="documents"):
+    path = f"{user_id}/{ticket_id}/{filename}"
+    supabase.storage.from_(bucket).upload(path, file)
+    return supabase.storage.from_(bucket).get_public_url(path)
+```
+
+### **3. Realtime (WebSocket)**
+```python
+# Subscribe to ticket updates
+supabase.realtime.channel('tickets')
+    .on('postgres_changes', 
+        event='UPDATE', 
+        schema='public', 
+        table='Tickets',
+        callback=handle_ticket_update)
+    .subscribe()
+```
+
+### **4. Database (Direct Queries)**
+```python
+# Use Supabase client for simple queries (optional)
+# For complex queries, use SQLAlchemy ORM
+tickets = supabase.table('Tickets').select('*').eq('status', 'open').execute()
+```
+
+---
+
+## 🚀 Getting Started
+
+### **Prerequisites**
+- Python 3.11+
+- PostgreSQL 15+ (Supabase)
+- Redis (for caching and Celery)
+- Docker & Docker Compose (optional)
+
+### **Installation**
+
+1. **Clone the repository**
+```bash
+git clone <repo-url>
+cd backend
+```
+
+2. **Create virtual environment**
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. **Install dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+4. **Set up environment variables**
+```bash
+cp .env.example .env
+# Edit .env with your Supabase credentials
+```
+
+5. **Run database migrations**
+```bash
+alembic upgrade head
+```
+
+6. **Start the development server**
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+7. **Start Celery worker** (in separate terminal)
+```bash
+celery -A app.tasks.celery_app worker --loglevel=info
+```
+
+8. **Start Celery beat** (scheduler, in separate terminal)
+```bash
+celery -A app.tasks.celery_app beat --loglevel=info
+```
+
+---
+
+## 🐳 Docker Setup
+
+```bash
+# Start all services (API, Celery, Redis)
+docker-compose up -d
+
+# View logs
+docker-compose logs -f api
+
+# Stop services
+docker-compose down
+```
+
+---
+
+## 📝 Environment Variables
+
+```bash
+# .env.example
+
+# Application
+APP_NAME=SwiftOps API
+APP_VERSION=1.0.0
+DEBUG=True
+ENVIRONMENT=development
+
+# Database (Supabase PostgreSQL)
+DATABASE_URL=postgresql://user:password@host:5432/dbname
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your-anon-key
+SUPABASE_SERVICE_KEY=your-service-role-key
+
+# JWT
+SECRET_KEY=your-secret-key-here
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+
+# Celery
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/0
+
+# Payment Gateways
+MPESA_CONSUMER_KEY=your-mpesa-key
+MPESA_CONSUMER_SECRET=your-mpesa-secret
+MPESA_SHORTCODE=174379
+MPESA_PASSKEY=your-passkey
+
+# Google Maps
+GOOGLE_MAPS_API_KEY=your-google-maps-key
+
+# SMS Provider (Africa's Talking)
+AFRICASTALKING_USERNAME=your-username
+AFRICASTALKING_API_KEY=your-api-key
+
+# Email Provider (SendGrid)
+SENDGRID_API_KEY=your-sendgrid-key
+FROM_EMAIL=noreply@swiftops.com
+
+# File Storage
+STORAGE_PROVIDER=supabase  # or 's3'
+AWS_ACCESS_KEY_ID=your-aws-key
+AWS_SECRET_ACCESS_KEY=your-aws-secret
+AWS_S3_BUCKET=your-bucket-name
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=app --cov-report=html
+
+# Run specific test file
+pytest tests/unit/test_services/test_payroll_service.py
+
+# Run integration tests only
+pytest tests/integration/
+```
+
+---
+
+## 📚 API Documentation
+
+Once the server is running, visit:
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **OpenAPI JSON**: http://localhost:8000/openapi.json
+
+---
+
+## 🏛️ Design Patterns & Best Practices
+
+### **1. Repository Pattern**
+Separates data access logic from business logic.
+
+```python
+# app/repositories/ticket_repository.py
+class TicketRepository:
+    def get_by_id(self, ticket_id: UUID) -> Ticket:
+        return db.query(Ticket).filter(Ticket.id == ticket_id).first()
+    
+    def get_open_tickets(self, project_id: UUID) -> List[Ticket]:
+        return db.query(Ticket).filter(
+            Ticket.project_id == project_id,
+            Ticket.status == 'open',
+            Ticket.deleted_at.is_(None)
+        ).all()
+```
+
+### **2. Service Layer Pattern**
+Encapsulates business logic.
+
+```python
+# app/services/ticket_service.py
+class TicketService:
+    def __init__(self, ticket_repo: TicketRepository):
+        self.ticket_repo = ticket_repo
+    
+    def assign_ticket(self, ticket_id: UUID, user_id: UUID):
+        # Business logic here
+        ticket = self.ticket_repo.get_by_id(ticket_id)
+        self._validate_assignment(ticket, user_id)
+        assignment = self._create_assignment(ticket, user_id)
+        self._send_notification(user_id, ticket)
+        return assignment
+```
+
+### **3. Dependency Injection**
+Use FastAPI's dependency injection system.
+
+```python
+# app/api/deps.py
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+def get_current_user(token: str = Depends(oauth2_scheme)):
+    # Validate token and return user
+    return user
+
+# Usage in endpoint
+@router.get("/tickets")
+def get_tickets(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    return ticket_service.get_tickets(db, current_user)
+```
+
+### **4. Optimistic Locking**
+Prevent concurrent update conflicts.
+
+```python
+def update_inventory_distribution(distribution_id, updates, version):
+    distribution = db.query(ProjectInventoryDistribution).filter(
+        ProjectInventoryDistribution.id == distribution_id,
+        ProjectInventoryDistribution.version == version
+    ).first()
+    
+    if not distribution:
+        raise ConcurrentUpdateError("Record was modified by another user")
+    
+    # Apply updates
+    distribution.quantity_issued += updates.quantity
+    distribution.version += 1
+    db.commit()
+```
+
+### **5. Soft Deletes**
+Always filter out soft-deleted records.
+
+```python
+# Base repository method
+def get_active(self, model_class):
+    return db.query(model_class).filter(model_class.deleted_at.is_(None))
+```
+
+---
+
+## 🔐 Security Considerations
+
+1. **Row-Level Security (RLS)**
+   - Enforce tenant isolation at database level
+   - Use Supabase RLS policies
+
+2. **API Rate Limiting**
+   - Implement rate limiting per client/user
+   - Use Redis for rate limit tracking
+
+3. **Input Validation**
+   - Use Pydantic schemas for all inputs
+   - Validate file uploads (type, size)
+
+4. **Audit Logging**
+   - Log all financial transactions
+   - Track who created/updated records
+
+5. **Secrets Management**
+   - Never commit secrets to git
+   - Use environment variables or secret managers
+
+---
+
+## 📈 Scalability Considerations
+
+1. **Database Connection Pooling**
+   - Use SQLAlchemy connection pool
+   - Configure pool size based on load
+
+2. **Caching Strategy**
+   - Cache frequently accessed data (Redis)
+   - Invalidate cache on updates
+
+3. **Background Jobs**
+   - Offload heavy tasks to Celery
+   - Use task queues for async processing
+
+4. **Horizontal Scaling**
+   - Stateless API design
+   - Load balance across multiple instances
+
+5. **Database Optimization**
+   - Use indexes effectively
+   - Monitor slow queries
+   - Consider read replicas for reporting
+
+---
+
+## 🤝 Contributing
+
+1. Create a feature branch
+2. Write tests for new features
+3. Follow PEP 8 style guide
+4. Update documentation
+5. Submit pull request
+
+---
+
+## 📄 License
+
+[Your License Here]
+
+---
+
+## 📞 Support
+
+For questions or issues, contact: [your-email@example.com]

docs/agent/COMPREHENSIVE_BUILD_PLAN.md

@@ -0,0 +1,2340 @@
+# SwiftOps Backend - Comprehensive Build Plan
+## Senior Developer's End-to-End Implementation Guide
+
+**Version:** 1.0  
+**Created:** 2025-11-15  
+**Status:** Master Build Plan  
+**Approach:** Complete System Build (All-at-Once View)
+
+---
+
+## 📋 Executive Summary
+
+This document provides a complete, end-to-end build plan for the SwiftOps backend system. It's designed for a top 1% senior developer who needs to see the entire architecture, understand all components, and build a robust, maintainable system that a human can easily navigate and extend.
+
+### Core Principles
+1. **Clean Architecture** - Clear separation of concerns (API → Service → Repository → Model)
+2. **Domain-Driven Design** - Business logic organized by domain boundaries
+3. **SOLID Principles** - Single responsibility, dependency injection, interface segregation
+4. **Maintainability First** - Code that's easy to read, understand, and modify
+5. **Production-Ready** - Built for scale, monitoring, and operational excellence
+
+---
+
+## 🏗️ Architecture Overview
+
+### High-Level System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CLIENT LAYER                             │
+│  (Web Dashboard, Mobile App, External APIs)                      │
+└────────────────────────┬────────────────────────────────────────┘
+                         │ HTTPS/REST
+┌────────────────────────▼────────────────────────────────────────┐
+│                      API GATEWAY LAYER                           │
+│  • Rate Limiting  • Authentication  • Request Validation         │
+│  • CORS  • Compression  • Logging                                │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────────────┐
+│                      API ENDPOINTS LAYER                         │
+│  (FastAPI Routers - Thin Controllers)                            │
+│  • Input Validation (Pydantic)                                   │
+│  • Response Formatting                                           │
+│  • Error Handling                                                │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────────────┐
+│                      SERVICE LAYER                               │
+│  (Business Logic - The Brain)                                    │
+│  • Domain Logic  • Validation Rules  • Orchestration             │
+│  • Transaction Management  • Event Publishing                    │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────────────┐
+│                    REPOSITORY LAYER                              │
+│  (Data Access - Database Abstraction)                            │
+│  • CRUD Operations  • Query Building  • Caching                  │
+└────────────────────────┬────────────────────────────────────────┘
+                         │
+┌────────────────────────▼────────────────────────────────────────┐
+│                      DATABASE LAYER                              │
+│  PostgreSQL (Supabase) - Single Source of Truth                  │
+└─────────────────────────────────────────────────��────────────────┘
+
+┌──────────────────────────────────────────────────────────────────┐
+│                    SUPPORTING SYSTEMS                             │
+├──────────────────────────────────────────────────────────────────┤
+│  • Redis (Caching, Sessions, Locks)                              │
+│  • Celery (Background Jobs, Scheduled Tasks)                     │
+│  • External APIs (M-Pesa, Cloudinary, Resend, Google Maps)       │
+│  • Monitoring (Sentry, Logs, Metrics)                            │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📁 Complete Folder Structure
+
+This is the **definitive** folder structure that ensures maintainability and clarity:
+
+```
+swiftops-backend/
+│
+├── src/                                    # Source code root
+│   └── app/                                # Main application package
+│       │
+│       ├── __init__.py                     # App package initialization
+│       ├── main.py                         # FastAPI app entry point
+│       ├── config.py                       # Configuration management
+│       ├── dependencies.py                 # Global dependencies (DB, Auth)
+│       │
+│       ├── core/                           # Core utilities (used everywhere)
+│       │   ├── __init__.py
+│       │   ├── auth.py                     # JWT, token management
+│       │   ├── security.py                 # Password hashing, encryption
+│       │   ├── permissions.py              # RBAC permission definitions
+│       │   ├── exceptions.py               # Custom exception classes
+│       │   ├── logging.py                  # Structured logging setup
+│       │   └── database.py                 # Database session management
+│       │
+│       ├── middleware/                     # HTTP middleware
+│       │   ├── __init__.py
+│       │   ├── authentication.py           # Auth middleware
+│       │   ├── rate_limiting.py            # Rate limiter
+│       │   ├── request_logging.py          # Request/response logging
+│       │   ├── error_handling.py           # Global error handler
+│       │   └── cors.py                     # CORS configuration
+│       │
+│       ├── api/                            # API layer (HTTP endpoints)
+│       │   ├── __init__.py
+│       │   ├── deps.py                     # Route dependencies
+│       │   │
+│       │   └── v1/                         # API version 1
+│       │       ├── __init__.py
+│       │       ├── router.py               # Main router aggregator
+│       │       │
+│       │       ├── auth.py                 # Authentication endpoints
+│       │       ├── users.py                # User management
+│       │       ├── organizations.py        # Clients & Contractors
+│       │       ├── projects.py             # Project CRUD
+│       │       ├── tickets.py              # Ticket operations
+│       │       ├── assignments.py          # Ticket assignments
+│       │       ├── customers.py            # Customer management
+│       │       ├── sales_orders.py         # Sales order processing
+│       │       ├── subscriptions.py        # Subscription management
+│       │       ├── incidents.py            # Support incidents
+│       │       ├── inventory.py            # Inventory management
+│       │       ├── expenses.py             # Expense tracking
+│       │       ├── payroll.py              # Payroll management
+│       │       ├── timesheets.py           # Timesheet tracking
+│       │       ├── documents.py            # Document management
+│       │       ├── media.py                # Photo/file uploads
+│       │       ├── reports.py              # Report generation
+│       │       ├── analytics.py            # Analytics endpoints
+│       │       ├── webhooks.py             # External webhooks (M-Pesa)
+│       │       └── health.py               # Health check endpoints
+│       │
+│       ├── services/                       # Business logic layer (THE BRAIN)
+│       │   ├── __init__.py
+│       │   │
+│       │   ├── auth_service.py             # Authentication logic
+│       │   ├── user_service.py             # User management logic
+│       │   ├── organization_service.py     # Client/Contractor logic
+│       │   ├── project_service.py          # Project management logic
+│       │   ├── ticket_service.py           # Ticket lifecycle logic
+│       │   ├── assignment_service.py       # Ticket assignment logic
+│       │   ├── customer_service.py         # Customer management logic
+│       │   ├── sales_order_service.py      # Sales order processing
+│       │   ├── subscription_service.py     # Subscription lifecycle
+│       │   ├── incident_service.py         # Incident management
+│       │   ├── inventory_service.py        # Inventory tracking
+│       │   ├── expense_service.py          # Expense management
+│       │   ├── payroll_service.py          # Payroll calculation
+│       │   ├── timesheet_service.py        # Timesheet management
+│       │   ├── document_service.py         # Document handling
+│       │   ├── media_service.py            # Photo/file management
+│       │   ├── notification_service.py     # Notification orchestration
+│       │   ├── report_service.py           # Report generation
+│       │   ├── analytics_service.py        # Analytics computation
+│       │   ├── csv_import_service.py       # CSV import logic
+│       │   ├── csv_export_service.py       # CSV export logic
+│       │   ├── allocation_service.py       # Agent allocation (V2)
+│       │   ├── route_optimization_service.py  # Route planning (V2)
+│       │   └── otp_service.py              # OTP generation/verification
+│       │
+│       ├── repositories/                   # Data access layer
+│       │   ├── __init__.py
+│       │   ├── base_repository.py          # Base repository with common methods
+│       │   │
+│       │   ├── user_repository.py
+│       │   ├── organization_repository.py
+│       │   ├── project_repository.py
+│       │   ├── ticket_repository.py
+│       │   ├── assignment_repository.py
+│       │   ├── customer_repository.py
+│       │   ├── sales_order_repository.py
+│       │   ├── subscription_repository.py
+│       │   ├── incident_repository.py
+│       │   ├── inventory_repository.py
+│       │   ├── expense_repository.py
+│       │   ├── payroll_repository.py
+│       │   ├── timesheet_repository.py
+│       │   ├── document_repository.py
+│       │   └── audit_log_repository.py
+│       │
+│       ├── models/                         # SQLAlchemy ORM models
+│       │   ├── __init__.py
+│       │   ├── base.py                     # Base model with common fields
+│       │   │
+│       │   ├── user.py                     # Users, UserFinancialAccounts, UserAssetAssignments
+│       │   ├── organization.py             # Clients, Contractors
+│       │   ├── project.py                  # Projects, ProjectTeam, ProjectRoles, ProjectRegions
+│       │   ├── ticket.py                   # Tickets, TicketAssignments, TicketStatusHistory
+│       │   ├── customer.py                 # Customers, SalesOrders, Subscriptions
+│       │   ├── incident.py                 # Incidents
+│       │   ├── inventory.py                # ProjectInventory, InventoryAssignments
+│       │   ├── finance.py                  # ProjectFinance, UserPayroll, PaymentLogs
+│       │   ├── timesheet.py                # Timesheets
+│       │   ├── document.py                 # Documents, DocumentVersions
+│       │   ├── media.py                    # MediaFiles
+│       │   ├── audit_log.py                # AuditLogs
+│       │   └── enums.py                    # All ENUM types
+│       │
+│       ├── schemas/                        # Pydantic schemas (request/response)
+│       │   ├── __init__.py
+│       │   ├── base.py                     # Base schemas
+│       │   │
+│       │   ├── auth.py                     # Login, Token, OTP schemas
+│       │   ├── user.py                     # User CRUD schemas
+│       │   ├── organization.py             # Client/Contractor schemas
+│       │   ├── project.py                  # Project schemas
+│       │   ├── ticket.py                   # Ticket schemas
+│       │   ├── assignment.py               # Assignment schemas
+│       │   ├── customer.py                 # Customer schemas
+│       │   ├── sales_order.py              # Sales order schemas
+│       │   ├── subscription.py             # Subscription schemas
+│       │   ├── incident.py                 # Incident schemas
+│       │   ├── inventory.py                # Inventory schemas
+│       │   ├── expense.py                  # Expense schemas
+│       │   ├── payroll.py                  # Payroll schemas
+│       │   ├── timesheet.py                # Timesheet schemas
+│       │   ├── document.py                 # Document schemas
+│       │   ├── media.py                    # Media schemas
+│       │   ├── report.py                   # Report schemas
+│       │   └── common.py                   # Common schemas (pagination, filters)
+│       │
+│       ├── tasks/                          # Celery background tasks
+│       │   ├── __init__.py
+│       │   ├── celery_app.py               # Celery configuration
+│       │   │
+│       │   ├── notification_tasks.py       # Email/SMS sending
+│       │   ├── payroll_tasks.py            # Payroll generation
+│       │   ├── payment_tasks.py            # Payment processing
+│       │   ├── import_tasks.py             # CSV import processing
+│       │   ├── export_tasks.py             # Report export generation
+│       │   ├── analytics_tasks.py          # Analytics computation
+│       │   ├── sla_tasks.py                # SLA monitoring
+│       │   └── cleanup_tasks.py            # Data cleanup
+│       │
+│       ├── integrations/                   # External service integrations
+│       │   ├── __init__.py
+│       │   │
+│       │   ├── supabase.py                 # Supabase client
+│       │   ├── cloudinary.py               # Cloudinary image uploads
+│       │   ├── mpesa.py                    # M-Pesa payment gateway
+│       │   ├── resend.py                   # Resend email service
+│       │   ├── africastalking.py           # Africa's Talking SMS (V2)
+│       │   ├── google_maps.py              # Google Maps API
+│       │   └── sentry.py                   # Sentry error tracking
+│       │
+│       ├── utils/                          # Utility functions
+│       │   ├── __init__.py
+│       │   │
+│       │   ├── cache.py                    # Redis caching utilities
+│       │   ├── encryption.py               # Data encryption
+│       │   ├── validators.py               # Custom validators
+│       │   ├── formatters.py               # Data formatters
+│       │   ├── pagination.py               # Pagination helpers
+│       │   ├── filters.py                  # Query filter builders
+│       │   ├── date_utils.py               # Date/time utilities
+│       │   ├── phone_utils.py              # Phone number validation
+│       │   ├── location_utils.py           # GPS/location utilities
+│       │   ├── file_utils.py               # File handling utilities
+│       │   ├── csv_utils.py                # CSV parsing utilities
+│       │   └── distributed_lock.py         # Redis distributed locks
+│       │
+│       └── constants/                      # Application constants
+│           ├── __init__.py
+│           ├── roles.py                    # Role definitions
+│           ├── permissions.py              # Permission mappings
+│           ├── status.py                   # Status constants
+│           └── messages.py                 # User-facing messages
+│
+├── tests/                                  # Test suite
+│   ├── __init__.py
+│   ├── conftest.py                         # Pytest configuration
+│   │
+│   ├── unit/                               # Unit tests
+│   │   ├── services/
+│   │   ├── repositories/
+│   │   └── utils/
+│   │
+│   ├── integration/                        # Integration tests
+│   │   ├── api/
+│   │   ├── database/
+│   │   └── external_services/
+│   │
+│   └── fixtures/                           # Test fixtures
+│       ├── users.py
+│       ├── projects.py
+│       └── tickets.py
+│
+├── scripts/                                # Utility scripts
+│   ├── seed_database.py                    # Database seeding
+│   ├── migrate_data.py                     # Data migration
+│   ├── generate_test_data.py               # Test data generation
+│   └── backup_database.py                  # Database backup
+│
+├── alembic/                                # Database migrations
+│   ├── versions/                           # Migration files
+│   ├── env.py                              # Alembic environment
+│   └── script.py.mako                      # Migration template
+│
+├── docs/                                   # Documentation
+│   ├── agent/                              # AI agent plans
+│   ├── dev/                                # Developer docs
+│   ├── prod/                               # Production docs
+│   └── schema/                             # Database schema
+│
+├── .env.example                            # Environment template
+├── .env                                    # Environment variables (gitignored)
+├── .gitignore                              # Git ignore rules
+├── requirements.txt                        # Python dependencies
+├── requirements-dev.txt                    # Development dependencies
+├── Dockerfile                              # Docker image definition
+├── docker-compose.yml                      # Docker services
+├── alembic.ini                             # Alembic configuration
+├── pytest.ini                              # Pytest configuration
+├── .pre-commit-config.yaml                 # Pre-commit hooks
+└── README.md                               # Project documentation
+```
+
+---
+
+## 🎯 Domain Boundaries & Component Organization
+
+### Domain 1: Authentication & Authorization
+**Purpose:** User identity, access control, security
+**Components:**
+- `core/auth.py` - JWT token management
+- `core/security.py` - Password hashing, encryption
+- `core/permissions.py` - RBAC definitions
+- `services/auth_service.py` - Login, logout, token refresh
+- `services/otp_service.py` - 2FA implementation
+- `api/v1/auth.py` - Auth endpoints
+
+**Key Responsibilities:**
+- Validate Supabase JWT tokens
+- Generate application JWT tokens
+- Enforce role-based permissions
+- Handle OTP generation/verification
+- Manage user sessions
+
+---
+
+### Domain 2: User Management
+**Purpose:** User profiles, preferences, financial accounts
+**Components:**
+- `models/user.py` - User, UserFinancialAccounts, UserAssetAssignments, UserPreferences
+- `services/user_service.py` - User CRUD, profile management
+- `repositories/user_repository.py` - User data access
+- `api/v1/users.py` - User endpoints
+
+**Key Responsibilities:**
+- User onboarding and activation
+- Profile management (health info, PPE sizes, emergency contacts)
+- Financial account management (M-Pesa, bank accounts)
+- Asset assignment tracking (tools, vehicles, equipment)
+- User preferences (UI settings, notifications)
+
+---
+
+### Domain 3: Organization Management
+**Purpose:** Clients, contractors, subcontractors
+**Components:**
+- `models/organization.py` - Clients, Contractors
+- `services/organization_service.py` - Organization CRUD
+- `repositories/organization_repository.py` - Organization data access
+- `api/v1/organizations.py` - Organization endpoints
+
+**Key Responsibilities:**
+- Client management (telecom operators)
+- Contractor management (field service providers)
+- Organization activation/deactivation
+- Competency tracking
+- Billing plan management
+
+---
+
+### Domain 4: Project Management
+**Purpose:** Projects, teams, roles, regions, subcontractors
+**Components:**
+- `models/project.py` - Projects, ProjectTeam, ProjectRoles, ProjectRegions, ProjectSubcontractors
+- `services/project_service.py` - Project lifecycle management
+- `repositories/project_repository.py` - Project data access
+- `api/v1/projects.py` - Project endpoints
+
+**Key Responsibilities:**
+- Project creation and configuration
+- Team assignment (main contractor + subcontractors)
+- Regional hub management
+- Role and compensation structure
+- Project closure and archival
+
+---
+
+### Domain 5: Ticket Management
+**Purpose:** Work orders, assignments, status tracking
+**Components:**
+- `models/ticket.py` - Tickets, TicketAssignments, TicketStatusHistory, TicketExpenses
+- `services/ticket_service.py` - Ticket lifecycle
+- `services/assignment_service.py` - Assignment logic
+- `repositories/ticket_repository.py` - Ticket data access
+- `api/v1/tickets.py` - Ticket endpoints
+- `api/v1/assignments.py` - Assignment endpoints
+
+**Key Responsibilities:**
+- Ticket creation from sales orders, incidents, tasks
+- Ticket assignment (manual, self-assignment, auto-allocation)
+- Status transitions (open → assigned → in_progress → completed)
+- SLA tracking and violation detection
+- Expense logging and approval
+- GPS verification and location tracking
+
+---
+
+### Domain 6: Customer & Sales
+**Purpose:** Customers, sales orders, subscriptions
+**Components:**
+- `models/customer.py` - Customers, SalesOrders, Subscriptions
+- `services/customer_service.py` - Customer management
+- `services/sales_order_service.py` - Sales order processing
+- `services/subscription_service.py` - Subscription lifecycle
+- `repositories/customer_repository.py` - Customer data access
+- `api/v1/customers.py` - Customer endpoints
+- `api/v1/sales_orders.py` - Sales order endpoints
+- `api/v1/subscriptions.py` - Subscription endpoints
+
+**Key Responsibilities:**
+- Customer deduplication (by phone number)
+- Sales order CSV import
+- Ticket generation from sales orders
+- Subscription activation after installation
+- Service address management
+- Equipment tracking (ONT, IMEI, etc.)
+
+---
+
+### Domain 7: Support & Incidents
+**Purpose:** Customer support requests, issue tracking
+**Components:**
+- `models/incident.py` - Incidents
+- `services/incident_service.py` - Incident management
+- `repositories/incident_repository.py` - Incident data access
+- `api/v1/incidents.py` - Incident endpoints
+
+**Key Responsibilities:**
+- Incident creation from customer complaints
+- Ticket generation from incidents
+- Issue categorization (no_service, slow_speed, equipment_fault)
+- Resolution tracking
+- Customer communication
+
+---
+
+### Domain 8: Inventory Management
+**Purpose:** Equipment, materials, stock tracking
+**Components:**
+- `models/inventory.py` - ProjectInventory, InventoryAssignments, InventoryTransactions
+- `services/inventory_service.py` - Inventory operations
+- `repositories/inventory_repository.py` - Inventory data access
+- `api/v1/inventory.py` - Inventory endpoints
+
+**Key Responsibilities:**
+- Stock management by region
+- Equipment issuance to field agents
+- Return tracking
+- Low stock alerts
+- Inventory reconciliation
+
+---
+
+### Domain 9: Financial Management
+**Purpose:** Expenses, payroll, payments
+**Components:**
+- `models/finance.py` - ProjectFinance, UserPayroll, PaymentLogs, TicketExpenses
+- `services/expense_service.py` - Expense management
+- `services/payroll_service.py` - Payroll calculation
+- `services/payment_service.py` - Payment processing
+- `repositories/expense_repository.py` - Expense data access
+- `repositories/payroll_repository.py` - Payroll data access
+- `api/v1/expenses.py` - Expense endpoints
+- `api/v1/payroll.py` - Payroll endpoints
+
+**Key Responsibilities:**
+- Expense logging and approval
+- Payroll calculation (weekly, commission-based)
+- Payment processing (M-Pesa, bank transfer)
+- Payment status tracking
+- Financial reporting
+
+---
+
+### Domain 10: Timesheet & Attendance
+**Purpose:** Worker presence, location tracking
+**Components:**
+- `models/timesheet.py` - Timesheets
+- `services/timesheet_service.py` - Timesheet management
+- `repositories/timesheet_repository.py` - Timesheet data access
+- `api/v1/timesheets.py` - Timesheet endpoints
+
+**Key Responsibilities:**
+- Daily attendance tracking
+- Check-in/check-out
+- Leave management
+- Hours worked calculation
+- Location history aggregation
+
+---
+
+### Domain 11: Document Management
+**Purpose:** File uploads, document versioning
+**Components:**
+- `models/document.py` - Documents, DocumentVersions
+- `models/media.py` - MediaFiles
+- `services/document_service.py` - Document handling
+- `services/media_service.py` - Photo/file management
+- `repositories/document_repository.py` - Document data access
+- `api/v1/documents.py` - Document endpoints
+- `api/v1/media.py` - Media endpoints
+
+**Key Responsibilities:**
+- File upload to Cloudinary
+- Document versioning
+- Photo management (before/after, receipts)
+- EXIF data extraction
+- File validation and security
+
+---
+
+### Domain 12: Communication & Notifications
+**Purpose:** Email, SMS, push notifications
+**Components:**
+- `services/notification_service.py` - Notification orchestration
+- `integrations/resend.py` - Email service
+- `integrations/africastalking.py` - SMS service
+- `tasks/notification_tasks.py` - Async notification sending
+
+**Key Responsibilities:**
+- Email sending (transactional, reports)
+- SMS sending (OTP, alerts)
+- Push notifications (mobile app)
+- Notification preferences
+- Delivery tracking
+
+---
+
+### Domain 13: Reporting & Analytics
+**Purpose:** Data export, analytics, dashboards
+**Components:**
+- `services/report_service.py` - Report generation
+- `services/analytics_service.py` - Analytics computation
+- `services/csv_export_service.py` - CSV export
+- `tasks/export_tasks.py` - Async export generation
+- `api/v1/reports.py` - Report endpoints
+- `api/v1/analytics.py` - Analytics endpoints
+
+**Key Responsibilities:**
+- CSV/Excel export
+- Performance analytics
+- SLA compliance reports
+- Financial reports
+- Dashboard metrics
+
+---
+
+### Domain 14: Background Processing
+**Purpose:** Async tasks, scheduled jobs
+**Components:**
+- `tasks/celery_app.py` - Celery configuration
+- `tasks/payroll_tasks.py` - Payroll generation
+- `tasks/payment_tasks.py` - Payment processing
+- `tasks/sla_tasks.py` - SLA monitoring
+- `tasks/cleanup_tasks.py` - Data cleanup
+
+**Key Responsibilities:**
+- Weekly payroll generation
+- Payment queue processing
+- SLA violation detection
+- Data archival
+- Report generation
+
+---
+
+### Domain 15: External Integrations
+**Purpose:** Third-party service integration
+**Components:**
+- `integrations/supabase.py` - Supabase client
+- `integrations/cloudinary.py` - Image uploads
+- `integrations/mpesa.py` - Payment gateway
+- `integrations/google_maps.py` - Geocoding, routing
+- `integrations/sentry.py` - Error tracking
+
+**Key Responsibilities:**
+- Supabase Auth integration
+- Cloudinary image management
+- M-Pesa payment processing
+- Google Maps API calls
+- Error tracking and monitoring
+
+---
+
+## 🔧 Implementation Patterns & Best Practices
+
+### Pattern 1: Repository Pattern (Data Access Layer)
+
+**Purpose:** Abstract database operations, enable testing, centralize queries
+
+**Base Repository Template:**
+```python
+# app/repositories/base_repository.py
+from typing import Generic, TypeVar, Type, Optional, List
+from sqlalchemy.orm import Session
+from sqlalchemy import select, update, delete
+from app.models.base import Base
+
+ModelType = TypeVar("ModelType", bound=Base)
+
+class BaseRepository(Generic[ModelType]):
+    def __init__(self, model: Type[ModelType], db: Session):
+        self.model = model
+        self.db = db
+
+    def get_by_id(self, id: str) -> Optional[ModelType]:
+        """Get single record by ID"""
+        return self.db.query(self.model).filter(
+            self.model.id == id,
+            self.model.deleted_at.is_(None)
+        ).first()
+
+    def get_all(self, skip: int = 0, limit: int = 100) -> List[ModelType]:
+        """Get all records with pagination"""
+        return self.db.query(self.model).filter(
+            self.model.deleted_at.is_(None)
+        ).offset(skip).limit(limit).all()
+
+    def create(self, obj_in: dict) -> ModelType:
+        """Create new record"""
+        db_obj = self.model(**obj_in)
+        self.db.add(db_obj)
+        self.db.commit()
+        self.db.refresh(db_obj)
+        return db_obj
+
+    def update(self, id: str, obj_in: dict) -> Optional[ModelType]:
+        """Update existing record"""
+        db_obj = self.get_by_id(id)
+        if not db_obj:
+            return None
+
+        for field, value in obj_in.items():
+            setattr(db_obj, field, value)
+
+        self.db.commit()
+        self.db.refresh(db_obj)
+        return db_obj
+
+    def soft_delete(self, id: str) -> bool:
+        """Soft delete record"""
+        db_obj = self.get_by_id(id)
+        if not db_obj:
+            return False
+
+        db_obj.deleted_at = datetime.utcnow()
+        self.db.commit()
+        return True
+
+    def apply_filters(self, query, filters: dict):
+        """Apply dynamic filters to query"""
+        for key, value in filters.items():
+            if hasattr(self.model, key) and value is not None:
+                query = query.filter(getattr(self.model, key) == value)
+        return query
+```
+
+**Specific Repository Example:**
+```python
+# app/repositories/ticket_repository.py
+from app.repositories.base_repository import BaseRepository
+from app.models.ticket import Ticket
+from sqlalchemy.orm import Session, joinedload
+
+class TicketRepository(BaseRepository[Ticket]):
+    def __init__(self, db: Session):
+        super().__init__(Ticket, db)
+
+    def get_with_relations(self, ticket_id: str):
+        """Get ticket with all related data (eager loading)"""
+        return self.db.query(Ticket).options(
+            joinedload(Ticket.customer),
+            joinedload(Ticket.project),
+            joinedload(Ticket.assignments),
+            joinedload(Ticket.expenses)
+        ).filter(
+            Ticket.id == ticket_id,
+            Ticket.deleted_at.is_(None)
+        ).first()
+
+    def get_by_project(self, project_id: str, status: Optional[str] = None):
+        """Get tickets by project with optional status filter"""
+        query = self.db.query(Ticket).filter(
+            Ticket.project_id == project_id,
+            Ticket.deleted_at.is_(None)
+        )
+
+        if status:
+            query = query.filter(Ticket.status == status)
+
+        return query.all()
+
+    def get_overdue_tickets(self):
+        """Get tickets past SLA deadline"""
+        return self.db.query(Ticket).filter(
+            Ticket.status.in_(['open', 'assigned', 'in_progress']),
+            Ticket.sla_target_date < datetime.utcnow(),
+            Ticket.deleted_at.is_(None)
+        ).all()
+```
+
+---
+
+### Pattern 2: Service Layer Pattern (Business Logic)
+
+**Purpose:** Encapsulate business rules, orchestrate operations, manage transactions
+
+**Service Template:**
+```python
+# app/services/ticket_service.py
+from typing import Optional, List
+from sqlalchemy.orm import Session
+from app.repositories.ticket_repository import TicketRepository
+from app.repositories.customer_repository import CustomerRepository
+from app.schemas.ticket import TicketCreate, TicketUpdate, TicketResponse
+from app.core.exceptions import NotFoundException, BusinessRuleException
+from app.services.notification_service import NotificationService
+
+class TicketService:
+    def __init__(self, db: Session):
+        self.db = db
+        self.ticket_repo = TicketRepository(db)
+        self.customer_repo = CustomerRepository(db)
+        self.notification_service = NotificationService(db)
+
+    def create_ticket(self, ticket_data: TicketCreate, created_by_id: str) -> TicketResponse:
+        """
+        Create new ticket with business rule validation
+
+        Business Rules:
+        1. Customer must exist
+        2. Project must be active
+        3. No duplicate tickets for same source
+        4. Calculate SLA deadline based on priority
+        """
+        # Validate customer exists
+        customer = self.customer_repo.get_by_id(ticket_data.customer_id)
+        if not customer:
+            raise NotFoundException("Customer not found")
+
+        # Check for duplicate tickets
+        existing = self.ticket_repo.get_by_source(
+            ticket_data.source,
+            ticket_data.source_id
+        )
+        if existing:
+            raise BusinessRuleException("Ticket already exists for this source")
+
+        # Calculate SLA deadline
+        sla_hours = self._get_sla_hours(ticket_data.priority)
+        sla_target_date = datetime.utcnow() + timedelta(hours=sla_hours)
+
+        # Create ticket
+        ticket_dict = ticket_data.dict()
+        ticket_dict['sla_target_date'] = sla_target_date
+        ticket_dict['created_by_user_id'] = created_by_id
+
+        ticket = self.ticket_repo.create(ticket_dict)
+
+        # Send notification (async)
+        self.notification_service.notify_ticket_created(ticket.id)
+
+        return TicketResponse.from_orm(ticket)
+
+    def assign_ticket(
+        self,
+        ticket_id: str,
+        agent_id: str,
+        assigned_by_id: str
+    ) -> TicketResponse:
+        """
+        Assign ticket to field agent
+
+        Business Rules:
+        1. Ticket must be in 'open' status
+        2. Agent must be active and in same project
+        3. Agent cannot have more than 3 active tickets
+        4. Record assignment history
+        """
+        ticket = self.ticket_repo.get_by_id(ticket_id)
+        if not ticket:
+            raise NotFoundException("Ticket not found")
+
+        if ticket.status != 'open':
+            raise BusinessRuleException("Ticket must be in 'open' status to assign")
+
+        # Check agent workload
+        active_tickets = self.ticket_repo.get_active_tickets_for_agent(agent_id)
+        if len(active_tickets) >= 3:
+            raise BusinessRuleException("Agent already has 3 active tickets")
+
+        # Update ticket status
+        ticket = self.ticket_repo.update(ticket_id, {
+            'status': 'assigned',
+            'assigned_agent_id': agent_id
+        })
+
+        # Create assignment record
+        self._create_assignment_record(ticket_id, agent_id, assigned_by_id)
+
+        # Send notification to agent
+        self.notification_service.notify_ticket_assigned(ticket_id, agent_id)
+
+        return TicketResponse.from_orm(ticket)
+
+    def _get_sla_hours(self, priority: str) -> int:
+        """Calculate SLA hours based on priority"""
+        sla_map = {
+            'urgent': 24,
+            'high': 48,
+            'normal': 72,
+            'low': 168  # 7 days
+        }
+        return sla_map.get(priority, 72)
+```
+
+---
+
+### Pattern 3: API Endpoint Pattern (Thin Controllers)
+
+**Purpose:** Handle HTTP concerns, validate input, format responses
+
+**Endpoint Template:**
+```python
+# app/api/v1/tickets.py
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from typing import List
+
+from app.api.deps import get_db, get_current_user
+from app.schemas.ticket import TicketCreate, TicketUpdate, TicketResponse
+from app.schemas.common import PaginatedResponse
+from app.services.ticket_service import TicketService
+from app.core.exceptions import NotFoundException, BusinessRuleException
+from app.models.user import User
+
+router = APIRouter(prefix="/tickets", tags=["tickets"])
+
+@router.post("/", response_model=TicketResponse, status_code=status.HTTP_201_CREATED)
+def create_ticket(
+    ticket_data: TicketCreate,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Create new ticket
+
+    Permissions: project_manager, dispatcher
+    """
+    try:
+        service = TicketService(db)
+        return service.create_ticket(ticket_data, current_user.id)
+    except NotFoundException as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except BusinessRuleException as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+@router.get("/{ticket_id}", response_model=TicketResponse)
+def get_ticket(
+    ticket_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """Get ticket by ID"""
+    service = TicketService(db)
+    ticket = service.get_ticket(ticket_id)
+
+    if not ticket:
+        raise HTTPException(status_code=404, detail="Ticket not found")
+
+    return ticket
+
+@router.get("/", response_model=PaginatedResponse[TicketResponse])
+def list_tickets(
+    project_id: Optional[str] = None,
+    status: Optional[str] = None,
+    skip: int = 0,
+    limit: int = 100,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    List tickets with filters
+
+    Filters:
+    - project_id: Filter by project
+    - status: Filter by status
+    - skip: Pagination offset
+    - limit: Page size
+    """
+    service = TicketService(db)
+    tickets, total = service.list_tickets(
+        project_id=project_id,
+        status=status,
+        skip=skip,
+        limit=limit
+    )
+
+    return PaginatedResponse(
+        items=tickets,
+        total=total,
+        skip=skip,
+        limit=limit
+    )
+
+@router.post("/{ticket_id}/assign", response_model=TicketResponse)
+def assign_ticket(
+    ticket_id: str,
+    agent_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Assign ticket to field agent
+
+    Permissions: dispatcher, project_manager
+    """
+    try:
+        service = TicketService(db)
+        return service.assign_ticket(ticket_id, agent_id, current_user.id)
+    except NotFoundException as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except BusinessRuleException as e:
+        raise HTTPException(status_code=400, detail=str(e))
+```
+
+---
+
+### Pattern 4: Dependency Injection
+
+**Purpose:** Manage dependencies, enable testing, improve maintainability
+
+```python
+# app/api/deps.py
+from typing import Generator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.orm import Session
+
+from app.core.database import SessionLocal
+from app.core.auth import verify_token
+from app.models.user import User
+from app.repositories.user_repository import UserRepository
+
+security = HTTPBearer()
+
+def get_db() -> Generator:
+    """Database session dependency"""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    db: Session = Depends(get_db)
+) -> User:
+    """Get current authenticated user"""
+    token = credentials.credentials
+
+    try:
+        payload = verify_token(token)
+        user_id = payload.get("sub")
+
+        if not user_id:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid authentication credentials"
+            )
+
+        user_repo = UserRepository(db)
+        user = user_repo.get_by_id(user_id)
+
+        if not user or not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found or inactive"
+            )
+
+        return user
+
+    except Exception:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials"
+        )
+
+def require_role(*allowed_roles: str):
+    """Role-based access control decorator"""
+    def role_checker(current_user: User = Depends(get_current_user)) -> User:
+        if current_user.role not in allowed_roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Access denied. Required roles: {', '.join(allowed_roles)}"
+            )
+        return current_user
+    return role_checker
+```
+
+---
+
+### Pattern 5: Error Handling
+
+**Purpose:** Consistent error responses, proper logging
+
+```python
+# app/core/exceptions.py
+class AppException(Exception):
+    """Base application exception"""
+    def __init__(self, message: str, code: str = None):
+        self.message = message
+        self.code = code
+        super().__init__(self.message)
+
+class NotFoundException(AppException):
+    """Resource not found"""
+    pass
+
+class BusinessRuleException(AppException):
+    """Business rule violation"""
+    pass
+
+class ValidationException(AppException):
+    """Data validation error"""
+    pass
+
+class AuthenticationException(AppException):
+    """Authentication failure"""
+    pass
+
+class AuthorizationException(AppException):
+    """Authorization failure"""
+    pass
+
+# app/middleware/error_handling.py
+from fastapi import Request, status
+from fastapi.responses import JSONResponse
+from app.core.exceptions import (
+    AppException,
+    NotFoundException,
+    BusinessRuleException,
+    ValidationException
+)
+import logging
+
+logger = logging.getLogger(__name__)
+
+async def error_handler_middleware(request: Request, call_next):
+    try:
+        return await call_next(request)
+    except NotFoundException as e:
+        logger.warning(f"Not found: {e.message}")
+        return JSONResponse(
+            status_code=status.HTTP_404_NOT_FOUND,
+            content={"detail": e.message, "code": e.code}
+        )
+    except BusinessRuleException as e:
+        logger.warning(f"Business rule violation: {e.message}")
+        return JSONResponse(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            content={"detail": e.message, "code": e.code}
+        )
+    except ValidationException as e:
+        logger.warning(f"Validation error: {e.message}")
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={"detail": e.message, "code": e.code}
+        )
+    except Exception as e:
+        logger.error(f"Unhandled exception: {str(e)}", exc_info=True)
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={"detail": "Internal server error"}
+        )
+```
+
+---
+
+### Pattern 6: Caching Strategy
+
+**Purpose:** Improve performance, reduce database load
+
+```python
+# app/utils/cache.py
+from typing import Optional, Any, Callable
+from functools import wraps
+import json
+import redis
+from app.config import settings
+
+redis_client = redis.from_url(settings.REDIS_URL)
+
+def cache_get(key: str) -> Optional[Any]:
+    """Get value from cache"""
+    value = redis_client.get(key)
+    return json.loads(value) if value else None
+
+def cache_set(key: str, value: Any, ttl: int = 300):
+    """Set value in cache with TTL"""
+    redis_client.setex(key, ttl, json.dumps(value))
+
+def cache_delete(key: str):
+    """Delete key from cache"""
+    redis_client.delete(key)
+
+def cache_delete_pattern(pattern: str):
+    """Delete all keys matching pattern"""
+    keys = redis_client.keys(pattern)
+    if keys:
+        redis_client.delete(*keys)
+
+def cached(ttl: int = 300, key_prefix: str = ""):
+    """Decorator for caching function results"""
+    def decorator(func: Callable):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = f"{key_prefix}:{func.__name__}:{str(args)}:{str(kwargs)}"
+
+            # Try to get from cache
+            cached_value = cache_get(cache_key)
+            if cached_value is not None:
+                return cached_value
+
+            # Execute function
+            result = func(*args, **kwargs)
+
+            # Store in cache
+            cache_set(cache_key, result, ttl)
+
+            return result
+        return wrapper
+    return decorator
+
+# Usage example
+@cached(ttl=300, key_prefix="dashboard")
+def get_dashboard_metrics(project_id: str):
+    # Expensive database query
+    return compute_metrics(project_id)
+```
+
+---
+
+### Pattern 7: Background Tasks (Celery)
+
+**Purpose:** Async processing, scheduled jobs
+
+```python
+# app/tasks/celery_app.py
+from celery import Celery
+from celery.schedules import crontab
+from app.config import settings
+
+celery_app = Celery(
+    "swiftops",
+    broker=settings.CELERY_BROKER_URL,
+    backend=settings.CELERY_RESULT_BACKEND
+)
+
+celery_app.conf.update(
+    task_serializer='json',
+    accept_content=['json'],
+    result_serializer='json',
+    timezone='UTC',
+    enable_utc=True,
+    task_track_started=True,
+    task_time_limit=30 * 60,  # 30 minutes
+    task_soft_time_limit=25 * 60,  # 25 minutes
+)
+
+# Task routing
+celery_app.conf.task_routes = {
+    'app.tasks.notification_tasks.*': {'queue': 'high_priority'},
+    'app.tasks.payment_tasks.*': {'queue': 'high_priority'},
+    'app.tasks.report_tasks.*': {'queue': 'medium_priority'},
+    'app.tasks.analytics_tasks.*': {'queue': 'low_priority'},
+}
+
+# Scheduled tasks
+celery_app.conf.beat_schedule = {
+    'generate-weekly-payroll': {
+        'task': 'app.tasks.payroll_tasks.generate_weekly_payroll',
+        'schedule': crontab(day_of_week=5, hour=18, minute=0),
+    },
+    'monitor-sla-violations': {
+        'task': 'app.tasks.sla_tasks.check_sla_violations',
+        'schedule': crontab(minute=0),  # Every hour
+    },
+    'cleanup-old-exports': {
+        'task': 'app.tasks.cleanup_tasks.cleanup_old_exports',
+        'schedule': crontab(hour=2, minute=0),  # 2 AM daily
+    },
+}
+
+# app/tasks/notification_tasks.py
+from app.tasks.celery_app import celery_app
+from app.integrations.resend import send_email
+from app.core.database import SessionLocal
+
+@celery_app.task(bind=True, max_retries=3)
+def send_ticket_assignment_email(self, ticket_id: str, agent_id: str):
+    """Send email notification for ticket assignment"""
+    try:
+        db = SessionLocal()
+
+        # Get ticket and agent details
+        ticket = db.query(Ticket).filter(Ticket.id == ticket_id).first()
+        agent = db.query(User).filter(User.id == agent_id).first()
+
+        # Send email
+        send_email(
+            to=agent.email,
+            subject=f"New Ticket Assigned: {ticket.ticket_name}",
+            template="ticket_assignment",
+            variables={
+                "agent_name": agent.name,
+                "ticket_id": ticket.id,
+                "customer_name": ticket.customer.customer_name,
+                "address": ticket.location_address
+            }
+        )
+
+        db.close()
+    except Exception as e:
+        # Retry with exponential backoff
+        raise self.retry(exc=e, countdown=60 * (2 ** self.request.retries))
+```
+
+---
+
+## 🔨 Build Sequence (Complete Implementation Order)
+
+### Phase 1: Foundation (Week 1)
+**Goal:** Set up core infrastructure and base components
+
+#### Day 1-2: Project Setup
+- [ ] Initialize project structure (all folders)
+- [ ] Set up virtual environment
+- [ ] Install dependencies (requirements.txt)
+- [ ] Configure environment variables (.env)
+- [ ] Set up Docker Compose (PostgreSQL, Redis)
+- [ ] Initialize Alembic for migrations
+- [ ] Set up pre-commit hooks (black, isort, flake8)
+
+#### Day 3-4: Core Components
+- [ ] `app/core/database.py` - Database session management
+- [ ] `app/core/logging.py` - Structured logging
+- [ ] `app/core/exceptions.py` - Custom exceptions
+- [ ] `app/config.py` - Configuration management
+- [ ] `app/models/base.py` - Base model with common fields
+- [ ] `app/models/enums.py` - All ENUM types
+- [ ] `app/schemas/base.py` - Base Pydantic schemas
+- [ ] `app/schemas/common.py` - Common schemas (pagination, filters)
+
+#### Day 5-7: Authentication & Authorization
+- [ ] `app/core/auth.py` - JWT token management
+- [ ] `app/core/security.py` - Password hashing
+- [ ] `app/core/permissions.py` - RBAC definitions
+- [ ] `app/integrations/supabase.py` - Supabase client
+- [ ] `app/services/auth_service.py` - Auth business logic
+- [ ] `app/api/deps.py` - Auth dependencies
+- [ ] `app/api/v1/auth.py` - Auth endpoints
+- [ ] `app/middleware/authentication.py` - Auth middleware
+- [ ] Test authentication flow
+
+---
+
+### Phase 2: Core Domain Models (Week 2)
+**Goal:** Implement all database models and migrations
+
+#### Day 1-2: User & Organization Models
+- [ ] `app/models/user.py` - Users, UserFinancialAccounts, UserAssetAssignments, UserPreferences
+- [ ] `app/models/organization.py` - Clients, Contractors
+- [ ] Create Alembic migration for users and organizations
+- [ ] Test models with sample data
+
+#### Day 3-4: Project & Team Models
+- [ ] `app/models/project.py` - Projects, ProjectTeam, ProjectRoles, ProjectRegions, ProjectSubcontractors
+- [ ] Create Alembic migration for projects
+- [ ] Test project relationships
+
+#### Day 5-7: Ticket & Customer Models
+- [ ] `app/models/ticket.py` - Tickets, TicketAssignments, TicketStatusHistory, TicketExpenses
+- [ ] `app/models/customer.py` - Customers, SalesOrders, Subscriptions
+- [ ] `app/models/incident.py` - Incidents
+- [ ] `app/models/inventory.py` - ProjectInventory, InventoryAssignments, InventoryTransactions
+- [ ] `app/models/finance.py` - ProjectFinance, UserPayroll, PaymentLogs
+- [ ] `app/models/timesheet.py` - Timesheets
+- [ ] `app/models/document.py` - Documents, DocumentVersions
+- [ ] `app/models/media.py` - MediaFiles
+- [ ] `app/models/audit_log.py` - AuditLogs
+- [ ] Create migrations for all remaining models
+- [ ] Run full migration: `alembic upgrade head`
+
+---
+
+### Phase 3: Repository Layer (Week 3)
+**Goal:** Implement data access layer for all domains
+
+#### Day 1-2: Base Repository & Core Repositories
+- [ ] `app/repositories/base_repository.py` - Generic base repository
+- [ ] `app/repositories/user_repository.py` - User data access
+- [ ] `app/repositories/organization_repository.py` - Client/Contractor data access
+- [ ] Test repositories with unit tests
+
+#### Day 3-4: Project & Ticket Repositories
+- [ ] `app/repositories/project_repository.py` - Project data access
+- [ ] `app/repositories/ticket_repository.py` - Ticket data access
+- [ ] `app/repositories/assignment_repository.py` - Assignment data access
+- [ ] Test complex queries (joins, filters)
+
+#### Day 5-7: Remaining Repositories
+- [ ] `app/repositories/customer_repository.py`
+- [ ] `app/repositories/sales_order_repository.py`
+- [ ] `app/repositories/subscription_repository.py`
+- [ ] `app/repositories/incident_repository.py`
+- [ ] `app/repositories/inventory_repository.py`
+- [ ] `app/repositories/expense_repository.py`
+- [ ] `app/repositories/payroll_repository.py`
+- [ ] `app/repositories/timesheet_repository.py`
+- [ ] `app/repositories/document_repository.py`
+- [ ] `app/repositories/audit_log_repository.py`
+- [ ] Write unit tests for all repositories
+
+---
+
+### Phase 4: Pydantic Schemas (Week 4)
+**Goal:** Define all request/response schemas
+
+#### Day 1-3: Core Domain Schemas
+- [ ] `app/schemas/user.py` - UserCreate, UserUpdate, UserResponse
+- [ ] `app/schemas/organization.py` - Client/Contractor schemas
+- [ ] `app/schemas/project.py` - Project schemas
+- [ ] `app/schemas/ticket.py` - Ticket schemas
+- [ ] `app/schemas/assignment.py` - Assignment schemas
+- [ ] Test schema validation
+
+#### Day 4-7: Remaining Domain Schemas
+- [ ] `app/schemas/customer.py`
+- [ ] `app/schemas/sales_order.py`
+- [ ] `app/schemas/subscription.py`
+- [ ] `app/schemas/incident.py`
+- [ ] `app/schemas/inventory.py`
+- [ ] `app/schemas/expense.py`
+- [ ] `app/schemas/payroll.py`
+- [ ] `app/schemas/timesheet.py`
+- [ ] `app/schemas/document.py`
+- [ ] `app/schemas/media.py`
+- [ ] `app/schemas/report.py`
+- [ ] Test all schemas with edge cases
+
+---
+
+### Phase 5: Service Layer - Core Domains (Week 5-6)
+**Goal:** Implement business logic for core domains
+
+#### Week 5: User, Organization, Project Services
+- [ ] `app/services/user_service.py`
+  - User CRUD operations
+  - Profile management
+  - Financial account management
+  - Asset assignment
+- [ ] `app/services/organization_service.py`
+  - Client/Contractor CRUD
+  - Organization activation
+- [ ] `app/services/project_service.py`
+  - Project lifecycle management
+  - Team assignment
+  - Regional hub management
+  - Subcontractor management
+- [ ] Write unit tests for services
+
+#### Week 6: Ticket & Assignment Services
+- [ ] `app/services/ticket_service.py`
+  - Ticket creation from sales orders, incidents, tasks
+  - Status transitions
+  - SLA tracking
+  - Expense logging
+- [ ] `app/services/assignment_service.py`
+  - Manual assignment
+  - Self-assignment (max 3 tickets rule)
+  - Assignment validation
+  - GPS verification
+- [ ] Write comprehensive tests for ticket workflows
+
+---
+
+### Phase 6: Service Layer - Customer & Sales (Week 7)
+**Goal:** Implement customer and sales management
+
+#### Day 1-3: Customer & Sales Order Services
+- [ ] `app/services/customer_service.py`
+  - Customer CRUD
+  - Deduplication by phone
+  - Address management
+- [ ] `app/services/sales_order_service.py`
+  - Sales order creation
+  - CSV import processing
+  - Ticket generation
+  - Order validation
+
+#### Day 4-7: Subscription & Incident Services
+- [ ] `app/services/subscription_service.py`
+  - Subscription activation
+  - Equipment tracking
+  - Service lifecycle
+- [ ] `app/services/incident_service.py`
+  - Incident creation
+  - Ticket generation
+  - Resolution tracking
+- [ ] Write integration tests
+
+---
+
+### Phase 7: Service Layer - Operations (Week 8)
+**Goal:** Implement operational services
+
+#### Day 1-3: Inventory & Expense Services
+- [ ] `app/services/inventory_service.py`
+  - Stock management
+  - Equipment issuance
+  - Return tracking
+  - Low stock alerts
+- [ ] `app/services/expense_service.py`
+  - Expense logging
+  - Approval workflow
+  - Receipt management
+
+#### Day 4-7: Payroll & Timesheet Services
+- [ ] `app/services/payroll_service.py`
+  - Payroll calculation (commission, flat rate, hybrid)
+  - Payment queue management
+  - Payroll reports
+- [ ] `app/services/timesheet_service.py`
+  - Attendance tracking
+  - Check-in/check-out
+  - Leave management
+- [ ] Write tests for financial calculations
+
+---
+
+### Phase 8: API Endpoints - Core (Week 9)
+**Goal:** Implement REST API endpoints
+
+#### Day 1-2: User & Organization Endpoints
+- [ ] `app/api/v1/users.py` - User management endpoints
+- [ ] `app/api/v1/organizations.py` - Client/Contractor endpoints
+- [ ] Test with Postman/HTTPie
+
+#### Day 3-4: Project Endpoints
+- [ ] `app/api/v1/projects.py` - Project CRUD endpoints
+- [ ] Test project workflows
+
+#### Day 5-7: Ticket & Assignment Endpoints
+- [ ] `app/api/v1/tickets.py` - Ticket management endpoints
+- [ ] `app/api/v1/assignments.py` - Assignment endpoints
+- [ ] Test ticket lifecycle
+- [ ] Test assignment rules
+
+---
+
+### Phase 9: API Endpoints - Customer & Sales (Week 10)
+**Goal:** Implement customer and sales endpoints
+
+#### Day 1-3: Customer & Sales Order Endpoints
+- [ ] `app/api/v1/customers.py` - Customer endpoints
+- [ ] `app/api/v1/sales_orders.py` - Sales order endpoints
+- [ ] CSV import endpoint
+- [ ] Test CSV import with sample files
+
+#### Day 4-7: Subscription & Incident Endpoints
+- [ ] `app/api/v1/subscriptions.py` - Subscription endpoints
+- [ ] `app/api/v1/incidents.py` - Incident endpoints
+- [ ] Test end-to-end workflows
+
+---
+
+### Phase 10: API Endpoints - Operations (Week 11)
+**Goal:** Implement operational endpoints
+
+#### Day 1-3: Inventory & Expense Endpoints
+- [ ] `app/api/v1/inventory.py` - Inventory endpoints
+- [ ] `app/api/v1/expenses.py` - Expense endpoints
+- [ ] Test inventory workflows
+
+#### Day 4-7: Payroll & Timesheet Endpoints
+- [ ] `app/api/v1/payroll.py` - Payroll endpoints
+- [ ] `app/api/v1/timesheets.py` - Timesheet endpoints
+- [ ] Test payroll generation
+
+---
+
+### Phase 11: External Integrations (Week 12)
+**Goal:** Integrate external services
+
+#### Day 1-2: Media & Document Services
+- [ ] `app/integrations/cloudinary.py` - Image upload integration
+- [ ] `app/services/media_service.py` - Photo management
+- [ ] `app/services/document_service.py` - Document handling
+- [ ] `app/api/v1/media.py` - Media endpoints
+- [ ] `app/api/v1/documents.py` - Document endpoints
+- [ ] Test file uploads
+
+#### Day 3-4: Email & Notification Services
+- [ ] `app/integrations/resend.py` - Email service
+- [ ] `app/services/notification_service.py` - Notification orchestration
+- [ ] Email templates (OTP, ticket assignment, payroll)
+- [ ] Test email sending
+
+#### Day 5-7: Payment Integration
+- [ ] `app/integrations/mpesa.py` - M-Pesa integration
+- [ ] `app/services/payment_service.py` - Payment processing
+- [ ] `app/api/v1/webhooks.py` - Payment webhooks
+- [ ] Test payment flow (sandbox)
+
+---
+
+### Phase 12: Background Tasks (Week 13)
+**Goal:** Implement async processing
+
+#### Day 1-3: Celery Setup & Core Tasks
+- [ ] `app/tasks/celery_app.py` - Celery configuration
+- [ ] `app/tasks/notification_tasks.py` - Email/SMS tasks
+- [ ] `app/tasks/payment_tasks.py` - Payment processing tasks
+- [ ] Test task execution
+
+#### Day 4-7: Scheduled Tasks
+- [ ] `app/tasks/payroll_tasks.py` - Weekly payroll generation
+- [ ] `app/tasks/sla_tasks.py` - SLA monitoring
+- [ ] `app/tasks/cleanup_tasks.py` - Data cleanup
+- [ ] `app/tasks/analytics_tasks.py` - Analytics computation
+- [ ] Configure Celery Beat schedule
+- [ ] Test scheduled tasks
+
+---
+
+### Phase 13: Reporting & Analytics (Week 14)
+**Goal:** Implement reporting features
+
+#### Day 1-3: CSV Export
+- [ ] `app/services/csv_export_service.py` - CSV export logic
+- [ ] `app/tasks/export_tasks.py` - Async export generation
+- [ ] `app/api/v1/reports.py` - Report endpoints
+- [ ] Test CSV export
+
+#### Day 4-7: Analytics & Dashboards
+- [ ] `app/services/analytics_service.py` - Analytics computation
+- [ ] `app/api/v1/analytics.py` - Analytics endpoints
+- [ ] Dashboard metrics calculation
+- [ ] Performance reports
+- [ ] Test analytics queries
+
+---
+
+### Phase 14: Advanced Features (Week 15)
+**Goal:** Implement V2 features
+
+#### Day 1-3: OTP & 2FA
+- [ ] `app/services/otp_service.py` - OTP generation/verification
+- [ ] OTP endpoints
+- [ ] Test OTP flow
+
+#### Day 4-7: Search & Filtering
+- [ ] `app/utils/filters.py` - Query filter builders
+- [ ] Full-text search implementation
+- [ ] Autocomplete endpoints
+- [ ] Test search functionality
+
+---
+
+### Phase 15: Middleware & Security (Week 16)
+**Goal:** Implement security features
+
+#### Day 1-2: Middleware
+- [ ] `app/middleware/rate_limiting.py` - Rate limiter
+- [ ] `app/middleware/request_logging.py` - Request logging
+- [ ] `app/middleware/error_handling.py` - Global error handler
+- [ ] `app/middleware/cors.py` - CORS configuration
+
+#### Day 3-4: Security Features
+- [ ] Input validation and sanitization
+- [ ] Audit logging
+- [ ] Data encryption for sensitive fields
+- [ ] Test security measures
+
+#### Day 5-7: Monitoring & Health Checks
+- [ ] `app/api/v1/health.py` - Health check endpoints
+- [ ] `app/integrations/sentry.py` - Error tracking
+- [ ] Logging configuration
+- [ ] Test monitoring
+
+---
+
+### Phase 16: Testing & Quality (Week 17-18)
+**Goal:** Comprehensive testing and code quality
+
+#### Week 17: Unit & Integration Tests
+- [ ] Write unit tests for all services (80% coverage)
+- [ ] Write integration tests for API endpoints
+- [ ] Write repository tests
+- [ ] Test edge cases and error handling
+
+#### Week 18: End-to-End Tests
+- [ ] Test complete workflows (sales order → ticket → completion)
+- [ ] Test payment flows
+- [ ] Test CSV import/export
+- [ ] Load testing with realistic data
+- [ ] Fix bugs and optimize
+
+---
+
+### Phase 17: Documentation (Week 19)
+**Goal:** Complete documentation
+
+#### Day 1-3: API Documentation
+- [ ] OpenAPI/Swagger documentation
+- [ ] Endpoint descriptions
+- [ ] Request/response examples
+- [ ] Authentication guide
+
+#### Day 4-7: Developer Documentation
+- [ ] Setup guide
+- [ ] Architecture documentation
+- [ ] Deployment guide
+- [ ] Troubleshooting guide
+- [ ] Contributing guidelines
+
+---
+
+### Phase 18: Deployment & DevOps (Week 20)
+**Goal:** Production deployment
+
+#### Day 1-3: Docker & CI/CD
+- [ ] Optimize Dockerfile
+- [ ] Docker Compose for production
+- [ ] CI/CD pipeline (GitHub Actions)
+- [ ] Automated testing in CI
+
+#### Day 4-7: Production Deployment
+- [ ] Deploy to production environment
+- [ ] Configure environment variables
+- [ ] Set up monitoring (Sentry)
+- [ ] Set up logging (CloudWatch/ELK)
+- [ ] Database backups
+- [ ] SSL certificates
+- [ ] Load balancer configuration
+- [ ] Final production testing
+
+---
+
+
+## 🎯 Critical Missing Components
+
+After reviewing the build plan against the backend features document, here are the **missing components** that need to be added:
+
+---
+
+### Missing Feature 1: CSV Import Service (Phase 6 Addition)
+
+**Location:** Should be in Phase 6 (Week 7) alongside Sales Order Service
+
+**Components to Add:**
+```
+- [ ] `app/services/csv_import_service.py`
+  - CSV parsing and validation
+  - Batch processing (chunks of 100)
+  - Error reporting
+  - Preview generation
+  - Deduplication logic
+- [ ] `app/tasks/import_tasks.py`
+  - Async CSV processing
+  - Progress tracking
+  - Import status updates
+- [ ] CSV import endpoints in `app/api/v1/sales_orders.py`
+  - POST /sales-orders/upload-csv
+  - POST /sales-orders/validate-csv
+  - POST /sales-orders/confirm-csv-import
+  - GET /sales-orders/import/{import_id}/status
+```
+
+---
+
+### Missing Feature 2: Google Maps Integration (Phase 11 Addition)
+
+**Location:** Should be in Phase 11 (Week 12) with other integrations
+
+**Components to Add:**
+```
+- [ ] `app/integrations/google_maps.py`
+  - Geocoding (address → coordinates)
+  - Reverse geocoding (coordinates → address)
+  - Distance calculation
+  - Directions API
+  - Travel time estimation
+- [ ] `app/utils/location_utils.py`
+  - GPS distance calculation
+  - Location validation
+  - Geofence checking
+  - Proximity detection
+- [ ] Location endpoints
+  - GET /tickets/{ticket_id}/route
+  - GET /tickets/{ticket_id}/verify-location
+  - POST /tickets/{ticket_id}/location-update
+```
+
+---
+
+### Missing Feature 3: Caching Layer (Phase 15 Addition)
+
+**Location:** Should be in Phase 15 (Week 16) with middleware
+
+**Components to Add:**
+```
+- [ ] `app/utils/cache.py`
+  - Redis caching utilities
+  - Cache decorators
+  - Cache invalidation patterns
+  - Multi-level caching
+- [ ] Implement caching for:
+  - User sessions (TTL: 24 hours)
+  - Dashboard metrics (TTL: 5 minutes)
+  - Project settings (TTL: 1 hour)
+  - Agent locations (TTL: 1 minute)
+  - SLA thresholds (TTL: 1 hour)
+- [ ] Cache invalidation triggers
+  - On data updates
+  - Pattern-based invalidation
+```
+
+---
+
+### Missing Feature 4: Distributed Locks (Phase 15 Addition)
+
+**Location:** Should be in Phase 15 (Week 16) with security
+
+**Components to Add:**
+```
+- [ ] `app/utils/distributed_lock.py`
+  - Redis-based distributed locks
+  - Lock acquisition with timeout
+  - Auto-release on timeout
+  - Deadlock prevention
+- [ ] Apply locks to:
+  - Payroll processing
+  - Payment processing
+  - Inventory updates
+  - Concurrent ticket assignments
+```
+
+---
+
+### Missing Feature 5: Audit Logging (Phase 15 Addition)
+
+**Location:** Should be in Phase 15 (Week 16) with security
+
+**Components to Add:**
+```
+- [ ] `app/services/audit_service.py`
+  - Audit log creation
+  - Change tracking
+  - User action logging
+- [ ] Audit logging for:
+  - Financial operations (payments, payroll)
+  - Security operations (login, role changes)
+  - Data operations (deletions, bulk updates)
+  - Configuration changes
+- [ ] Audit log endpoints
+  - GET /audit-logs
+  - GET /audit-logs/user/{user_id}
+  - GET /audit-logs/entity/{entity_type}/{entity_id}
+```
+
+---
+
+### Missing Feature 6: WebSocket Support (New Phase 19)
+
+**Location:** New phase for real-time features
+
+**Components to Add:**
+```
+- [ ] `app/api/websockets/`
+  - location.py - Real-time location tracking
+  - notifications.py - Real-time notifications
+- [ ] WebSocket connection management
+- [ ] Location broadcast to dispatchers
+- [ ] Notification push to users
+- [ ] Connection authentication
+- [ ] Heartbeat/keepalive
+```
+
+---
+
+### Missing Feature 7: Data Validation & Sanitization (Phase 4 Addition)
+
+**Location:** Should be in Phase 4 (Week 4) with schemas
+
+**Components to Add:**
+```
+- [ ] `app/utils/validators.py`
+  - Phone number validation (Kenya format)
+  - Email validation
+  - GPS coordinate validation
+  - Serial number validation
+  - Custom business rule validators
+- [ ] `app/utils/sanitizers.py`
+  - HTML sanitization (prevent XSS)
+  - SQL injection prevention
+  - File upload validation
+  - Input normalization
+```
+
+---
+
+### Missing Feature 8: Pagination & Filtering Utilities (Phase 4 Addition)
+
+**Location:** Should be in Phase 4 (Week 4) with schemas
+
+**Components to Add:**
+```
+- [ ] `app/utils/pagination.py`
+  - Pagination helper functions
+  - Cursor-based pagination
+  - Offset-based pagination
+- [ ] `app/utils/filters.py`
+  - Dynamic filter builder
+  - Query parameter parsing
+  - Filter validation
+  - Sort parameter handling
+```
+
+---
+
+### Missing Feature 9: SMS Integration (V2 - New Phase 21)
+
+**Location:** New phase for V2 features
+
+**Components to Add:**
+```
+- [ ] `app/integrations/africastalking.py`
+  - SMS sending
+  - Bulk SMS
+  - Delivery status tracking
+- [ ] SMS use cases:
+  - OTP codes
+  - Urgent ticket assignments
+  - SLA violation alerts
+  - Payment confirmations
+- [ ] SMS endpoints
+  - POST /communications/sms/send
+  - POST /communications/sms/bulk
+  - GET /communications/sms/{sms_id}/status
+```
+
+---
+
+### Missing Feature 10: Agent Allocation Service (V2 - New Phase 21)
+
+**Location:** New phase for V2 features
+
+**Components to Add:**
+```
+- [ ] `app/services/allocation_service.py`
+  - Intelligent agent allocation algorithm
+  - Workload balancing
+  - Skill matching
+  - Distance-based assignment
+  - Availability checking
+- [ ] `app/services/route_optimization_service.py`
+  - Route optimization for multiple tickets
+  - Travel time calculation
+  - Optimal sequence determination
+- [ ] Allocation endpoints
+  - POST /tickets/{ticket_id}/auto-assign
+  - POST /tickets/bulk-auto-assign
+  - GET /agents/available
+  - GET /agents/nearest
+```
+
+---
+
+### Missing Feature 11: Health Checks & Monitoring (V2 - New Phase 21)
+
+**Location:** New phase for V2 features
+
+**Components to Add:**
+```
+- [ ] Health check endpoints
+  - GET /health
+  - GET /health/database
+  - GET /health/redis
+  - GET /health/celery
+  - GET /health/external-services
+- [ ] Usage monitoring
+  - API request tracking
+  - Response time monitoring
+  - Error rate tracking
+  - Resource usage monitoring
+- [ ] Infrastructure monitoring
+  - Database performance
+  - Redis memory usage
+  - Celery queue lengths
+  - External API quota tracking
+- [ ] Alerting system
+  - Critical alerts (email, SMS, Slack)
+  - Warning alerts
+  - Info notifications
+```
+
+---
+
+### Missing Feature 12: Data Encryption (Phase 15 Addition)
+
+**Location:** Should be in Phase 15 (Week 16) with security
+
+**Components to Add:**
+```
+- [ ] `app/utils/encryption.py`
+  - Field-level encryption
+  - Encryption key management
+  - Decrypt on read
+- [ ] Encrypt sensitive fields:
+  - Financial account numbers
+  - ID numbers
+  - Tax information
+  - Bank account numbers
+```
+
+---
+
+### Missing Feature 13: Rate Limiting Configuration (Phase 15 Addition)
+
+**Location:** Should be in Phase 15 (Week 16) with middleware
+
+**Components to Add:**
+```
+- [ ] Configure rate limits per endpoint:
+  - Auth endpoints: 5 requests/5 minutes
+  - OTP generation: 3 requests/5 minutes
+  - Standard API: 1000 requests/hour
+  - Search: 100 requests/minute
+  - Export: 10 requests/hour
+- [ ] Rate limit storage in Redis
+- [ ] Rate limit headers in responses
+- [ ] Rate limit exceeded error handling
+```
+
+---
+
+### Missing Feature 14: File Upload Validation (Phase 11 Addition)
+
+**Location:** Should be in Phase 11 (Week 12) with media service
+
+**Components to Add:**
+```
+- [ ] `app/utils/file_utils.py`
+  - File type validation
+  - File size validation
+  - Image dimension validation
+  - Malware scanning (optional)
+  - EXIF data extraction
+- [ ] Validation rules:
+  - Max file size: 10MB
+  - Allowed types: JPG, PNG, PDF
+  - Min image dimensions: 640x480
+```
+
+---
+
+### Missing Feature 15: Error Response Standardization (Phase 1 Addition)
+
+**Location:** Should be in Phase 1 (Week 1) with core components
+
+**Components to Add:**
+```
+- [ ] Standardized error response format:
+  {
+    "success": false,
+    "error": {
+      "code": "VALIDATION_ERROR",
+      "message": "Invalid input data",
+      "details": {...}
+    },
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+- [ ] Success response format:
+  {
+    "success": true,
+    "data": {...},
+    "message": "Operation completed successfully",
+    "timestamp": "2024-01-15T10:30:00Z"
+  }
+```
+
+---
+
+## 📋 Updated Implementation Phases
+
+### NEW Phase 19: WebSocket & Real-time Features (Week 21)
+**Goal:** Implement real-time communication
+
+#### Day 1-3: WebSocket Infrastructure
+- [ ] Set up WebSocket support in FastAPI
+- [ ] Connection management
+- [ ] Authentication for WebSocket connections
+- [ ] Heartbeat/keepalive mechanism
+
+#### Day 4-5: Location Tracking
+- [ ] Real-time location updates
+- [ ] Location broadcast to dispatchers
+- [ ] Journey tracking
+- [ ] GPS validation
+
+#### Day 6-7: Real-time Notifications
+- [ ] Push notifications via WebSocket
+- [ ] Notification queue management
+- [ ] Connection recovery
+- [ ] Test real-time features
+
+---
+
+### NEW Phase 20: Performance Optimization (Week 22)
+**Goal:** Optimize system performance
+
+#### Day 1-2: Database Optimization
+- [ ] Query optimization
+- [ ] Index analysis and creation
+- [ ] N+1 query elimination
+- [ ] Database connection pool tuning
+
+#### Day 3-4: Caching Optimization
+- [ ] Implement caching strategy
+- [ ] Cache warming
+- [ ] Cache invalidation testing
+- [ ] Cache hit rate monitoring
+
+#### Day 5-7: API Performance
+- [ ] Response time optimization
+- [ ] Payload size reduction
+- [ ] Compression configuration
+- [ ] Load testing and benchmarking
+
+---
+
+### NEW Phase 21: V2 Features (Week 23-24)
+**Goal:** Implement advanced features
+
+#### Week 23: SMS & Agent Allocation
+- [ ] Africa's Talking SMS integration
+- [ ] SMS notification templates
+- [ ] Intelligent agent allocation service
+- [ ] Route optimization service
+- [ ] Test allocation algorithms
+
+#### Week 24: Monitoring & Health Checks
+- [ ] Health check endpoints
+- [ ] Usage monitoring
+- [ ] Infrastructure monitoring
+- [ ] Alerting system
+- [ ] Dashboard for monitoring
+
+---
+
+## 🔍 Testing Strategy (Missing Section)
+
+### Unit Testing
+**Coverage Goal:** 80%+
+
+**What to Test:**
+- All service methods
+- All repository methods
+- All utility functions
+- Business rule validation
+- Error handling
+
+**Tools:**
+- pytest
+- pytest-cov (coverage)
+- pytest-mock (mocking)
+- faker (test data)
+
+### Integration Testing
+**What to Test:**
+- API endpoint workflows
+- Database transactions
+- External service integrations
+- Background task execution
+- Cache behavior
+
+### End-to-End Testing
+**What to Test:**
+- Complete user workflows
+- Sales order → ticket → completion
+- Payment processing
+- CSV import/export
+- Multi-user scenarios
+
+### Load Testing
+**What to Test:**
+- API response times under load
+- Database performance
+- Concurrent user handling
+- WebSocket connection limits
+
+**Tools:**
+- Locust
+- Apache JMeter
+- k6
+
+---
+
+## 🚀 Deployment Checklist (Expanded)
+
+### Pre-Deployment
+- [ ] All environment variables configured
+- [ ] Database migrations tested
+- [ ] Redis connection verified
+- [ ] Celery workers configured
+- [ ] External services tested (M-Pesa, Cloudinary, Resend)
+- [ ] SSL certificates configured
+- [ ] Monitoring setup (Sentry)
+- [ ] Backup strategy implemented
+- [ ] Load balancer configured
+- [ ] CDN configured (for static assets)
+- [ ] Rate limiting configured
+- [ ] CORS settings verified
+- [ ] Security headers configured
+- [ ] Database indexes created
+- [ ] Cache warming scripts ready
+
+### Post-Deployment
+- [ ] Health checks passing
+- [ ] API documentation accessible
+- [ ] Webhooks configured
+- [ ] Scheduled tasks running
+- [ ] Logs being collected
+- [ ] Alerts configured
+- [ ] Performance monitoring active
+- [ ] Database backups running
+- [ ] SSL certificate auto-renewal configured
+- [ ] Smoke tests passed
+- [ ] Load testing completed
+- [ ] Rollback plan documented
+- [ ] On-call rotation established
+
+---
+
+## 📊 Success Metrics (Expanded)
+
+### Technical Metrics
+- API response time < 200ms (p95)
+- Database query time < 50ms (p95)
+- Cache hit rate > 80%
+- Test coverage > 80%
+- Zero critical security vulnerabilities
+- 99.9% uptime
+- Error rate < 0.1%
+- Background job success rate > 99%
+
+### Business Metrics
+- Support 1000+ concurrent field agents
+- Process 10,000+ tickets per month
+- Handle 500+ payroll payments per week
+- 95% SLA compliance rate
+- < 1% payment failure rate
+- Average ticket completion time < 48 hours
+- Customer satisfaction > 4.5/5
+
+### Performance Benchmarks
+- Handle 1000 requests/second
+- Support 10,000 concurrent WebSocket connections
+- Process CSV with 10,000 rows in < 5 minutes
+- Generate payroll for 500 agents in < 10 minutes
+- Dashboard load time < 2 seconds
+
+---
+
+## 🔧 Maintenance & Operations (New Section)
+
+### Daily Operations
+- [ ] Monitor error rates
+- [ ] Check background job status
+- [ ] Review payment failures
+- [ ] Check SLA violations
+- [ ] Monitor API performance
+
+### Weekly Operations
+- [ ] Review logs for anomalies
+- [ ] Check database performance
+- [ ] Review security alerts
+- [ ] Update dependencies (security patches)
+- [ ] Backup verification
+
+### Monthly Operations
+- [ ] Performance review
+- [ ] Cost optimization review
+- [ ] Security audit
+- [ ] Dependency updates
+- [ ] Database maintenance (vacuum, analyze)
+- [ ] Archive old data
+
+### Quarterly Operations
+- [ ] Disaster recovery drill
+- [ ] Security penetration testing
+- [ ] Performance benchmarking
+- [ ] Infrastructure review
+- [ ] Documentation update
+
+---
+
+## 🎓 Knowledge Transfer (New Section)
+
+### Documentation to Create
+- [ ] API documentation (OpenAPI/Swagger)
+- [ ] Architecture diagrams
+- [ ] Database schema documentation
+- [ ] Deployment runbook
+- [ ] Troubleshooting guide
+- [ ] Incident response playbook
+- [ ] Onboarding guide for new developers
+- [ ] Code style guide
+- [ ] Git workflow guide
+
+### Training Materials
+- [ ] Video walkthrough of architecture
+- [ ] Code review guidelines
+- [ ] Testing best practices
+- [ ] Deployment procedures
+- [ ] Monitoring and alerting guide
+
+---
+
+## 🔐 Security Hardening Checklist (New Section)
+
+### Application Security
+- [ ] Input validation on all endpoints
+- [ ] SQL injection prevention (ORM usage)
+- [ ] XSS prevention (HTML sanitization)
+- [ ] CSRF protection
+- [ ] Rate limiting configured
+- [ ] Authentication on all protected endpoints
+- [ ] Authorization checks on all operations
+- [ ] Sensitive data encryption
+- [ ] Secure password hashing (bcrypt)
+- [ ] JWT token expiration configured
+
+### Infrastructure Security
+- [ ] HTTPS enforced
+- [ ] Security headers configured (HSTS, CSP, etc.)
+- [ ] Database access restricted (IP whitelist)
+- [ ] Redis access restricted
+- [ ] API keys rotated regularly
+- [ ] Secrets stored securely (not in code)
+- [ ] Firewall rules configured
+- [ ] DDoS protection enabled
+- [ ] Regular security updates
+
+### Compliance
+- [ ] GDPR compliance (data deletion, export)
+- [ ] Audit logging for sensitive operations
+- [ ] Data retention policies implemented
+- [ ] Privacy policy documented
+- [ ] Terms of service documented
+
+---
+
+## 📈 Scalability Roadmap (New Section)
+
+### Phase 1: Current (1-1000 users)
+- Single server deployment
+- Vertical scaling
+- Basic caching
+- Manual monitoring
+
+### Phase 2: Growth (1000-10,000 users)
+- Load balancer
+- Multiple API servers
+- Redis cluster
+- Database read replicas
+- CDN for static assets
+- Automated monitoring
+
+### Phase 3: Scale (10,000+ users)
+- Kubernetes orchestration
+- Auto-scaling
+- Database sharding
+- Message queue (RabbitMQ/Kafka)
+- Microservices architecture (if needed)
+- Advanced caching (Varnish)
+- Global CDN
+
+---
+
+## 🎯 Post-Launch Roadmap (New Section)
+
+### Month 1-3: Stabilization
+- Bug fixes based on user feedback
+- Performance optimization
+- Monitoring and alerting refinement
+- Documentation updates
+
+### Month 4-6: Feature Enhancements
+- SMS integration (Africa's Talking)
+- Intelligent agent allocation
+- Route optimization
+- Advanced analytics
+- Custom reports
+
+### Month 7-12: Advanced Features
+- Mobile app optimization
+- Offline mode improvements
+- AI-powered insights
+- Predictive analytics
+- Multi-language support
+- Customer portal
+
+---
+
+**Document Status:** Complete with all missing components identified and added  
+**Last Updated:** November 2025  
+**Next Review:** Before Phase 1 implementation begins

docs/dev/TEMPLATES_ARCHITECTURE.md

@@ -0,0 +1,265 @@
+# SwiftOps API - Templates Architecture
+
+## 🏗️ Architecture Overview
+
+Following FastAPI best practices, we've separated concerns into distinct layers:
+
+```
+src/app/
+├── templates/              # Jinja2 HTML templates
+│   ├── base.html          # Base template (layout)
+│   ├── index.html         # Landing page
+│   └── README.md          # Template documentation
+│
+├── static/                # Static assets
+│   ├── css/
+│   │   └── main.css      # Styles (theme-aware)
+│   └── js/
+│       └── main.js       # Client-side JavaScript
+│
+├── api/v1/
+│   ├── pages.py          # Page routes (HTML)
+│   ├── auth.py           # API routes (JSON)
+│   └── ...               # Other API routes
+│
+├── constants/
+│   └── app_metadata.py   # Centralized app config
+│
+└── main.py               # Application entry point
+```
+
+---
+
+## 📋 Design Principles
+
+### 1. **Separation of Concerns**
+- **Templates** (`templates/`) - HTML structure
+- **Styles** (`static/css/`) - Visual presentation
+- **Scripts** (`static/js/`) - Client behavior
+- **Routes** (`api/v1/pages.py`) - Page logic
+- **Config** (`constants/app_metadata.py`) - Metadata
+
+### 2. **Template Inheritance**
+```
+base.html (layout)
+    ↓
+index.html (content)
+    ↓
+Future pages extend base.html
+```
+
+### 3. **Static File Serving**
+```python
+# Mounted in main.py
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+# Used in templates
+<link rel="stylesheet" href="{{ url_for('static', path='/css/main.css') }}">
+```
+
+### 4. **Centralized Configuration**
+```python
+# constants/app_metadata.py
+APP_NAME = "SwiftOps API"
+APP_VERSION = "1.0.0"
+
+# Used everywhere
+from app.constants.app_metadata import APP_NAME, APP_VERSION
+```
+
+---
+
+## 🎨 Features
+
+### Theme Support
+- ✅ Automatic dark/light mode detection
+- ✅ Respects system preferences
+- ✅ Smooth transitions
+- ✅ CSS custom properties (variables)
+
+### Responsive Design
+- ✅ Mobile-first approach
+- ✅ Flexible grid layouts
+- ✅ Touch-friendly interactions
+- ✅ Breakpoints for all devices
+
+### Performance
+- ✅ Minimal CSS/JS
+- ✅ No external dependencies
+- ✅ Fast page loads
+- ✅ Optimized assets
+
+---
+
+## 📝 Adding New Pages
+
+### Step 1: Create Template
+
+```html
+<!-- templates/about.html -->
+{% extends "base.html" %}
+
+{% block title %}About - {{ app_name }}{% endblock %}
+
+{% block content %}
+<div class="container">
+    <h1>About {{ app_name }}</h1>
+    <p>{{ app_description }}</p>
+</div>
+{% endblock %}
+```
+
+### Step 2: Add Route
+
+```python
+# api/v1/pages.py
+@router.get("/about", response_class=HTMLResponse)
+async def about(request: Request):
+    return templates.TemplateResponse("about.html", {
+        "request": request,
+        "app_name": APP_NAME,
+        "app_description": APP_DESCRIPTION
+    })
+```
+
+### Step 3: Update Navigation (if needed)
+
+```html
+<!-- templates/base.html -->
+<nav>
+    <a href="/">Home</a>
+    <a href="/about">About</a>
+</nav>
+```
+
+---
+
+## 🎯 Best Practices
+
+### 1. **Keep Templates Simple**
+- Logic in Python (routes)
+- Presentation in HTML (templates)
+- Styling in CSS (separate file)
+
+### 2. **Use Template Inheritance**
+```html
+{% extends "base.html" %}
+{% block content %}...{% endblock %}
+```
+
+### 3. **Centralize Configuration**
+```python
+# Don't hardcode
+app_name = "SwiftOps API"
+
+# Do this
+from app.constants.app_metadata import APP_NAME
+```
+
+### 4. **Include Request Object**
+```python
+# Always pass request to templates
+return templates.TemplateResponse("page.html", {
+    "request": request,  # Required by Jinja2Templates
+    "data": data
+})
+```
+
+### 5. **Use url_for for Static Files**
+```html
+<!-- Good -->
+<link href="{{ url_for('static', path='/css/main.css') }}">
+
+<!-- Avoid -->
+<link href="/static/css/main.css">
+```
+
+---
+
+## 🔧 Customization
+
+### Update App Metadata
+
+Edit `constants/app_metadata.py`:
+
+```python
+APP_NAME = "Your App Name"
+APP_VERSION = "2.0.0"
+APP_DESCRIPTION = "Your description"
+```
+
+### Add Custom Styles
+
+Edit `static/css/main.css`:
+
+```css
+/* Add your custom styles */
+.custom-class {
+    color: var(--accent-color);
+}
+```
+
+### Add Custom JavaScript
+
+Edit `static/js/main.js`:
+
+```javascript
+// Add your custom scripts
+document.addEventListener('DOMContentLoaded', function() {
+    // Your code here
+});
+```
+
+---
+
+## 📊 File Structure Benefits
+
+### ✅ **Maintainability**
+- Clear separation of concerns
+- Easy to find and update files
+- Consistent structure
+
+### ✅ **Scalability**
+- Add new pages easily
+- Extend base template
+- Reuse components
+
+### ✅ **Testability**
+- Routes are separate from templates
+- Logic is in Python (testable)
+- Templates are pure HTML
+
+### ✅ **Performance**
+- Static files cached by browser
+- Minimal dependencies
+- Fast rendering
+
+---
+
+## 🚀 Future Enhancements
+
+### Planned Features
+- [ ] Component library (reusable blocks)
+- [ ] Admin dashboard template
+- [ ] Error pages (404, 500)
+- [ ] Email templates
+- [ ] PDF generation templates
+
+### Possible Additions
+- [ ] Template fragments (HTMX support)
+- [ ] Internationalization (i18n)
+- [ ] Template caching
+- [ ] Asset bundling/minification
+
+---
+
+## 📚 Resources
+
+- [FastAPI Templates](https://fastapi.tiangolo.com/advanced/templates/)
+- [Jinja2 Documentation](https://jinja.palletsprojects.com/)
+- [Static Files in FastAPI](https://fastapi.tiangolo.com/tutorial/static-files/)
+- [CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
+
+---
+
+**This architecture provides a solid foundation for building scalable, maintainable web pages in your FastAPI application!** 🎉

docs/dev/spec/DEVELOPMENT_CHECKLIST.md

@@ -0,0 +1,329 @@
+# SwiftOps Backend - Development Checklist
+
+Track your progress as you build the system.
+
+## ✅ Phase 1: Foundation (Week 1)
+
+### Day 1-2: Project Setup
+- [ ] Virtual environment created and activated
+- [ ] Dependencies installed (`pip install -r requirements-dev.txt`)
+- [ ] `.env` file configured with credentials
+- [ ] Docker services running (`docker-compose up -d`)
+- [ ] Can access http://localhost:8000
+- [ ] Can access http://localhost:8000/api/docs
+
+### Day 3-4: Core Components
+- [ ] `app/models/base.py` - Base model tested
+- [ ] `app/models/enums.py` - All ENUMs defined
+- [ ] `app/schemas/base.py` - Base schemas created
+- [ ] `app/schemas/common.py` - Pagination schemas created
+- [ ] First Alembic migration created
+- [ ] Migration applied successfully
+
+### Day 5-7: Authentication & Authorization
+- [ ] `app/core/auth.py` - JWT functions tested
+- [ ] `app/core/security.py` - Password hashing tested
+- [ ] `app/integrations/supabase.py` - Supabase client working
+- [ ] `app/services/auth_service.py` - Login logic implemented
+- [ ] `app/api/v1/auth.py` - Auth endpoints working
+- [ ] `app/api/deps.py` - Auth dependencies working
+- [ ] Can login and get JWT token
+- [ ] Protected endpoints require authentication
+
+---
+
+## ✅ Phase 2: Core Domain Models (Week 2)
+
+### Day 1-2: User & Organization Models
+- [ ] `app/models/user.py` - Users table
+- [ ] `app/models/user.py` - UserFinancialAccounts table
+- [ ] `app/models/user.py` - UserAssetAssignments table
+- [ ] `app/models/user.py` - UserPreferences table
+- [ ] `app/models/organization.py` - Clients table
+- [ ] `app/models/organization.py` - Contractors table
+- [ ] Migration created and applied
+- [ ] Can create users and organizations
+
+### Day 3-4: Project & Team Models
+- [ ] `app/models/project.py` - Projects table
+- [ ] `app/models/project.py` - ProjectTeam table
+- [ ] `app/models/project.py` - ProjectRoles table
+- [ ] `app/models/project.py` - ProjectRegions table
+- [ ] `app/models/project.py` - ProjectSubcontractors table
+- [ ] Migration created and applied
+- [ ] Can create projects with teams
+
+### Day 5-7: Ticket & Customer Models
+- [ ] `app/models/ticket.py` - Tickets table
+- [ ] `app/models/ticket.py` - TicketAssignments table
+- [ ] `app/models/ticket.py` - TicketStatusHistory table
+- [ ] `app/models/ticket.py` - TicketExpenses table
+- [ ] `app/models/customer.py` - Customers table
+- [ ] `app/models/customer.py` - SalesOrders table
+- [ ] `app/models/customer.py` - Subscriptions table
+- [ ] `app/models/incident.py` - Incidents table
+- [ ] `app/models/inventory.py` - All inventory tables
+- [ ] `app/models/finance.py` - All finance tables
+- [ ] `app/models/timesheet.py` - Timesheets table
+- [ ] `app/models/document.py` - Documents table
+- [ ] `app/models/media.py` - MediaFiles table
+- [ ] `app/models/audit_log.py` - AuditLogs table
+- [ ] All migrations created and applied
+- [ ] Database schema matches schema.sql
+
+---
+
+## ✅ Phase 3: Repository Layer (Week 3)
+
+### Day 1-2: Base Repository & Core Repositories
+- [ ] `app/repositories/base_repository.py` - Tested with all CRUD operations
+- [ ] `app/repositories/user_repository.py` - Implemented
+- [ ] `app/repositories/organization_repository.py` - Implemented
+- [ ] Unit tests written for repositories
+
+### Day 3-4: Project & Ticket Repositories
+- [ ] `app/repositories/project_repository.py` - Implemented
+- [ ] `app/repositories/ticket_repository.py` - Implemented
+- [ ] `app/repositories/assignment_repository.py` - Implemented
+- [ ] Complex queries tested (joins, filters)
+
+### Day 5-7: Remaining Repositories
+- [ ] All 15 repositories implemented
+- [ ] All repositories have unit tests
+- [ ] Query performance tested
+
+---
+
+## ✅ Phase 4: Pydantic Schemas (Week 4)
+
+### Day 1-3: Core Domain Schemas
+- [ ] `app/schemas/user.py` - All user schemas
+- [ ] `app/schemas/organization.py` - All org schemas
+- [ ] `app/schemas/project.py` - All project schemas
+- [ ] `app/schemas/ticket.py` - All ticket schemas
+- [ ] `app/schemas/assignment.py` - All assignment schemas
+- [ ] Schema validation tested
+
+### Day 4-7: Remaining Domain Schemas
+- [ ] All 19 schema files implemented
+- [ ] All schemas have validation rules
+- [ ] Edge cases tested
+
+---
+
+## ✅ Phase 5-6: Service Layer (Weeks 5-7)
+
+### Week 5: User, Organization, Project Services
+- [ ] `app/services/user_service.py` - Complete
+- [ ] `app/services/organization_service.py` - Complete
+- [ ] `app/services/project_service.py` - Complete
+- [ ] Unit tests for all services
+
+### Week 6: Ticket & Assignment Services
+- [ ] `app/services/ticket_service.py` - Complete
+- [ ] `app/services/assignment_service.py` - Complete
+- [ ] Ticket workflows tested end-to-end
+
+### Week 7: Customer & Sales Services
+- [ ] `app/services/customer_service.py` - Complete
+- [ ] `app/services/sales_order_service.py` - Complete
+- [ ] `app/services/subscription_service.py` - Complete
+- [ ] `app/services/incident_service.py` - Complete
+- [ ] CSV import working
+
+---
+
+## ✅ Phase 7-8: Operations Services (Weeks 8-9)
+
+### Week 8: Inventory & Expense Services
+- [ ] `app/services/inventory_service.py` - Complete
+- [ ] `app/services/expense_service.py` - Complete
+- [ ] `app/services/payroll_service.py` - Complete
+- [ ] `app/services/timesheet_service.py` - Complete
+- [ ] Payroll calculations tested
+
+---
+
+## ✅ Phase 9-11: API Endpoints (Weeks 9-11)
+
+### Week 9: Core Endpoints
+- [ ] `app/api/v1/users.py` - All endpoints
+- [ ] `app/api/v1/organizations.py` - All endpoints
+- [ ] `app/api/v1/projects.py` - All endpoints
+- [ ] `app/api/v1/tickets.py` - All endpoints
+- [ ] `app/api/v1/assignments.py` - All endpoints
+- [ ] Postman collection created
+
+### Week 10: Customer & Sales Endpoints
+- [ ] `app/api/v1/customers.py` - All endpoints
+- [ ] `app/api/v1/sales_orders.py` - All endpoints
+- [ ] `app/api/v1/subscriptions.py` - All endpoints
+- [ ] `app/api/v1/incidents.py` - All endpoints
+- [ ] CSV import endpoint working
+
+### Week 11: Operations Endpoints
+- [ ] `app/api/v1/inventory.py` - All endpoints
+- [ ] `app/api/v1/expenses.py` - All endpoints
+- [ ] `app/api/v1/payroll.py` - All endpoints
+- [ ] `app/api/v1/timesheets.py` - All endpoints
+
+---
+
+## ✅ Phase 12: External Integrations (Week 12)
+
+### Day 1-2: Media & Documents
+- [ ] `app/integrations/cloudinary.py` - Image upload working
+- [ ] `app/services/media_service.py` - Complete
+- [ ] `app/services/document_service.py` - Complete
+- [ ] `app/api/v1/media.py` - All endpoints
+- [ ] `app/api/v1/documents.py` - All endpoints
+- [ ] Can upload and retrieve images
+
+### Day 3-4: Email & Notifications
+- [ ] `app/integrations/resend.py` - Email sending working
+- [ ] `app/services/notification_service.py` - Complete
+- [ ] Email templates created
+- [ ] Can send emails
+
+### Day 5-7: Payment Integration (Skip M-Pesa for now)
+- [ ] Payment service structure ready
+- [ ] Webhook endpoints created
+- [ ] Manual payment tracking working
+
+---
+
+## ✅ Phase 13: Background Tasks (Week 13)
+
+### Day 1-3: Celery Setup
+- [ ] `app/tasks/celery_app.py` - Configured
+- [ ] `app/tasks/notification_tasks.py` - Email tasks working
+- [ ] Celery worker running
+- [ ] Can send async emails
+
+### Day 4-7: Scheduled Tasks
+- [ ] `app/tasks/payroll_tasks.py` - Weekly payroll
+- [ ] `app/tasks/sla_tasks.py` - SLA monitoring
+- [ ] `app/tasks/cleanup_tasks.py` - Data cleanup
+- [ ] Celery Beat configured
+- [ ] Scheduled tasks running
+
+---
+
+## ✅ Phase 14: Reporting & Analytics (Week 14)
+
+### Day 1-3: CSV Export
+- [ ] `app/services/csv_export_service.py` - Complete
+- [ ] `app/tasks/export_tasks.py` - Async export
+- [ ] `app/api/v1/reports.py` - Export endpoints
+- [ ] Can export tickets to CSV
+
+### Day 4-7: Analytics
+- [ ] `app/services/analytics_service.py` - Complete
+- [ ] `app/api/v1/analytics.py` - All endpoints
+- [ ] Dashboard metrics working
+- [ ] Performance reports working
+
+---
+
+## ✅ Phase 15: Advanced Features (Week 15)
+
+### Day 1-3: OTP & 2FA
+- [ ] `app/services/otp_service.py` - Complete
+- [ ] OTP generation working
+- [ ] OTP verification working
+- [ ] Email OTP delivery working
+
+### Day 4-7: Search & Filtering
+- [ ] `app/utils/filters.py` - Filter builders
+- [ ] Full-text search working
+- [ ] Autocomplete endpoints
+- [ ] Advanced filtering tested
+
+---
+
+## ✅ Phase 16: Middleware & Security (Week 16)
+
+### Day 1-2: Middleware
+- [ ] `app/middleware/rate_limiting.py` - Implemented
+- [ ] `app/middleware/request_logging.py` - Implemented
+- [ ] All middleware active
+
+### Day 3-4: Security
+- [ ] Input validation everywhere
+- [ ] Audit logging working
+- [ ] Data encryption for sensitive fields
+- [ ] Security audit passed
+
+### Day 5-7: Monitoring
+- [ ] `app/api/v1/health.py` - Health checks
+- [ ] `app/integrations/sentry.py` - Error tracking
+- [ ] Logging configured
+- [ ] Can monitor system health
+
+---
+
+## ✅ Phase 17-18: Testing & Quality (Weeks 17-18)
+
+### Week 17: Unit & Integration Tests
+- [ ] 80%+ test coverage
+- [ ] All services have unit tests
+- [ ] All endpoints have integration tests
+- [ ] Edge cases covered
+
+### Week 18: End-to-End Tests
+- [ ] Complete workflows tested
+- [ ] Payment flows tested
+- [ ] CSV import/export tested
+- [ ] Load testing completed
+- [ ] All bugs fixed
+
+---
+
+## ✅ Phase 19: Documentation (Week 19)
+
+### Day 1-3: API Documentation
+- [ ] OpenAPI/Swagger complete
+- [ ] All endpoints documented
+- [ ] Request/response examples
+- [ ] Authentication guide
+
+### Day 4-7: Developer Documentation
+- [ ] Setup guide complete
+- [ ] Architecture documentation
+- [ ] Deployment guide
+- [ ] Troubleshooting guide
+
+---
+
+## ✅ Phase 20: Deployment (Week 20)
+
+### Day 1-3: Docker & CI/CD
+- [ ] Dockerfile optimized
+- [ ] Docker Compose for production
+- [ ] CI/CD pipeline working
+- [ ] Automated testing in CI
+
+### Day 4-7: Production Deployment
+- [ ] Deployed to production
+- [ ] Environment variables configured
+- [ ] Monitoring active (Sentry)
+- [ ] Logging configured
+- [ ] Database backups working
+- [ ] SSL certificates installed
+- [ ] Load balancer configured
+- [ ] Production testing complete
+
+---
+
+## 🎉 Project Complete!
+
+- [ ] All features implemented
+- [ ] All tests passing
+- [ ] Documentation complete
+- [ ] Production deployed
+- [ ] Team trained
+- [ ] Handover complete
+
+---
+
+**Track your progress and celebrate each milestone! 🚀**

docs/dev/spec/HUGGINGFACE_DEPLOYMENT.md

@@ -0,0 +1,276 @@
+# Deploying SwiftOps Backend to Hugging Face Spaces
+
+## 🚀 Quick Deployment Guide
+
+### Prerequisites
+- Hugging Face account
+- Supabase account (for PostgreSQL database)
+- Redis instance (Upstash, Redis Cloud, or similar)
+
+---
+
+## 📋 Step-by-Step Deployment
+
+### 1. Create a New Space
+
+1. Go to https://huggingface.co/spaces
+2. Click "Create new Space"
+3. Configure:
+   - **Name**: `swiftops-backend`
+   - **License**: MIT
+   - **SDK**: Docker
+   - **Hardware**: CPU Basic (or upgrade as needed)
+
+### 2. Set Up External Services
+
+#### A. Supabase (PostgreSQL Database)
+1. Create project at https://supabase.com
+2. Get connection string from Settings → Database
+3. Format: `postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres`
+
+#### B. Redis (Upstash or Redis Cloud)
+1. Create Redis instance at https://upstash.com or https://redis.com
+2. Get connection URL
+3. Format: `redis://default:[PASSWORD]@[HOST]:6379`
+
+### 3. Configure Environment Variables
+
+In your Hugging Face Space settings, add these secrets:
+
+```bash
+# Required
+DATABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
+SUPABASE_URL=https://[PROJECT].supabase.co
+SUPABASE_KEY=[YOUR_ANON_KEY]
+SUPABASE_SERVICE_KEY=[YOUR_SERVICE_KEY]
+SECRET_KEY=[GENERATE_WITH: openssl rand -hex 32]
+REDIS_URL=redis://default:[PASSWORD]@[HOST]:6379
+CELERY_BROKER_URL=redis://default:[PASSWORD]@[HOST]:6379
+CELERY_RESULT_BACKEND=redis://default:[PASSWORD]@[HOST]:6379
+
+# Optional (for production features)
+CLOUDINARY_CLOUD_NAME=[YOUR_CLOUD_NAME]
+CLOUDINARY_API_KEY=[YOUR_API_KEY]
+CLOUDINARY_API_SECRET=[YOUR_API_SECRET]
+RESEND_API_KEY=[YOUR_RESEND_KEY]
+GOOGLE_MAPS_API_KEY=[YOUR_GOOGLE_MAPS_KEY]
+SENTRY_DSN=[YOUR_SENTRY_DSN]
+
+# Application Settings
+ENVIRONMENT=production
+DEBUG=False
+```
+
+### 4. Push Code to Hugging Face
+
+#### Option A: Using Git
+
+```bash
+# Add Hugging Face remote
+git remote add hf https://huggingface.co/spaces/[YOUR_USERNAME]/swiftops-backend
+
+# Push to Hugging Face
+git push hf main
+```
+
+#### Option B: Using Hugging Face Hub
+
+```bash
+# Install huggingface_hub
+pip install huggingface_hub
+
+# Login
+huggingface-cli login
+
+# Upload repository
+huggingface-cli upload [YOUR_USERNAME]/swiftops-backend . --repo-type=space
+```
+
+### 5. Verify Deployment
+
+1. Wait for Docker build to complete (5-10 minutes)
+2. Check build logs in Space settings
+3. Visit your Space URL: `https://huggingface.co/spaces/[YOUR_USERNAME]/swiftops-backend`
+4. Test endpoints:
+   - Health check: `https://[YOUR_SPACE].hf.space/health`
+   - API docs: `https://[YOUR_SPACE].hf.space/api/docs`
+
+---
+
+## 🔧 Important Configuration Changes
+
+### 1. Port Configuration
+Hugging Face Spaces uses **port 7860** by default. The Dockerfile has been updated:
+
+```dockerfile
+EXPOSE 7860
+CMD uvicorn src.app.main:app --host 0.0.0.0 --port 7860
+```
+
+### 2. Database Migrations
+Migrations run automatically on startup:
+
+```dockerfile
+CMD alembic upgrade head && uvicorn src.app.main:app --host 0.0.0.0 --port 7860
+```
+
+### 3. Files Included in Deployment
+
+**Deployed:**
+- ✅ `src/` - Application code
+- ✅ `alembic/` - Database migrations
+- ✅ `alembic.ini` - Migration config
+- ✅ `requirements.txt` - Dependencies
+- ✅ `Dockerfile` - Container definition
+- ✅ `README.md` - Space description
+
+**Not Deployed (via .dockerignore):**
+- ❌ `tests/` - Test suite
+- ❌ `scripts/` - Utility scripts
+- ❌ `docs/` - Documentation
+- ❌ `docker-compose.yml` - Local development
+- ❌ `.pre-commit-config.yaml` - Dev tools
+- ❌ `pytest.ini` - Test config
+
+---
+
+## 🎯 Post-Deployment Tasks
+
+### 1. Run Database Migrations
+Migrations run automatically, but you can verify:
+
+```bash
+# Check Space logs to confirm migrations ran
+# Look for: "Running upgrade ... -> ..."
+```
+
+### 2. Create Admin User
+Use the Space's terminal or API to create first admin user:
+
+```bash
+# Via API (once deployed)
+curl -X POST https://[YOUR_SPACE].hf.space/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "admin@swiftops.com",
+    "password": "secure_password",
+    "name": "Admin User",
+    "role": "platform_admin"
+  }'
+```
+
+### 3. Test API Endpoints
+
+```bash
+# Health check
+curl https://[YOUR_SPACE].hf.space/health
+
+# API documentation
+open https://[YOUR_SPACE].hf.space/api/docs
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Build Fails
+
+**Check Dockerfile:**
+- Ensure all paths are correct
+- Verify requirements.txt has all dependencies
+- Check for syntax errors
+
+**Check Logs:**
+- Go to Space settings → Logs
+- Look for error messages during build
+
+### Database Connection Issues
+
+**Verify Environment Variables:**
+- Check DATABASE_URL format
+- Ensure Supabase allows connections from Hugging Face IPs
+- Test connection string locally first
+
+**Supabase Configuration:**
+- Go to Supabase → Settings → Database
+- Enable "Allow connections from anywhere" (or add HF IPs)
+- Check connection pooling settings
+
+### Redis Connection Issues
+
+**Verify Redis URL:**
+- Check REDIS_URL format
+- Ensure Redis instance is accessible
+- Test connection with redis-cli
+
+### Application Errors
+
+**Check Logs:**
+```bash
+# View Space logs in real-time
+# Go to Space → Settings → Logs
+```
+
+**Common Issues:**
+- Missing environment variables
+- Database migration failures
+- Redis connection timeout
+- Port conflicts (should be 7860)
+
+---
+
+## 📊 Monitoring & Maintenance
+
+### View Logs
+- Go to Space settings → Logs
+- Monitor for errors and warnings
+
+### Update Application
+```bash
+# Make changes locally
+git add .
+git commit -m "Update feature"
+git push hf main
+
+# Space will automatically rebuild
+```
+
+### Scale Resources
+- Go to Space settings → Hardware
+- Upgrade to CPU/GPU as needed
+- Consider persistent storage for uploads
+
+---
+
+## 🔒 Security Checklist
+
+- [ ] All secrets stored as Space secrets (not in code)
+- [ ] DEBUG=False in production
+- [ ] CORS configured properly
+- [ ] Rate limiting enabled
+- [ ] Database backups configured (Supabase)
+- [ ] Redis password protected
+- [ ] API authentication working
+- [ ] HTTPS enabled (automatic on HF Spaces)
+
+---
+
+## 📚 Additional Resources
+
+- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
+- [Docker Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [Supabase Documentation](https://supabase.com/docs)
+- [Upstash Redis Documentation](https://docs.upstash.com/redis)
+
+---
+
+## 🎉 Success!
+
+Your SwiftOps backend is now deployed on Hugging Face Spaces!
+
+**API URL**: `https://[YOUR_USERNAME]-swiftops-backend.hf.space`  
+**API Docs**: `https://[YOUR_USERNAME]-swiftops-backend.hf.space/api/docs`
+
+---
+
+**Need help?** Check the troubleshooting section or open an issue on GitHub.

docs/dev/spec/PROJECT_STATUS.md

@@ -0,0 +1,237 @@
+# SwiftOps Backend - Project Status
+
+**Date:** November 15, 2025  
+**Status:** ✅ **SCAFFOLDED - READY FOR DEVELOPMENT**
+
+---
+
+## 🎉 Scaffolding Complete!
+
+The complete project structure has been created with all necessary folders, files, and configurations. You can now begin development immediately.
+
+## 📊 What's Been Created
+
+### ✅ Core Infrastructure (100%)
+- [x] Project folder structure (all directories)
+- [x] FastAPI application entry point (`main.py`)
+- [x] Configuration management (`config.py`)
+- [x] Database session management (`core/database.py`)
+- [x] Authentication utilities (`core/auth.py`)
+- [x] Security utilities (`core/security.py`)
+- [x] RBAC permissions (`core/permissions.py`)
+- [x] Custom exceptions (`core/exceptions.py`)
+- [x] Logging configuration (`core/logging.py`)
+
+### ✅ Middleware (100%)
+- [x] Authentication middleware (placeholder)
+- [x] Rate limiting middleware (placeholder)
+- [x] Request logging middleware (placeholder)
+- [x] Error handling middleware (implemented)
+- [x] CORS configuration
+
+### ✅ API Layer (100%)
+- [x] API dependencies (`api/deps.py`)
+- [x] Main router (`api/v1/router.py`)
+- [x] All endpoint files created (19 files):
+  - auth.py, users.py, organizations.py, projects.py
+  - tickets.py, assignments.py, customers.py, sales_orders.py
+  - subscriptions.py, incidents.py, inventory.py, expenses.py
+  - payroll.py, timesheets.py, documents.py, media.py
+  - reports.py, analytics.py, webhooks.py, health.py
+
+### ✅ Models (100%)
+- [x] Base model with common fields
+- [x] All ENUM types defined
+- [x] Model files created (12 files):
+  - user.py, organization.py, project.py, ticket.py
+  - customer.py, incident.py, inventory.py, finance.py
+  - timesheet.py, document.py, media.py, audit_log.py
+
+### ✅ Repositories (100%)
+- [x] Base repository with CRUD operations
+- [x] Repository files created (15 files)
+
+### ✅ Services (100%)
+- [x] Service files created (22 files):
+  - auth_service, user_service, organization_service
+  - project_service, ticket_service, assignment_service
+  - customer_service, sales_order_service, subscription_service
+  - incident_service, inventory_service, expense_service
+  - payroll_service, timesheet_service, document_service
+  - media_service, notification_service, report_service
+  - analytics_service, csv_import_service, csv_export_service
+  - otp_service
+
+### ✅ Schemas (100%)
+- [x] Schema files created (19 files)
+
+### ✅ Tasks (100%)
+- [x] Task files created (9 files):
+  - celery_app, notification_tasks, payroll_tasks
+  - payment_tasks, import_tasks, export_tasks
+  - analytics_tasks, sla_tasks, cleanup_tasks
+
+### ✅ Integrations (100%)
+- [x] Integration files created (7 files):
+  - supabase, cloudinary, mpesa, resend
+  - africastalking, google_maps, sentry
+
+### ✅ Utilities (100%)
+- [x] Utility files created (12 files):
+  - cache, encryption, validators, formatters
+  - pagination, filters, date_utils, phone_utils
+  - location_utils, file_utils, csv_utils, distributed_lock
+
+### ✅ Constants (100%)
+- [x] Constant files created (4 files):
+  - roles, permissions, status, messages
+
+### ✅ Configuration Files (100%)
+- [x] requirements.txt (production dependencies)
+- [x] requirements-dev.txt (development dependencies)
+- [x] Dockerfile
+- [x] docker-compose.yml
+- [x] alembic.ini
+- [x] pytest.ini
+- [x] .pre-commit-config.yaml
+- [x] README.md
+
+### ✅ Testing Infrastructure (100%)
+- [x] Test directory structure
+- [x] pytest configuration (conftest.py)
+- [x] Test fixtures directory
+
+### ✅ Scripts (100%)
+- [x] Database seeding script
+- [x] Alembic environment configuration
+
+---
+
+## 🚀 Next Steps - Start Development!
+
+### Phase 1: Foundation (Week 1) - START HERE
+
+#### Step 1: Set Up Environment
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements-dev.txt
+
+# Copy environment file
+cp .env.example .env
+# Edit .env with your Supabase credentials
+```
+
+#### Step 2: Start Docker Services
+```bash
+# Start PostgreSQL and Redis
+docker-compose up -d db redis
+
+# Verify services are running
+docker-compose ps
+```
+
+#### Step 3: Initialize Database
+```bash
+# Create initial migration
+alembic revision --autogenerate -m "Initial schema"
+
+# Apply migration
+alembic upgrade head
+```
+
+#### Step 4: Implement Core Models
+Start with `src/app/models/user.py`:
+- Implement Users table
+- Implement UserFinancialAccounts table
+- Implement UserAssetAssignments table
+- Implement UserPreferences table
+
+Reference: `docs/schema/schema.sql` (lines 1-400)
+
+#### Step 5: Test Your Setup
+```bash
+# Start the development server
+uvicorn src.app.main:app --reload
+
+# Visit http://localhost:8000
+# Visit http://localhost:8000/api/docs (Swagger UI)
+```
+
+---
+
+## 📋 Development Checklist
+
+Follow the build plan in `docs/agent/COMPREHENSIVE_BUILD_PLAN.md`
+
+### Week 1: Foundation ⏳
+- [ ] Environment setup
+- [ ] Docker services running
+- [ ] Database migrations working
+- [ ] Core models implemented
+- [ ] Authentication working
+
+### Week 2: Core Domain Models ⏳
+- [ ] User & Organization models
+- [ ] Project & Team models
+- [ ] Ticket & Customer models
+- [ ] All migrations created
+
+### Week 3: Repository Layer ⏳
+- [ ] Base repository tested
+- [ ] All repositories implemented
+- [ ] Unit tests written
+
+### Week 4: Pydantic Schemas ⏳
+- [ ] All schemas defined
+- [ ] Validation tested
+
+### Weeks 5-20: Continue with build plan...
+
+---
+
+## 📚 Key Documentation
+
+- **Build Plan**: `docs/agent/COMPREHENSIVE_BUILD_PLAN.md`
+- **Backend Features**: `docs/prod/BACKEND_FEATURES.md`
+- **Database Schema**: `docs/schema/schema.sql`
+- **Credentials Setup**: `docs/prod/CREDENTIALS_SETUP_GUIDE.md`
+
+---
+
+## 🎯 Success Criteria
+
+✅ **Scaffolding Complete** - All files and folders created  
+⏳ **Phase 1 Complete** - Core foundation working  
+⏳ **Phase 2 Complete** - All models implemented  
+⏳ **Phase 3 Complete** - Repositories working  
+⏳ **MVP Complete** - Core ticket workflow end-to-end  
+⏳ **Production Ready** - All features implemented and tested
+
+---
+
+## 💡 Tips for Development
+
+1. **Follow the build plan** - It's designed for logical progression
+2. **Test as you go** - Write tests alongside implementation
+3. **Use the schema** - Reference `schema.sql` for exact table definitions
+4. **Start simple** - Get core workflows working before adding complexity
+5. **Commit often** - Small, focused commits are easier to review
+
+---
+
+## 🆘 Need Help?
+
+- Check the build plan for detailed implementation patterns
+- Reference the backend features document for requirements
+- Look at the schema for exact database structure
+- Review existing placeholder files for structure
+
+---
+
+**Ready to build something amazing! 🚀**
+
+Start with Phase 1, Day 1-2: Project Setup and Core Components.

docs/dev/spec/QUICKSTART.md

@@ -0,0 +1,180 @@
+# SwiftOps Backend - Quick Start Guide
+
+Get up and running in 5 minutes!
+
+## 🚀 Quick Setup
+
+### 1. Install Dependencies
+
+```bash
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install packages
+pip install -r requirements-dev.txt
+```
+
+### 2. Configure Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env and add your credentials:
+# - DATABASE_URL (Supabase PostgreSQL URL)
+# - SUPABASE_URL
+# - SUPABASE_KEY
+# - SECRET_KEY (generate with: openssl rand -hex 32)
+```
+
+### 3. Start Services
+
+```bash
+# Option A: Use Docker (Recommended)
+docker-compose up -d
+
+# Option B: Local PostgreSQL and Redis
+# Make sure PostgreSQL and Redis are running locally
+```
+
+### 4. Initialize Database
+
+```bash
+# Create initial migration
+alembic revision --autogenerate -m "Initial schema"
+
+# Apply migrations
+alembic upgrade head
+
+# (Optional) Seed database with test data
+python scripts/seed_database.py
+```
+
+### 5. Run the Application
+
+```bash
+# Start development server
+uvicorn src.app.main:app --reload
+
+# Server will start at http://localhost:8000
+# API docs at http://localhost:8000/api/docs
+```
+
+## ✅ Verify Installation
+
+Visit these URLs to confirm everything works:
+
+- **API Root**: http://localhost:8000
+- **Health Check**: http://localhost:8000/health
+- **API Documentation**: http://localhost:8000/api/docs
+- **ReDoc**: http://localhost:8000/api/redoc
+
+## 🧪 Run Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=src/app
+
+# Run specific test
+pytest tests/unit/services/test_auth_service.py
+```
+
+## 🔧 Development Tools
+
+```bash
+# Format code
+black src/ tests/
+
+# Sort imports
+isort src/ tests/
+
+# Lint code
+flake8 src/ tests/
+
+# Type checking
+mypy src/
+```
+
+## 📦 Docker Commands
+
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f api
+
+# Stop services
+docker-compose down
+
+# Rebuild after code changes
+docker-compose up -d --build
+```
+
+## 🎯 Next Steps
+
+1. **Read the Build Plan**: `docs/agent/COMPREHENSIVE_BUILD_PLAN.md`
+2. **Check Project Status**: `PROJECT_STATUS.md`
+3. **Start with Phase 1**: Implement core models
+4. **Follow the checklist**: Week-by-week implementation
+
+## 🆘 Troubleshooting
+
+### Database Connection Error
+```bash
+# Check if PostgreSQL is running
+docker-compose ps
+
+# Check DATABASE_URL in .env
+# Format: postgresql://user:password@host:port/database
+```
+
+### Import Errors
+```bash
+# Make sure you're in the virtual environment
+source venv/bin/activate
+
+# Reinstall dependencies
+pip install -r requirements-dev.txt
+```
+
+### Alembic Migration Issues
+```bash
+# Reset migrations (CAUTION: Deletes all data)
+alembic downgrade base
+alembic upgrade head
+
+# Or drop and recreate database
+docker-compose down -v
+docker-compose up -d
+```
+
+## 📚 Useful Commands
+
+```bash
+# Create new migration
+alembic revision --autogenerate -m "Add new table"
+
+# Apply migrations
+alembic upgrade head
+
+# Rollback one migration
+alembic downgrade -1
+
+# Start Celery worker
+celery -A src.app.tasks.celery_app worker --loglevel=info
+
+# Start Celery beat
+celery -A src.app.tasks.celery_app beat --loglevel=info
+
+# Monitor Celery with Flower
+celery -A src.app.tasks.celery_app flower
+```
+
+## 🎉 You're Ready!
+
+The project is fully scaffolded and ready for development. Start building! 🚀

docs/dev/spec/SCAFFOLDING_COMPLETE.md

@@ -0,0 +1,292 @@
+# 🎉 SwiftOps Backend - Scaffolding Complete!
+
+**Date:** November 15, 2025  
+**Status:** ✅ **READY FOR DEVELOPMENT**
+
+---
+
+## 📊 What We've Built
+
+### Complete Project Structure
+- **200+ files created**
+- **18 directories** organized by domain
+- **All placeholder files** with TODO comments
+- **Production-ready configuration**
+
+### Key Components Created
+
+#### 1. Core Infrastructure ✅
+```
+src/app/core/
+├── auth.py              # JWT token management
+├── security.py          # Password hashing
+├── permissions.py       # RBAC definitions
+├── exceptions.py        # Custom exceptions
+├── logging.py           # Structured logging
+└── database.py          # Database sessions
+```
+
+#### 2. API Layer ✅
+```
+src/app/api/v1/
+├── auth.py              # Authentication endpoints
+├── users.py             # User management
+├── projects.py          # Project CRUD
+├── tickets.py           # Ticket operations
+├── ... (19 endpoint files total)
+```
+
+#### 3. Business Logic ✅
+```
+src/app/services/
+├── auth_service.py
+├── ticket_service.py
+├── payroll_service.py
+├── ... (22 service files total)
+```
+
+#### 4. Data Access ✅
+```
+src/app/repositories/
+├── base_repository.py   # Generic CRUD
+├── ticket_repository.py
+├── ... (15 repository files total)
+```
+
+#### 5. Database Models ✅
+```
+src/app/models/
+├── base.py              # Base model with common fields
+├── enums.py             # All ENUM types
+├── user.py, project.py, ticket.py
+├── ... (12 model files total)
+```
+
+#### 6. Request/Response Schemas ✅
+```
+src/app/schemas/
+├── base.py, common.py
+├── ticket.py, user.py
+├── ... (19 schema files total)
+```
+
+#### 7. Background Tasks ✅
+```
+src/app/tasks/
+├── celery_app.py        # Celery configuration
+├── payroll_tasks.py     # Weekly payroll
+├── sla_tasks.py         # SLA monitoring
+├── ... (9 task files total)
+```
+
+#### 8. External Integrations ✅
+```
+src/app/integrations/
+├── supabase.py          # Supabase client
+├── cloudinary.py        # Image uploads
+├── mpesa.py             # Payment gateway
+├── resend.py            # Email service
+├── ... (7 integration files total)
+```
+
+#### 9. Utilities ✅
+```
+src/app/utils/
+├── cache.py             # Redis caching
+├── validators.py        # Input validation
+├── pagination.py        # Pagination helpers
+├── ... (12 utility files total)
+```
+
+#### 10. Configuration Files ✅
+```
+Root Directory:
+├── requirements.txt     # Production dependencies
+├── Dockerfile           # Docker image
+├── docker-compose.yml   # Multi-container setup
+├── alembic.ini          # Database migrations
+├── pytest.ini           # Test configuration
+├── .pre-commit-config   # Code quality hooks
+└── README.md            # Project documentation
+```
+
+---
+
+## 🎯 Project Statistics
+
+| Category | Count | Status |
+|----------|-------|--------|
+| **Total Files** | 200+ | ✅ Created |
+| **Directories** | 18 | ✅ Created |
+| **API Endpoints** | 19 | ✅ Scaffolded |
+| **Services** | 22 | ✅ Scaffolded |
+| **Repositories** | 15 | ✅ Scaffolded |
+| **Models** | 12 | ✅ Scaffolded |
+| **Schemas** | 19 | ✅ Scaffolded |
+| **Tasks** | 9 | ✅ Scaffolded |
+| **Integrations** | 7 | ✅ Scaffolded |
+| **Utilities** | 12 | ✅ Scaffolded |
+
+---
+
+## 🚀 What's Implemented vs. What's Scaffolded
+
+### ✅ Fully Implemented (Ready to Use)
+- FastAPI application entry point
+- Configuration management (Pydantic Settings)
+- Database session management
+- JWT token creation and verification
+- Password hashing (bcrypt)
+- RBAC permission system
+- Custom exception classes
+- Error handling middleware
+- Base repository with CRUD operations
+- Base model with soft delete
+- All ENUM types
+- API dependencies (auth, database)
+- Docker Compose setup
+- Alembic configuration
+- Pytest configuration
+
+### 📝 Scaffolded (TODO Comments)
+- All API endpoint implementations
+- All service business logic
+- All repository queries
+- All database models
+- All Pydantic schemas
+- All background tasks
+- All external integrations
+- All utility functions
+
+---
+
+## 📚 Documentation Created
+
+1. **README.md** - Project overview and setup instructions
+2. **QUICKSTART.md** - 5-minute setup guide
+3. **PROJECT_STATUS.md** - Detailed status and checklist
+4. **SCAFFOLDING_COMPLETE.md** - This file!
+
+Existing Documentation:
+- **COMPREHENSIVE_BUILD_PLAN.md** - 20-week implementation plan
+- **BACKEND_FEATURES.md** - Complete feature specifications
+- **schema.sql** - Database schema with workflows
+
+---
+
+## 🎓 How to Use This Scaffolding
+
+### Step 1: Set Up Environment
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements-dev.txt
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+### Step 2: Start Services
+```bash
+docker-compose up -d
+```
+
+### Step 3: Initialize Database
+```bash
+alembic revision --autogenerate -m "Initial schema"
+alembic upgrade head
+```
+
+### Step 4: Start Development
+```bash
+uvicorn src.app.main:app --reload
+```
+
+### Step 5: Follow the Build Plan
+Open `docs/agent/COMPREHENSIVE_BUILD_PLAN.md` and start with **Phase 1: Foundation (Week 1)**
+
+---
+
+## 🔍 Finding Your Way Around
+
+### Need to implement a feature?
+1. **Check the build plan** for the implementation order
+2. **Find the TODO file** in the appropriate directory
+3. **Reference the schema** (`docs/schema/schema.sql`) for database structure
+4. **Check backend features** (`docs/prod/BACKEND_FEATURES.md`) for requirements
+
+### Example: Implementing Ticket Creation
+
+1. **Model**: `src/app/models/ticket.py` - Define Ticket table
+2. **Schema**: `src/app/schemas/ticket.py` - Define TicketCreate, TicketResponse
+3. **Repository**: `src/app/repositories/ticket_repository.py` - Add create_ticket()
+4. **Service**: `src/app/services/ticket_service.py` - Add business logic
+5. **API**: `src/app/api/v1/tickets.py` - Add POST /tickets endpoint
+6. **Test**: `tests/unit/services/test_ticket_service.py` - Write tests
+
+---
+
+## 🎯 Next Immediate Steps
+
+### Today (Day 1)
+1. ✅ Scaffolding complete
+2. ⏳ Set up your development environment
+3. ⏳ Start Docker services
+4. ⏳ Create first database migration
+
+### This Week (Week 1)
+1. ⏳ Implement User model
+2. ⏳ Implement Organization model
+3. ⏳ Implement authentication endpoints
+4. ⏳ Write first tests
+
+### This Month (Weeks 1-4)
+1. ⏳ Complete all database models
+2. ⏳ Implement all repositories
+3. ⏳ Define all Pydantic schemas
+4. ⏳ Set up CI/CD pipeline
+
+---
+
+## 💡 Pro Tips
+
+1. **Start Small**: Get one complete workflow working end-to-end before adding complexity
+2. **Test Early**: Write tests as you implement features (TDD approach)
+3. **Use the Schema**: The `schema.sql` file is your source of truth for database structure
+4. **Follow Patterns**: The base repository and service patterns are your templates
+5. **Commit Often**: Small, focused commits make debugging easier
+
+---
+
+## 🆘 Need Help?
+
+### Documentation
+- **Build Plan**: `docs/agent/COMPREHENSIVE_BUILD_PLAN.md`
+- **Backend Features**: `docs/prod/BACKEND_FEATURES.md`
+- **Database Schema**: `docs/schema/schema.sql`
+- **Quick Start**: `QUICKSTART.md`
+
+### Common Issues
+- **Import errors**: Make sure virtual environment is activated
+- **Database errors**: Check DATABASE_URL in .env
+- **Docker issues**: Run `docker-compose down -v` and restart
+
+---
+
+## 🎉 Congratulations!
+
+You now have a **production-ready project structure** with:
+- ✅ Clean architecture (API → Service → Repository → Model)
+- ✅ Proper separation of concerns
+- ✅ Scalable folder structure
+- ✅ All necessary configuration files
+- ✅ Testing infrastructure
+- ✅ Docker support
+- ✅ Comprehensive documentation
+
+**Everything is in place. Now it's time to build! 🚀**
+
+---
+
+**Happy Coding!** 💻
+
+Start with Phase 1 of the build plan and work your way through systematically.

docs/dev/spec/START_HERE.md

@@ -0,0 +1,241 @@
+# 🚀 START HERE - SwiftOps Backend
+
+## Welcome! Your Project is Ready 🎉
+
+The complete SwiftOps backend has been **scaffolded and is ready for development**.
+
+---
+
+## 📖 Quick Navigation
+
+### 🏃 Want to Start Immediately?
+**Read:** [`QUICKSTART.md`](QUICKSTART.md) - Get running in 5 minutes
+
+### 📊 Want to See What's Built?
+**Read:** [`SCAFFOLDING_COMPLETE.md`](SCAFFOLDING_COMPLETE.md) - Complete overview
+
+### ✅ Want to Track Progress?
+**Read:** [`DEVELOPMENT_CHECKLIST.md`](DEVELOPMENT_CHECKLIST.md) - Week-by-week checklist
+
+### 📋 Want the Full Plan?
+**Read:** [`docs/agent/COMPREHENSIVE_BUILD_PLAN.md`](docs/agent/COMPREHENSIVE_BUILD_PLAN.md) - 20-week implementation plan
+
+### 🔍 Want to Understand the System?
+**Read:** [`docs/prod/BACKEND_FEATURES.md`](docs/prod/BACKEND_FEATURES.md) - All features explained
+
+### 🗄️ Want to See the Database?
+**Read:** [`docs/schema/schema.sql`](docs/schema/schema.sql) - Complete database schema
+
+---
+
+## 🎯 What You Have
+
+### ✅ Complete Project Structure
+- 200+ files created
+- 18 organized directories
+- Production-ready configuration
+- All placeholder files with TODO comments
+
+### ✅ Core Infrastructure
+- FastAPI application setup
+- Database session management
+- JWT authentication
+- RBAC permissions
+- Error handling
+- Logging configuration
+
+### ✅ Development Tools
+- Docker Compose setup
+- Alembic migrations
+- Pytest configuration
+- Pre-commit hooks
+- Code quality tools
+
+### ✅ Documentation
+- Quick start guide
+- Build plan (20 weeks)
+- Feature specifications
+- Database schema
+- Development checklist
+
+---
+
+## 🚀 Get Started in 3 Steps
+
+### Step 1: Set Up Environment (5 minutes)
+```bash
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements-dev.txt
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your Supabase credentials
+```
+
+### Step 2: Start Services (2 minutes)
+```bash
+# Start PostgreSQL and Redis
+docker-compose up -d
+
+# Verify services
+docker-compose ps
+```
+
+### Step 3: Run the Application (1 minute)
+```bash
+# Start development server
+uvicorn src.app.main:app --reload
+
+# Visit http://localhost:8000
+# API docs at http://localhost:8000/api/docs
+```
+
+---
+
+## 📚 Key Files to Know
+
+| File | Purpose |
+|------|---------|
+| `src/app/main.py` | FastAPI application entry point |
+| `src/app/config.py` | Configuration management |
+| `src/app/core/database.py` | Database sessions |
+| `src/app/core/auth.py` | JWT authentication |
+| `src/app/models/base.py` | Base model for all tables |
+| `src/app/repositories/base_repository.py` | Base CRUD operations |
+| `docker-compose.yml` | Docker services configuration |
+| `alembic.ini` | Database migration configuration |
+| `requirements.txt` | Python dependencies |
+
+---
+
+## 🎓 Development Workflow
+
+### 1. Implement a Feature
+```
+Model → Schema → Repository → Service → API → Test
+```
+
+### 2. Example: Add Ticket Creation
+1. **Model**: Define Ticket table in `src/app/models/ticket.py`
+2. **Schema**: Define TicketCreate in `src/app/schemas/ticket.py`
+3. **Repository**: Add create() in `src/app/repositories/ticket_repository.py`
+4. **Service**: Add business logic in `src/app/services/ticket_service.py`
+5. **API**: Add POST endpoint in `src/app/api/v1/tickets.py`
+6. **Test**: Write tests in `tests/unit/services/test_ticket_service.py`
+
+### 3. Create Database Migration
+```bash
+alembic revision --autogenerate -m "Add tickets table"
+alembic upgrade head
+```
+
+### 4. Run Tests
+```bash
+pytest
+pytest --cov=src/app
+```
+
+---
+
+## 🗺️ Project Structure Overview
+
+```
+swiftops-backend/
+├── src/app/              # Application code
+│   ├── api/              # API endpoints (19 files)
+│   ├── core/             # Core utilities (7 files)
+│   ├── models/           # Database models (12 files)
+│   ├── schemas/          # Request/response schemas (19 files)
+│   ├── services/         # Business logic (22 files)
+│   ├── repositories/     # Data access (15 files)
+│   ├── tasks/            # Background tasks (9 files)
+│   ├── integrations/     # External services (7 files)
+│   ├── utils/            # Utilities (12 files)
+│   └── constants/        # Constants (4 files)
+├── tests/                # Test suite
+├── alembic/              # Database migrations
+├── docs/                 # Documentation
+└── scripts/              # Utility scripts
+```
+
+---
+
+## 💡 Pro Tips
+
+1. **Follow the Build Plan**: It's designed for logical progression
+2. **Start with Models**: Get the database structure right first
+3. **Test as You Go**: Write tests alongside implementation
+4. **Use the Schema**: Reference `schema.sql` for exact table definitions
+5. **Commit Often**: Small, focused commits are easier to review
+
+---
+
+## 🆘 Need Help?
+
+### Common Issues
+
+**Import Errors**
+```bash
+# Make sure virtual environment is activated
+source venv/bin/activate
+pip install -r requirements-dev.txt
+```
+
+**Database Connection Error**
+```bash
+# Check if PostgreSQL is running
+docker-compose ps
+
+# Check DATABASE_URL in .env
+```
+
+**Alembic Migration Issues**
+```bash
+# Reset migrations (CAUTION: Deletes data)
+alembic downgrade base
+alembic upgrade head
+```
+
+### Documentation
+- **Quick Start**: `QUICKSTART.md`
+- **Project Status**: `PROJECT_STATUS.md`
+- **Build Plan**: `docs/agent/COMPREHENSIVE_BUILD_PLAN.md`
+- **Features**: `docs/prod/BACKEND_FEATURES.md`
+- **Schema**: `docs/schema/schema.sql`
+
+---
+
+## 🎯 Your First Task
+
+**Implement the User Model** (Phase 1, Day 3-4)
+
+1. Open `src/app/models/user.py`
+2. Reference `docs/schema/schema.sql` (lines 1-400)
+3. Implement:
+   - Users table
+   - UserFinancialAccounts table
+   - UserAssetAssignments table
+   - UserPreferences table
+4. Create migration: `alembic revision --autogenerate -m "Add user tables"`
+5. Apply migration: `alembic upgrade head`
+6. Test: Create a user in the database
+
+---
+
+## 🎉 You're All Set!
+
+Everything is in place. The project is scaffolded, documented, and ready for development.
+
+**Now go build something amazing! 🚀**
+
+---
+
+**Questions?** Check the documentation files listed above.
+
+**Ready to code?** Start with `QUICKSTART.md` and then follow the `COMPREHENSIVE_BUILD_PLAN.md`.
+
+**Happy coding!** 💻

docs/huggingface/examples/Dockerfile

@@ -0,0 +1,80 @@
+# Dockerfile for Atlas GIS API on HuggingFace Spaces
+# Includes GDAL installation for geospatial libraries
+
+FROM python:3.11-slim
+
+# Install system dependencies including GDAL and geospatial libraries
+RUN apt-get update && apt-get install -y \
+    # GDAL and geospatial dependencies
+    gdal-bin \
+    libgdal-dev \
+    libproj-dev \
+    libgeos-dev \
+    libspatialindex-dev \
+    # Build tools for compilation
+    build-essential \
+    # Utilities
+    curl \
+    wget \
+    git \
+    # Cleanup
+    && rm -rf /var/lib/apt/lists/*
+
+# Set GDAL environment variables
+ENV GDAL_CONFIG=/usr/bin/gdal-config
+ENV GDAL_DATA=/usr/share/gdal
+ENV PROJ_LIB=/usr/share/proj
+
+# Set up a new user named "user" with user ID 1000 (HuggingFace requirement)
+RUN useradd -m -u 1000 user
+
+# Switch to the "user" user
+USER user
+
+# Set home to the user's home directory
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Set the working directory to the user's home directory
+WORKDIR $HOME/app
+
+# Set environment variables for the application
+ENV PYTHONPATH=$HOME/app
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Copy the requirements file and install Python dependencies
+COPY --chown=user ./requirements.txt requirements.txt
+
+# Upgrade pip and install dependencies
+RUN pip install --no-cache-dir --upgrade pip
+
+# Install Python dependencies with specific handling for geospatial packages
+# Note: GDAL Python bindings will be automatically matched to system GDAL version
+# by the requirements.txt installation process
+RUN pip install --no-cache-dir --user \
+    # Install other dependencies first
+    -r requirements.txt
+
+# Copy the application source code
+COPY --chown=user ./src src
+
+# Create app.py entry point for HuggingFace Spaces
+COPY --chown=user ./app.py app.py
+
+# Create necessary directories
+RUN mkdir -p \
+    $HOME/app/temp_exports \
+    $HOME/app/logs \
+    $HOME/.cache
+
+# Expose port 7860 (HuggingFace Spaces requirement)
+EXPOSE 7860
+
+# Health check for container monitoring
+HEALTHCHECK --interval=30s --timeout=30s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/api/v1/health || exit 1
+
+# Start the FastAPI application on port 7860
+# HuggingFace Spaces requires this specific port and host configuration
+CMD ["python", "-m", "uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "7860"]

docs/huggingface/examples/requirements.txt

@@ -0,0 +1,61 @@
+# Atlas FastAPI Service - Production Dependencies
+
+# Core Web Framework
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+pydantic==2.5.0
+pydantic-settings==2.1.0
+
+# Geospatial Core Libraries
+geopandas==0.14.1
+shapely==2.0.2
+fiona==1.9.5
+pyproj==3.6.1
+rasterio==1.3.9
+geojson-pydantic==1.1.0
+
+# Data Source Libraries
+earthengine-api==0.1.383
+osmnx==1.7.1
+overpy==0.7
+requests==2.31.0
+
+# Export Format Libraries
+simplekml==1.3.6
+ezdxf==1.1.4
+openpyxl==3.1.2
+
+# Async and Concurrency
+aiohttp==3.9.1
+aiofiles==23.2.1
+asyncio-throttle==1.0.2
+
+# Utilities
+python-multipart==0.0.6
+python-jose[cryptography]==3.3.0
+python-dotenv==1.0.0
+click==8.1.7
+
+# Optional: Caching and Performance
+redis==5.0.1
+hiredis==2.2.3
+
+# Monitoring and Logging
+structlog==23.2.0
+prometheus-client==0.19.0
+
+# Data Processing
+pandas==2.1.4
+numpy==1.25.2
+matplotlib==3.8.2
+folium==0.15.1
+
+# Development and Testing (commented for production)
+# pytest==7.4.3
+# pytest-asyncio==0.21.1
+# pytest-cov==4.1.0
+# black==23.11.0
+# isort==5.12.0
+# flake8==6.1.0
+# mypy==1.7.1
+# pre-commit==3.6.0

docs/prod/BACKEND_FEATURES.md

@@ -0,0 +1,1821 @@
+# SwiftOps Backend Features & Responsibilities
+
+**Version:** 1.0  
+**Last Updated:** November 2025  
+**Status:** Production Planning
+
+---
+
+## Overview
+
+This document outlines the comprehensive backend features and responsibilities for the SwiftOps FastAPI server. The backend acts as the central orchestrator for all business logic, data management, external integrations, and security controls.
+
+## Architecture Philosophy
+
+The FastAPI backend is the **single source of truth** for all operations:
+- Frontend applications (web, mobile) are thin clients
+- All database operations go through the backend
+- All business logic is enforced server-side
+- All external service integrations are managed by the backend
+
+---
+
+## 1. 🔐 Authentication & Authorization
+
+### 1.1 Supabase Auth Integration
+
+**Responsibilities:**
+- Integrate with Supabase Auth for user authentication
+- Validate JWT tokens from Supabase
+- Sync user data between Supabase Auth and application database
+- Handle user registration and onboarding flows
+
+**Implementation:**
+```python
+# app/core/auth.py
+- verify_supabase_token()
+- create_user_from_supabase()
+- sync_user_roles()
+```
+
+**Endpoints:**
+```
+POST   /api/v1/auth/login
+POST   /api/v1/auth/register
+POST   /api/v1/auth/logout
+POST   /api/v1/auth/refresh-token
+GET    /api/v1/auth/me
+```
+
+### 1.2 JWT Token Management
+
+**Responsibilities:**
+- Generate access tokens (24-hour expiry)
+- Generate refresh tokens (30-day expiry)
+- Token validation and verification
+- Token blacklisting on logout
+
+**Implementation:**
+```python
+# app/core/auth.py
+- create_access_token()
+- create_refresh_token()
+- verify_token()
+- blacklist_token()
+```
+
+**Token Structure:**
+```json
+{
+  "sub": "user_id",
+  "email": "user@example.com",
+  "role": "field_agent",
+  "client_id": "uuid",
+  "contractor_id": "uuid",
+  "exp": 1234567890,
+  "iat": 1234567890
+}
+```
+
+### 1.3 OTP & 2FA (Two-Factor Authentication)
+
+**Responsibilities:**
+- Generate OTP codes for critical operations
+- Send OTP via email (Resend) or SMS (Africa's Talking)
+- Verify OTP codes with expiry validation
+- Rate limiting on OTP generation (max 3 per 5 minutes)
+
+**Critical Operations Requiring 2FA:**
+- Bulk payment authorization (>$1000 or >10 transactions)
+- Payroll approval and disbursement
+- User role changes (elevation to admin)
+- Project closure with financial settlement
+- Bulk ticket reassignment (>20 tickets)
+- Inventory write-offs (>$500 value)
+
+**Implementation:**
+```python
+# app/services/otp_service.py
+- generate_otp(user_id, operation_type)
+- send_otp_email(user_id, otp_code)
+- send_otp_sms(user_id, otp_code)
+- verify_otp(user_id, otp_code, operation_type)
+- invalidate_otp(user_id, operation_type)
+```
+
+**Endpoints:**
+```
+POST   /api/v1/auth/otp/generate
+POST   /api/v1/auth/otp/verify
+POST   /api/v1/auth/otp/resend
+```
+
+**OTP Flow:**
+```
+1. User initiates critical operation
+2. Backend generates 6-digit OTP (valid 5 minutes)
+3. OTP sent via email/SMS
+4. User enters OTP in frontend
+5. Backend verifies OTP
+6. Operation proceeds if valid
+7. OTP invalidated after use
+```
+
+### 1.4 Role-Based Access Control (RBAC)
+
+**Responsibilities:**
+- Enforce role-based permissions on all endpoints
+- Validate user has required role for operation
+- Support hierarchical permissions (admin > manager > agent)
+- Dynamic permission checking based on resource ownership
+
+**Roles & Permissions:**
+```python
+# app/core/permissions.py
+ROLES = {
+    "platform_admin": ["*"],  # All permissions
+    "client_admin": ["manage_projects", "invite_users", "view_reports"],
+    "contractor_admin": ["manage_agents", "accept_projects", "view_payroll"],
+    "project_manager": ["create_tickets", "manage_inventory", "approve_expenses"],
+    "dispatcher": ["assign_tickets", "issue_equipment", "approve_expenses"],
+    "field_agent": ["view_tickets", "update_status", "log_expenses"],
+    "sales_agent": ["create_orders", "view_customers"],
+    "sales_manager": ["view_team_performance", "export_reports"]
+}
+```
+
+---
+
+## 2. 📧 Communication Services
+
+### 2.1 Email Service (Resend)
+
+**Responsibilities:**
+- Send transactional emails (OTP, password reset, notifications)
+- Send bulk emails (weekly reports, announcements)
+- Email templating with dynamic content
+- Track email delivery status
+- Handle email bounces and failures
+
+**Email Types:**
+- **Transactional**: OTP codes, password resets, account verification
+- **Notifications**: Ticket assignments, status updates, payment confirmations
+- **Reports**: Weekly payroll summaries, SLA compliance reports
+- **Marketing**: Feature announcements, system updates
+
+**Implementation:**
+```python
+# app/integrations/resend.py
+- send_email(to, subject, html_content, template_id)
+- send_bulk_email(recipients, subject, html_content)
+- send_templated_email(to, template_id, variables)
+- get_email_status(email_id)
+```
+
+**Email Templates:**
+```
+- otp_verification.html
+- password_reset.html
+- ticket_assignment.html
+- payroll_summary.html
+- expense_approved.html
+- payment_confirmation.html
+```
+
+**Endpoints:**
+```
+POST   /api/v1/communications/email/send
+POST   /api/v1/communications/email/bulk
+GET    /api/v1/communications/email/{email_id}/status
+```
+
+### 2.2 SMS Service (Africa's Talking) - V2 Feature
+
+**Responsibilities:**
+- Send SMS notifications to field agents
+- Send OTP codes via SMS
+- Bulk SMS for urgent alerts
+- Track SMS delivery status
+- Handle SMS failures and retries
+
+**SMS Use Cases:**
+- OTP codes for 2FA
+- Urgent ticket assignments
+- SLA violation alerts
+- Payment confirmations
+- Emergency notifications
+
+**Implementation:**
+```python
+# app/integrations/africastalking.py
+- send_sms(phone_number, message)
+- send_bulk_sms(phone_numbers, message)
+- get_sms_status(sms_id)
+```
+
+**Endpoints:**
+```
+POST   /api/v1/communications/sms/send
+POST   /api/v1/communications/sms/bulk
+GET    /api/v1/communications/sms/{sms_id}/status
+```
+
+### 2.3 Push Notifications - V2 Feature
+
+**Responsibilities:**
+- Send push notifications to mobile apps
+- Real-time alerts for critical events
+- Notification preferences management
+- Badge count management
+
+**Implementation:**
+```python
+# app/services/push_notification_service.py
+- send_push_notification(user_id, title, body, data)
+- send_bulk_push_notification(user_ids, title, body, data)
+```
+
+---
+
+## 3. 📸 Media & Photo Management
+
+### 3.1 Cloudinary Integration
+
+**Responsibilities:**
+- Upload images to Cloudinary
+- Generate optimized image URLs
+- Image transformation (resize, crop, compress)
+- Map images to tickets, users, documents
+- Delete images when records are deleted
+
+**Image Types:**
+- **Ticket Photos**: Before/after installation photos, issue documentation
+- **Profile Photos**: User avatars, field agent photos
+- **Receipt Photos**: Expense receipts, delivery notes
+- **Document Scans**: Contracts, invoices, reports
+
+**Implementation:**
+```python
+# app/integrations/cloudinary.py
+- upload_image(file, folder, public_id)
+- get_image_url(public_id, transformations)
+- delete_image(public_id)
+- upload_multiple_images(files, folder)
+```
+
+**Image Transformations:**
+```python
+# Thumbnail: 150x150, quality 80
+# Medium: 800x600, quality 85
+# Large: 1920x1080, quality 90
+# Original: No transformation
+```
+
+**Endpoints:**
+```
+POST   /api/v1/media/upload
+POST   /api/v1/media/upload-multiple
+GET    /api/v1/media/{media_id}
+DELETE /api/v1/media/{media_id}
+GET    /api/v1/tickets/{ticket_id}/photos
+POST   /api/v1/tickets/{ticket_id}/photos
+GET    /api/v1/users/{user_id}/profile-photo
+POST   /api/v1/users/{user_id}/profile-photo
+```
+
+### 3.2 Image Validation
+
+**Responsibilities:**
+- Validate file type (JPEG, PNG, PDF)
+- Validate file size (max 10MB per file)
+- Validate image dimensions (min 640x480)
+- Scan for malware (optional)
+- EXIF data extraction (GPS, timestamp)
+
+**Implementation:**
+```python
+# app/utils/media_validation.py
+- validate_image_file(file)
+- validate_file_size(file, max_size_mb)
+- extract_exif_data(file)
+- validate_image_dimensions(file, min_width, min_height)
+```
+
+### 3.3 Image Metadata Management
+
+**Responsibilities:**
+- Store image metadata in database
+- Link images to entities (tickets, users, expenses)
+- Track upload timestamp and uploader
+- Support image captions and descriptions
+
+**Database Schema:**
+```sql
+CREATE TABLE media_files (
+    id UUID PRIMARY KEY,
+    cloudinary_public_id VARCHAR(255),
+    cloudinary_url TEXT,
+    file_type VARCHAR(50),
+    file_size_bytes INTEGER,
+    width INTEGER,
+    height INTEGER,
+    uploaded_by_user_id UUID,
+    entity_type VARCHAR(50),  -- 'ticket', 'user', 'expense'
+    entity_id UUID,
+    caption TEXT,
+    exif_data JSONB,
+    created_at TIMESTAMP,
+    deleted_at TIMESTAMP
+);
+```
+
+---
+
+## 4. 📍 Location & Field Agent Allocation (V2 Feature)
+
+### 4.1 Intelligent Agent Allocation
+
+**Responsibilities:**
+- Auto-assign tickets to nearest available agents
+- Consider agent workload (max 3 active tickets)
+- Consider agent skills and specializations
+- Optimize routes for multiple tickets
+- Balance workload across team
+
+**Allocation Algorithm:**
+```python
+# app/services/allocation_service.py
+def allocate_ticket(ticket_id):
+    1. Get ticket location
+    2. Find agents in same region
+    3. Filter agents with < 3 active tickets
+    4. Filter agents with required skills
+    5. Calculate distance from each agent's current location
+    6. Score agents: (distance × 0.4) + (workload × 0.3) + (skill_match × 0.3)
+    7. Assign to highest scoring agent
+    8. Send notification to agent
+```
+
+**Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/auto-assign
+POST   /api/v1/tickets/bulk-auto-assign
+GET    /api/v1/agents/available
+GET    /api/v1/agents/nearest?lat={lat}&lng={lng}
+```
+
+### 4.2 Route Optimization
+
+**Responsibilities:**
+- Calculate optimal route for agent's daily tickets
+- Minimize travel time and distance
+- Consider ticket priorities and SLA deadlines
+- Provide turn-by-turn directions
+
+**Implementation:**
+```python
+# app/services/route_optimization_service.py
+- optimize_route(agent_id, ticket_ids)
+- calculate_travel_time(origin, destination)
+- get_directions(origin, destination)
+```
+
+**Endpoints:**
+```
+GET    /api/v1/agents/{agent_id}/optimized-route
+GET    /api/v1/tickets/{ticket_id}/directions
+```
+
+### 4.3 Geofencing & Proximity Alerts
+
+**Responsibilities:**
+- Alert agent when approaching customer location
+- Verify agent is within geofence before allowing check-in
+- Track time spent at customer location
+- Detect if agent leaves before completing work
+
+**Implementation:**
+```python
+# app/services/geofencing_service.py
+- check_proximity(agent_location, customer_location, radius_meters)
+- create_geofence(center_lat, center_lng, radius_meters)
+- check_agent_in_geofence(agent_location, geofence)
+```
+
+---
+
+## 5. 🔍 Filtering & Search
+
+### 5.1 Advanced Filtering
+
+**Responsibilities:**
+- Filter tickets by status, priority, region, date range
+- Filter users by role, organization, status
+- Filter inventory by type, location, availability
+- Support multiple filter combinations
+- Pagination and sorting
+
+**Filter Examples:**
+```
+GET /api/v1/tickets?status=open&priority=high&region_id=uuid&created_after=2024-01-01
+GET /api/v1/users?role=field_agent&contractor_id=uuid&status=active
+GET /api/v1/inventory?type=equipment&location=regional_hub&available=true
+```
+
+**Implementation:**
+```python
+# app/repositories/base_repository.py
+def apply_filters(query, filters):
+    for key, value in filters.items():
+        if key == 'status':
+            query = query.filter(Model.status == value)
+        elif key == 'created_after':
+            query = query.filter(Model.created_at >= value)
+        # ... more filters
+    return query
+```
+
+### 5.2 Full-Text Search
+
+**Responsibilities:**
+- Search tickets by customer name, address, description
+- Search users by name, email, phone
+- Search inventory by serial number, description
+- Support fuzzy matching and typo tolerance
+
+**Implementation:**
+```python
+# app/services/search_service.py
+- search_tickets(query, filters)
+- search_users(query, filters)
+- search_customers(query)
+- search_inventory(query)
+```
+
+**Endpoints:**
+```
+GET    /api/v1/search/tickets?q={query}
+GET    /api/v1/search/users?q={query}
+GET    /api/v1/search/customers?q={query}
+GET    /api/v1/search/global?q={query}
+```
+
+### 5.3 Autocomplete & Suggestions
+
+**Responsibilities:**
+- Provide autocomplete suggestions for search
+- Suggest customers based on partial phone number
+- Suggest locations based on partial address
+- Cache frequent searches
+
+**Endpoints:**
+```
+GET    /api/v1/autocomplete/customers?q={query}
+GET    /api/v1/autocomplete/locations?q={query}
+```
+
+---
+
+## 6. 💳 Payment Processing
+
+### 6.1 Expense Payments
+
+**Responsibilities:**
+- Process expense reimbursements to field agents
+- Support M-Pesa and bank transfer
+- Track payment status (pending, processing, completed, failed)
+- Handle payment failures and retries
+- Generate payment receipts
+
+**Payment Flow:**
+```
+1. Dispatcher approves expense
+2. Expense added to payment queue
+3. Backend initiates payment via M-Pesa/Bank
+4. Payment gateway returns transaction ID
+5. Backend polls for payment status
+6. On success: Update expense status, send notification
+7. On failure: Retry with exponential backoff (max 3 retries)
+```
+
+**Implementation:**
+```python
+# app/services/payment_service.py
+- initiate_expense_payment(expense_id)
+- process_payment_queue()
+- check_payment_status(transaction_id)
+- retry_failed_payment(payment_id)
+- generate_payment_receipt(payment_id)
+```
+
+**Endpoints:**
+```
+POST   /api/v1/payments/expenses/{expense_id}/pay
+GET    /api/v1/payments/{payment_id}/status
+POST   /api/v1/payments/{payment_id}/retry
+GET    /api/v1/payments/{payment_id}/receipt
+```
+
+### 6.2 Payroll Disbursement
+
+**Responsibilities:**
+- Process weekly payroll payments
+- Support bulk payments (100+ agents)
+- Validate payment details before processing
+- Handle partial failures (some succeed, some fail)
+- Generate payroll reports
+
+**Bulk Payment Flow:**
+```
+1. Payroll generated (Celery task)
+2. Payments added to queue
+3. Process in batches of 50
+4. For each batch:
+   - Validate payment details
+   - Initiate bulk payment via M-Pesa B2C
+   - Track individual payment statuses
+5. Generate success/failure report
+6. Retry failed payments
+7. Send notifications to agents
+```
+
+**Implementation:**
+```python
+# app/services/payroll_payment_service.py
+- process_payroll_payments(payroll_period_id)
+- validate_payment_batch(payments)
+- initiate_bulk_payment(payments)
+- handle_payment_callback(callback_data)
+- generate_payroll_report(payroll_period_id)
+```
+
+**Endpoints:**
+```
+POST   /api/v1/payroll/{period_id}/disburse
+GET    /api/v1/payroll/{period_id}/payment-status
+POST   /api/v1/payroll/{period_id}/retry-failed
+GET    /api/v1/payroll/{period_id}/report
+```
+
+### 6.3 Payment Webhooks
+
+**Responsibilities:**
+- Receive payment callbacks from M-Pesa
+- Validate webhook signatures
+- Update payment statuses
+- Trigger post-payment actions (notifications, reports)
+
+**Implementation:**
+```python
+# app/api/v1/webhooks.py
+@router.post("/webhooks/mpesa")
+async def mpesa_callback(payload: dict):
+    # 1. Validate signature
+    # 2. Parse payment result
+    # 3. Update payment status
+    # 4. Send notification
+    # 5. Log callback
+```
+
+---
+
+## 7. 🔄 Queue Management & Concurrency Control
+
+### 7.1 Task Queues (Celery)
+
+**Responsibilities:**
+- Process background tasks asynchronously
+- Retry failed tasks with exponential backoff
+- Monitor queue health and length
+- Prioritize critical tasks
+
+**Queue Types:**
+```python
+# High Priority Queue (SLA-critical)
+- ticket_assignment_notifications
+- sla_violation_alerts
+- payment_processing
+
+# Medium Priority Queue
+- email_notifications
+- report_generation
+- inventory_updates
+
+# Low Priority Queue
+- analytics_computation
+- data_cleanup
+- log_archival
+```
+
+**Implementation:**
+```python
+# app/tasks/celery_app.py
+celery_app.conf.task_routes = {
+    'app.tasks.notifications.*': {'queue': 'high_priority'},
+    'app.tasks.reports.*': {'queue': 'medium_priority'},
+    'app.tasks.analytics.*': {'queue': 'low_priority'},
+}
+```
+
+### 7.2 Optimistic Locking
+
+**Responsibilities:**
+- Prevent concurrent update conflicts
+- Use version field for conflict detection
+- Retry on conflict with fresh data
+- Inform user of conflicts
+
+**Implementation:**
+```python
+# app/models/base.py
+class BaseModel:
+    version = Column(Integer, default=1, nullable=False)
+
+# app/repositories/base_repository.py
+def update_with_optimistic_lock(id, updates, version):
+    result = db.query(Model).filter(
+        Model.id == id,
+        Model.version == version
+    ).update({
+        **updates,
+        'version': Model.version + 1
+    })
+    
+    if result == 0:
+        raise ConcurrentUpdateError("Record was modified by another user")
+    
+    db.commit()
+```
+
+**Use Cases:**
+- Inventory quantity updates
+- Ticket status changes
+- Payroll calculations
+- Financial transactions
+
+### 7.3 Distributed Locks (Redis)
+
+**Responsibilities:**
+- Prevent duplicate task execution
+- Ensure only one worker processes a task
+- Lock critical sections (payment processing)
+- Auto-release locks on timeout
+
+**Implementation:**
+```python
+# app/utils/distributed_lock.py
+from redis import Redis
+from contextlib import contextmanager
+
+@contextmanager
+def distributed_lock(lock_key, timeout=30):
+    redis_client = Redis()
+    lock = redis_client.lock(lock_key, timeout=timeout)
+    
+    try:
+        acquired = lock.acquire(blocking=True, blocking_timeout=10)
+        if not acquired:
+            raise LockAcquisitionError(f"Could not acquire lock: {lock_key}")
+        yield
+    finally:
+        lock.release()
+
+# Usage
+with distributed_lock(f"payroll_processing:{period_id}"):
+    process_payroll(period_id)
+```
+
+---
+
+## 8. 📊 CSV Parsing & Export
+
+### 8.1 CSV Import
+
+**Responsibilities:**
+- Parse CSV files for bulk data import
+- Validate data before import
+- Handle large files (10,000+ rows)
+- Provide detailed error reports
+- Support preview before import
+
+**Supported Imports:**
+- Sales orders (customer details, installation addresses)
+- Field agents (contact details, financial accounts)
+- Inventory (serial numbers, quantities)
+- Customers (bulk customer creation)
+
+**Implementation:**
+```python
+# app/services/csv_import_service.py
+def import_sales_orders_csv(file):
+    1. Parse CSV file
+    2. Validate headers
+    3. Validate each row
+    4. Deduplicate customers by phone
+    5. Create preview with errors
+    6. Return validation report
+    
+def confirm_csv_import(import_id):
+    1. Retrieve validated data
+    2. Create records in batches of 100
+    3. Track progress
+    4. Generate success/failure report
+    5. Return import summary
+```
+
+**Endpoints:**
+```
+POST   /api/v1/import/sales-orders/validate
+POST   /api/v1/import/sales-orders/confirm
+GET    /api/v1/import/{import_id}/status
+GET    /api/v1/import/{import_id}/errors
+POST   /api/v1/import/field-agents/validate
+POST   /api/v1/import/inventory/validate
+```
+
+### 8.2 CSV Export
+
+**Responsibilities:**
+- Export data to CSV format
+- Support large datasets (streaming)
+- Apply filters before export
+- Generate downloadable files
+- Clean up old exports
+
+**Supported Exports:**
+- Tickets (filtered by date, status, region)
+- Payroll reports (by period, agent)
+- Inventory reports (by location, type)
+- Financial reports (by project, date range)
+- Agent performance reports
+
+**Implementation:**
+```python
+# app/services/csv_export_service.py
+def export_tickets_csv(filters):
+    1. Apply filters to query
+    2. Stream results to CSV
+    3. Upload to temporary storage
+    4. Generate signed download URL
+    5. Schedule cleanup after 24 hours
+    6. Return download URL
+```
+
+**Endpoints:**
+```
+POST   /api/v1/export/tickets
+POST   /api/v1/export/payroll
+POST   /api/v1/export/inventory
+POST   /api/v1/export/financial-report
+GET    /api/v1/export/{export_id}/download
+```
+
+### 8.3 Excel Integration
+
+**Responsibilities:**
+- Generate Excel files with formatting
+- Support multiple sheets
+- Add charts and pivot tables
+- Password-protect sensitive reports
+
+**Implementation:**
+```python
+# app/services/excel_service.py
+- generate_excel_report(data, template)
+- add_formatting(workbook, styles)
+- create_pivot_table(worksheet, data_range)
+```
+
+---
+
+## 9. 🏥 Health Checks & Monitoring (V2 Feature)
+
+### 9.1 System Health Checks
+
+**Responsibilities:**
+- Monitor API server health
+- Check database connectivity
+- Check Redis connectivity
+- Check external service availability
+- Report system status
+
+**Health Check Endpoints:**
+```
+GET    /api/v1/health
+GET    /api/v1/health/database
+GET    /api/v1/health/redis
+GET    /api/v1/health/celery
+GET    /api/v1/health/external-services
+```
+
+**Health Check Response:**
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "checks": {
+    "database": {
+      "status": "healthy",
+      "response_time_ms": 15,
+      "connection_pool": {
+        "active": 5,
+        "idle": 15,
+        "max": 20
+      }
+    },
+    "redis": {
+      "status": "healthy",
+      "response_time_ms": 3
+    },
+    "celery": {
+      "status": "healthy",
+      "workers": 4,
+      "queue_length": {
+        "high_priority": 5,
+        "medium_priority": 23,
+        "low_priority": 102
+      }
+    },
+    "external_services": {
+      "supabase": "healthy",
+      "cloudinary": "healthy",
+      "mpesa": "degraded",
+      "resend": "healthy"
+    }
+  }
+}
+```
+
+### 9.2 Usage Monitoring
+
+**Responsibilities:**
+- Track API request counts
+- Monitor response times
+- Track error rates
+- Monitor resource usage (CPU, memory, disk)
+- Alert on anomalies
+
+**Metrics Tracked:**
+```python
+# Request Metrics
+- Total requests per endpoint
+- Average response time per endpoint
+- Error rate per endpoint
+- Requests per user/organization
+
+# Resource Metrics
+- Database connection pool usage
+- Redis memory usage
+- Celery queue lengths
+- Disk space usage
+
+# Business Metrics
+- Active users
+- Tickets created/completed per day
+- Payments processed per day
+- API calls per organization (for billing)
+```
+
+**Implementation:**
+```python
+# app/middleware/monitoring.py
+class MonitoringMiddleware:
+    async def __call__(self, request, call_next):
+        start_time = time.time()
+        
+        response = await call_next(request)
+        
+        duration = time.time() - start_time
+        
+        # Log metrics
+        metrics.record_request(
+            endpoint=request.url.path,
+            method=request.method,
+            status_code=response.status_code,
+            duration_ms=duration * 1000,
+            user_id=request.state.user_id
+        )
+        
+        return response
+```
+
+**Endpoints:**
+```
+GET    /api/v1/monitoring/metrics
+GET    /api/v1/monitoring/metrics/requests
+GET    /api/v1/monitoring/metrics/errors
+GET    /api/v1/monitoring/metrics/performance
+GET    /api/v1/monitoring/usage/by-organization
+```
+
+### 9.3 Infrastructure Monitoring
+
+**Responsibilities:**
+- Monitor Netlify deployment status
+- Monitor database performance (Supabase)
+- Monitor storage usage (Cloudinary)
+- Track API quota usage (Google Maps, M-Pesa)
+- Alert on quota limits
+
+**Monitored Services:**
+```python
+# Netlify
+- Deployment status
+- Build times
+- Bandwidth usage
+
+# Supabase
+- Database size
+- Connection count
+- Query performance
+- Storage usage
+
+# Cloudinary
+- Storage used
+- Bandwidth used
+- Transformations used
+
+# External APIs
+- Google Maps API calls
+- M-Pesa transaction count
+- Resend email quota
+- Africa's Talking SMS quota
+```
+
+**Endpoints:**
+```
+GET    /api/v1/monitoring/infrastructure
+GET    /api/v1/monitoring/infrastructure/netlify
+GET    /api/v1/monitoring/infrastructure/supabase
+GET    /api/v1/monitoring/infrastructure/cloudinary
+GET    /api/v1/monitoring/infrastructure/quotas
+```
+
+### 9.4 Alerting & Notifications
+
+**
+Responsibilities:**
+- Alert on system errors (500 errors, database failures)
+- Alert on performance degradation (slow queries, high latency)
+- Alert on quota limits (80% usage)
+- Alert on security events (failed login attempts, suspicious activity)
+- Send alerts via email, SMS, Slack
+
+**Alert Levels:**
+```python
+# Critical (Immediate action required)
+- Database connection failure
+- Payment gateway down
+- API server crash
+- Security breach detected
+
+# Warning (Action required soon)
+- High error rate (>5%)
+- Slow response times (>2s)
+- Queue backlog (>1000 items)
+- Quota at 80%
+
+# Info (Monitoring)
+- Deployment completed
+- Scheduled task completed
+- Daily summary reports
+```
+
+**Implementation:**
+```python
+# app/services/alerting_service.py
+def send_alert(level, title, message, channels):
+    if level == "critical":
+        send_email(ADMIN_EMAILS, title, message)
+        send_sms(ADMIN_PHONES, message)
+        send_slack(CRITICAL_CHANNEL, message)
+    elif level == "warning":
+        send_email(ADMIN_EMAILS, title, message)
+        send_slack(WARNING_CHANNEL, message)
+    else:
+        send_slack(INFO_CHANNEL, message)
+```
+
+---
+
+## 10. 🔒 Security Features
+
+### 10.1 Rate Limiting
+
+**Responsibilities:**
+- Limit API requests per user/IP
+- Prevent brute force attacks
+- Protect against DDoS
+- Different limits for different endpoints
+
+**Rate Limits:**
+```python
+# Authentication endpoints
+- Login: 5 requests per 5 minutes per IP
+- OTP generation: 3 requests per 5 minutes per user
+- Password reset: 3 requests per hour per email
+
+# General API
+- Standard endpoints: 1000 requests per hour per user
+- Search endpoints: 100 requests per minute per user
+- Export endpoints: 10 requests per hour per user
+
+# Webhooks
+- Payment callbacks: 1000 requests per hour per IP
+```
+
+**Implementation:**
+```python
+# app/middleware/rate_limiting.py
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+
+@app.post("/api/v1/auth/login")
+@limiter.limit("5/5minutes")
+async def login(request: Request):
+    pass
+```
+
+### 10.2 Input Validation & Sanitization
+
+**Responsibilities:**
+- Validate all input data using Pydantic
+- Sanitize user input to prevent XSS
+- Validate file uploads (type, size, content)
+- Prevent SQL injection (using ORM)
+
+**Implementation:**
+```python
+# app/schemas/ticket.py
+from pydantic import BaseModel, validator, Field
+
+class TicketCreate(BaseModel):
+    title: str = Field(..., min_length=5, max_length=200)
+    description: str = Field(..., max_length=2000)
+    priority: str = Field(..., regex="^(low|medium|high|critical)$")
+    
+    @validator('title', 'description')
+    def sanitize_html(cls, v):
+        return bleach.clean(v, tags=[], strip=True)
+```
+
+### 10.3 Audit Logging
+
+**Responsibilities:**
+- Log all critical operations
+- Track who did what and when
+- Immutable audit trail
+- Compliance reporting
+
+**Logged Operations:**
+```python
+# Financial Operations
+- Payment processing
+- Payroll generation
+- Expense approval
+- Invoice creation
+
+# Security Operations
+- User login/logout
+- Role changes
+- Permission grants
+- Password changes
+
+# Data Operations
+- Record deletion
+- Bulk updates
+- Data exports
+- Configuration changes
+```
+
+**Implementation:**
+```python
+# app/models/audit_log.py
+class AuditLog(Base):
+    id = Column(UUID, primary_key=True)
+    user_id = Column(UUID, nullable=False)
+    action = Column(String(100), nullable=False)
+    entity_type = Column(String(50), nullable=False)
+    entity_id = Column(UUID, nullable=True)
+    old_values = Column(JSONB, nullable=True)
+    new_values = Column(JSONB, nullable=True)
+    ip_address = Column(String(45), nullable=True)
+    user_agent = Column(Text, nullable=True)
+    created_at = Column(DateTime, nullable=False)
+
+# app/services/audit_service.py
+def log_action(user_id, action, entity_type, entity_id, old_values, new_values):
+    audit_log = AuditLog(
+        user_id=user_id,
+        action=action,
+        entity_type=entity_type,
+        entity_id=entity_id,
+        old_values=old_values,
+        new_values=new_values,
+        ip_address=request.client.host,
+        user_agent=request.headers.get("user-agent"),
+        created_at=datetime.utcnow()
+    )
+    db.add(audit_log)
+    db.commit()
+```
+
+**Endpoints:**
+```
+GET    /api/v1/audit-logs
+GET    /api/v1/audit-logs/user/{user_id}
+GET    /api/v1/audit-logs/entity/{entity_type}/{entity_id}
+POST   /api/v1/audit-logs/export
+```
+
+### 10.4 Data Encryption
+
+**Responsibilities:**
+- Encrypt sensitive data at rest
+- Encrypt data in transit (HTTPS)
+- Encrypt database backups
+- Secure key management
+
+**Encrypted Fields:**
+```python
+# User Data
+- Financial account numbers
+- ID numbers
+- Tax information
+
+# Payment Data
+- M-Pesa transaction details
+- Bank account numbers
+
+# Sensitive Documents
+- Contracts
+- Legal documents
+```
+
+**Implementation:**
+```python
+# app/utils/encryption.py
+from cryptography.fernet import Fernet
+
+def encrypt_field(value: str) -> str:
+    cipher = Fernet(ENCRYPTION_KEY)
+    return cipher.encrypt(value.encode()).decode()
+
+def decrypt_field(encrypted_value: str) -> str:
+    cipher = Fernet(ENCRYPTION_KEY)
+    return cipher.decrypt(encrypted_value.encode()).decode()
+```
+
+---
+
+## 11. 🔄 Data Synchronization & Caching
+
+### 11.1 Redis Caching Strategy
+
+**Responsibilities:**
+- Cache frequently accessed data
+- Reduce database load
+- Improve response times
+- Invalidate cache on updates
+
+**Cached Data:**
+```python
+# User Sessions (TTL: 24 hours)
+cache_key = f"user_session:{user_id}"
+
+# Dashboard Metrics (TTL: 5 minutes)
+cache_key = f"dashboard_metrics:{project_id}"
+
+# Project Settings (TTL: 1 hour)
+cache_key = f"project_settings:{project_id}"
+
+# Agent Locations (TTL: 1 minute)
+cache_key = f"agent_location:{agent_id}"
+
+# SLA Thresholds (TTL: 1 hour)
+cache_key = f"sla_thresholds:{project_id}"
+```
+
+**Implementation:**
+```python
+# app/utils/cache.py
+from redis import Redis
+import json
+
+redis_client = Redis.from_url(REDIS_URL)
+
+def cache_get(key: str):
+    value = redis_client.get(key)
+    return json.loads(value) if value else None
+
+def cache_set(key: str, value: any, ttl: int = 300):
+    redis_client.setex(key, ttl, json.dumps(value))
+
+def cache_delete(key: str):
+    redis_client.delete(key)
+
+def cache_delete_pattern(pattern: str):
+    keys = redis_client.keys(pattern)
+    if keys:
+        redis_client.delete(*keys)
+```
+
+### 11.2 Cache Invalidation
+
+**Responsibilities:**
+- Invalidate cache when data changes
+- Support pattern-based invalidation
+- Prevent stale data
+
+**Invalidation Triggers:**
+```python
+# Ticket updated → Invalidate ticket cache + dashboard cache
+cache_delete(f"ticket:{ticket_id}")
+cache_delete_pattern(f"dashboard_metrics:{project_id}*")
+
+# User role changed → Invalidate user session
+cache_delete(f"user_session:{user_id}")
+
+# Project settings updated → Invalidate project cache
+cache_delete(f"project_settings:{project_id}")
+```
+
+### 11.3 Database Query Optimization
+
+**Responsibilities:**
+- Use database indexes effectively
+- Optimize N+1 queries with eager loading
+- Use database views for complex queries
+- Implement query result caching
+
+**Implementation:**
+```python
+# app/repositories/ticket_repository.py
+def get_tickets_with_relations(project_id):
+    # Use eager loading to prevent N+1 queries
+    return db.query(Ticket)\
+        .options(
+            joinedload(Ticket.customer),
+            joinedload(Ticket.assigned_agent),
+            joinedload(Ticket.project)
+        )\
+        .filter(Ticket.project_id == project_id)\
+        .all()
+```
+
+---
+
+## 12. 📱 Mobile API Optimizations
+
+### 12.1 Lightweight Responses
+
+**Responsibilities:**
+- Return only necessary fields for mobile
+- Support field selection (?fields=id,title,status)
+- Compress responses (gzip)
+- Optimize image URLs (thumbnails)
+
+**Implementation:**
+```python
+# app/api/v1/tickets.py
+@router.get("/tickets/{ticket_id}")
+async def get_ticket(
+    ticket_id: UUID,
+    fields: Optional[str] = None
+):
+    ticket = ticket_service.get_ticket(ticket_id)
+    
+    if fields:
+        # Return only requested fields
+        field_list = fields.split(',')
+        return {k: v for k, v in ticket.dict().items() if k in field_list}
+    
+    return ticket
+```
+
+### 12.2 Offline Support
+
+**Responsibilities:**
+- Queue operations when offline
+- Sync when connection restored
+- Handle conflicts (optimistic locking)
+- Provide offline-first endpoints
+
+**Offline Operations:**
+```python
+# Operations that work offline (queued)
+- Update ticket status
+- Log expenses
+- Add photos
+- Record location updates
+- Clock in/out
+
+# Operations that require online
+- Create new tickets
+- Assign tickets
+- Process payments
+- Generate reports
+```
+
+**Sync Endpoint:**
+```
+POST   /api/v1/sync/queue
+```
+
+**Request:**
+```json
+{
+  "operations": [
+    {
+      "id": "local_uuid_1",
+      "type": "update_ticket_status",
+      "entity_id": "ticket_uuid",
+      "data": {"status": "in_progress"},
+      "timestamp": "2024-01-15T10:30:00Z"
+    },
+    {
+      "id": "local_uuid_2",
+      "type": "log_expense",
+      "entity_id": "ticket_uuid",
+      "data": {"amount": 500, "category": "transport"},
+      "timestamp": "2024-01-15T11:00:00Z"
+    }
+  ]
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "local_id": "local_uuid_1",
+      "status": "success",
+      "server_id": "ticket_uuid"
+    },
+    {
+      "local_id": "local_uuid_2",
+      "status": "conflict",
+      "error": "Ticket already completed by another user",
+      "server_data": {...}
+    }
+  ]
+}
+```
+
+### 12.3 Data Compression
+
+**Responsibilities:**
+- Compress API responses (gzip)
+- Optimize JSON payloads
+- Use efficient data formats
+- Support delta updates
+
+**Implementation:**
+```python
+# app/middleware/compression.py
+from fastapi.middleware.gzip import GZipMiddleware
+
+app.add_middleware(GZipMiddleware, minimum_size=1000)
+```
+
+---
+
+## 13. 🔧 Background Jobs & Scheduled Tasks
+
+### 13.1 Scheduled Tasks (Celery Beat)
+
+**Daily Tasks:**
+```python
+# Midnight (00:00)
+- compute_daily_metrics()
+- cleanup_old_exports()
+- archive_old_logs()
+- send_daily_summary_reports()
+
+# 6:00 AM
+- check_sla_violations()
+- send_morning_briefing_to_managers()
+
+# Every Hour
+- monitor_sla_deadlines()
+- sync_payment_statuses()
+- cleanup_expired_otps()
+```
+
+**Weekly Tasks:**
+```python
+# Friday 6:00 PM
+- generate_weekly_payroll()
+- send_payroll_notifications()
+
+# Sunday 11:00 PM
+- generate_weekly_reports()
+- send_weekly_summary_to_admins()
+```
+
+**Monthly Tasks:**
+```python
+# Last day of month
+- generate_contractor_invoices()
+- generate_monthly_reports()
+- archive_old_data()
+```
+
+**Implementation:**
+```python
+# app/tasks/celery_app.py
+from celery.schedules import crontab
+
+celery_app.conf.beat_schedule = {
+    'generate-weekly-payroll': {
+        'task': 'app.tasks.payroll_tasks.generate_weekly_payroll',
+        'schedule': crontab(day_of_week=5, hour=18, minute=0),
+    },
+    'monitor-sla-violations': {
+        'task': 'app.tasks.sla_tasks.monitor_sla_violations',
+        'schedule': crontab(minute=0),  # Every hour
+    },
+    'compute-daily-metrics': {
+        'task': 'app.tasks.analytics_tasks.compute_daily_metrics',
+        'schedule': crontab(hour=0, minute=0),  # Midnight
+    },
+}
+```
+
+### 13.2 Async Task Processing
+
+**Long-Running Tasks:**
+```python
+# CSV Import (10,000+ rows)
+- Parse and validate CSV
+- Create records in batches
+- Generate import report
+
+# Report Generation
+- Query large datasets
+- Generate Excel/PDF
+- Upload to storage
+- Send download link
+
+# Bulk Operations
+- Bulk ticket assignment
+- Bulk payment processing
+- Bulk email sending
+```
+
+**Implementation:**
+```python
+# app/tasks/import_tasks.py
+@celery_app.task(bind=True)
+def import_sales_orders_task(self, import_id, file_path):
+    try:
+        # Update progress
+        self.update_state(state='PROGRESS', meta={'progress': 0})
+        
+        # Process CSV
+        results = process_csv(file_path)
+        
+        # Update progress
+        self.update_state(state='PROGRESS', meta={'progress': 50})
+        
+        # Create records
+        create_records(results)
+        
+        # Update progress
+        self.update_state(state='PROGRESS', meta={'progress': 100})
+        
+        return {'status': 'completed', 'imported': len(results)}
+    except Exception as e:
+        self.update_state(state='FAILURE', meta={'error': str(e)})
+        raise
+```
+
+**Task Status Endpoint:**
+```
+GET    /api/v1/tasks/{task_id}/status
+```
+
+**Response:**
+```json
+{
+  "task_id": "uuid",
+  "status": "PROGRESS",
+  "progress": 50,
+  "result": null,
+  "error": null
+}
+```
+
+---
+
+## 14. 🌐 External Service Integrations
+
+### 14.1 Supabase Integration
+
+**Services Used:**
+- **Auth**: User authentication and JWT tokens
+- **Database**: PostgreSQL with Row-Level Security
+- **Storage**: File uploads (documents, receipts)
+- **Realtime**: WebSocket subscriptions (optional)
+
+**Implementation:**
+```python
+# app/integrations/supabase.py
+from supabase import create_client
+
+supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
+
+# Auth
+def verify_supabase_token(token):
+    return supabase.auth.get_user(token)
+
+# Storage
+def upload_to_supabase_storage(file, bucket, path):
+    return supabase.storage.from_(bucket).upload(path, file)
+
+# Database (for simple queries)
+def query_supabase(table, filters):
+    return supabase.table(table).select('*').match(filters).execute()
+```
+
+### 14.2 Cloudinary Integration
+
+**Services Used:**
+- Image uploads
+- Image transformations
+- CDN delivery
+- Video uploads (future)
+
+**Implementation:**
+```python
+# app/integrations/cloudinary.py
+import cloudinary
+import cloudinary.uploader
+
+cloudinary.config(
+    cloud_name=CLOUDINARY_CLOUD_NAME,
+    api_key=CLOUDINARY_API_KEY,
+    api_secret=CLOUDINARY_API_SECRET
+)
+
+def upload_image(file, folder, public_id=None):
+    result = cloudinary.uploader.upload(
+        file,
+        folder=folder,
+        public_id=public_id,
+        resource_type="image",
+        transformation=[
+            {'width': 1920, 'height': 1080, 'crop': 'limit'},
+            {'quality': 'auto'},
+            {'fetch_format': 'auto'}
+        ]
+    )
+    return result['secure_url']
+```
+
+### 14.3 M-Pesa Integration
+
+**Services Used:**
+- B2C payments (business to customer)
+- Payment status queries
+- Transaction callbacks
+
+**Implementation:**
+```python
+# app/integrations/mpesa.py
+import requests
+import base64
+
+def get_mpesa_access_token():
+    url = "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials"
+    response = requests.get(url, auth=(MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET))
+    return response.json()['access_token']
+
+def initiate_b2c_payment(phone_number, amount, remarks):
+    access_token = get_mpesa_access_token()
+    
+    payload = {
+        "InitiatorName": MPESA_INITIATOR_NAME,
+        "SecurityCredential": MPESA_SECURITY_CREDENTIAL,
+        "CommandID": "BusinessPayment",
+        "Amount": amount,
+        "PartyA": MPESA_SHORTCODE,
+        "PartyB": phone_number,
+        "Remarks": remarks,
+        "QueueTimeOutURL": f"{API_BASE_URL}/webhooks/mpesa/timeout",
+        "ResultURL": f"{API_BASE_URL}/webhooks/mpesa/result",
+        "Occasion": ""
+    }
+    
+    headers = {"Authorization": f"Bearer {access_token}"}
+    response = requests.post(MPESA_B2C_URL, json=payload, headers=headers)
+    return response.json()
+```
+
+### 14.4 Resend Integration
+
+**Services Used:**
+- Transactional emails
+- Email templates
+- Delivery tracking
+
+**Implementation:**
+```python
+# app/integrations/resend.py
+import resend
+
+resend.api_key = RESEND_API_KEY
+
+def send_email(to, subject, html):
+    return resend.Emails.send({
+        "from": "SwiftOps <noreply@swiftops.com>",
+        "to": to,
+        "subject": subject,
+        "html": html
+    })
+
+def send_templated_email(to, template_id, variables):
+    return resend.Emails.send({
+        "from": "SwiftOps <noreply@swiftops.com>",
+        "to": to,
+        "template_id": template_id,
+        "template_data": variables
+    })
+```
+
+### 14.5 Google Maps Integration
+
+**Services Used:**
+- Geocoding (address → coordinates)
+- Reverse geocoding (coordinates → address)
+- Distance calculation
+- Directions API
+
+**Implementation:**
+```python
+# app/integrations/google_maps.py
+import googlemaps
+
+gmaps = googlemaps.Client(key=GOOGLE_MAPS_API_KEY)
+
+def geocode_address(address):
+    result = gmaps.geocode(address)
+    if result:
+        location = result[0]['geometry']['location']
+        return location['lat'], location['lng']
+    return None, None
+
+def calculate_distance(origin, destination):
+    result = gmaps.distance_matrix(origin, destination, mode="driving")
+    if result['rows']:
+        element = result['rows'][0]['elements'][0]
+        return {
+            'distance_meters': element['distance']['value'],
+            'duration_seconds': element['duration']['value']
+        }
+    return None
+```
+
+---
+
+## 15. 📋 Implementation Priority
+
+### Phase 1: Core Backend (Weeks 1-4)
+1. ✅ Authentication & JWT
+2. ✅ Supabase integration
+3. ✅ Basic CRUD operations
+4. ✅ Role-based access control
+5. ✅ Database models and migrations
+
+### Phase 2: Essential Features (Weeks 5-8)
+1. 🔄 Email service (Resend)
+2. 🔄 OTP & 2FA
+3. 🔄 Media management (Cloudinary)
+4. 🔄 Payment processing (M-Pesa)
+5. 🔄 CSV import/export
+
+### Phase 3: Advanced Features (Weeks 9-12)
+1. 📋 Queue management (Celery)
+2. 📋 Background tasks
+3. 📋 Caching (Redis)
+4. 📋 Filtering & search
+5. 📋 Optimistic locking
+
+### Phase 4: V2 Features (Weeks 13-16)
+1. 📋 SMS service (Africa's Talking)
+2. 📋 Intelligent agent allocation
+3. 📋 Route optimization
+4. 📋 Health checks & monitoring
+5. 📋 Usage tracking
+
+### Phase 5: Polish & Optimization (Weeks 17-20)
+1. 📋 Performance optimization
+2. 📋 Security hardening
+3. 📋 Documentation
+4. 📋 Testing (80% coverage)
+5. 📋 Deployment automation
+
+---
+
+## 16. 🔑 Environment Variables Required
+
+```bash
+# Application
+APP_NAME=SwiftOps API
+DEBUG=False
+ENVIRONMENT=production
+SECRET_KEY=your-secret-key-here
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=1440
+
+# Database (Supabase)
+DATABASE_URL=postgresql://user:password@host:5432/dbname
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your-anon-key
+SUPABASE_SERVICE_KEY=your-service-role-key
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+
+# Celery
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/0
+
+# Cloudinary
+CLOUDINARY_CLOUD_NAME=your-cloud-name
+CLOUDINARY_API_KEY=your-api-key
+CLOUDINARY_API_SECRET=your-api-secret
+
+# M-Pesa
+MPESA_CONSUMER_KEY=your-mpesa-key
+MPESA_CONSUMER_SECRET=your-mpesa-secret
+MPESA_SHORTCODE=174379
+MPESA_PASSKEY=your-passkey
+MPESA_INITIATOR_NAME=your-initiator
+MPESA_SECURITY_CREDENTIAL=your-credential
+
+# Resend
+RESEND_API_KEY=your-resend-key
+
+# Africa's Talking (V2)
+AFRICASTALKING_USERNAME=your-username
+AFRICASTALKING_API_KEY=your-api-key
+
+# Google Maps
+GOOGLE_MAPS_API_KEY=your-google-maps-key
+
+# Monitoring (V2)
+SENTRY_DSN=your-sentry-dsn
+```
+
+---
+
+## 17. 📊 Success Metrics
+
+### Technical Metrics
+- API response time < 200ms (p95)
+- Database query time < 50ms (p95)
+- Cache hit rate > 80%
+- Test coverage > 80%
+- Zero critical security vulnerabilities
+- 99.9% uptime
+
+### Business Metrics
+- Support 1000+ concurrent field agents
+- Process 10,000+ tickets per month
+- Handle 500+ payroll payments per week
+- 95% SLA compliance rate
+- < 1% payment failure rate
+
+---
+
+## 18. 🚀 Deployment Checklist
+
+### Pre-Deployment
+- [ ] All environment variables configured
+- [ ] Database migrations tested
+- [ ] Redis connection verified
+- [ ] Celery workers configured
+- [ ] External services tested (M-Pesa, Cloudinary, Resend)
+- [ ] SSL certificates configured
+- [ ] Monitoring setup (Sentry)
+- [ ] Backup strategy implemented
+
+### Post-Deployment
+- [ ] Health checks passing
+- [ ] API documentation accessible
+- [ ] Webhooks configured
+- [ ] Scheduled tasks running
+- [ ] Logs being collected
+- [ ] Alerts configured
+- [ ] Performance monitoring active
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** November 2025  
+**Maintained By:** SwiftOps Backend Team

docs/prod/CREDENTIALS_SETUP_GUIDE.md

@@ -0,0 +1,734 @@
+# SwiftOps Backend - Credentials & Services Setup Guide
+
+**Version:** 1.0  
+**Last Updated:** November 2025  
+**Purpose:** Step-by-step guide to set up all external services and obtain required credentials
+
+---
+
+## Overview
+
+This guide walks you through setting up all external services required for the SwiftOps backend. Follow each section in order to obtain all necessary API keys and credentials.
+
+**Estimated Time:** 2-3 hours  
+**Cost:** Most services have free tiers suitable for development
+
+---
+
+## 1. 🗄️ Supabase (Database & Auth)
+
+**What you need:**
+- Database URL
+- Anon Key (public)
+- Service Role Key (private)
+- JWT Secret
+
+### Setup Steps:
+
+1. **Create Account**
+   - Go to [https://supabase.com](https://supabase.com)
+   - Click "Start your project"
+   - Sign up with GitHub, Google, or email
+
+2. **Create New Project**
+   - Click "New Project"
+   - Choose your organization (or create one)
+   - Fill in project details:
+     - **Name:** `swiftops-production` (or `swiftops-dev` for development)
+     - **Database Password:** Generate a strong password (save this!)
+     - **Region:** Choose closest to your users (e.g., `eu-west-1` for Europe)
+   - Click "Create new project"
+   - Wait 2-3 minutes for provisioning
+
+3. **Get Database Credentials**
+   - Go to **Settings** → **Database**
+   - Under "Connection string", select **URI**
+   - Copy the connection string (looks like):
+     ```
+     postgresql://postgres:[YOUR-PASSWORD]@db.xxxxx.supabase.co:5432/postgres
+     ```
+   - Replace `[YOUR-PASSWORD]` with your database password
+   - Save as `DATABASE_URL`
+
+4. **Get API Keys**
+   - Go to **Settings** → **API**
+   - Copy the following:
+     - **Project URL** → Save as `SUPABASE_URL`
+     - **anon public** key → Save as `SUPABASE_KEY`
+     - **service_role** key → Save as `SUPABASE_SERVICE_KEY` (⚠️ Keep secret!)
+
+5. **Get JWT Secret**
+   - Still in **Settings** → **API**
+   - Scroll down to "JWT Settings"
+   - Copy **JWT Secret** → Save as `SUPABASE_JWT_SECRET`
+
+6. **Configure Auth Providers** (Optional)
+   - Go to **Authentication** → **Providers**
+   - Enable email/password authentication
+   - Configure OAuth providers if needed (Google, GitHub, etc.)
+
+### Environment Variables:
+```bash
+DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@db.xxxxx.supabase.co:5432/postgres
+SUPABASE_URL=https://xxxxx.supabase.co
+SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_JWT_SECRET=your-jwt-secret-here
+```
+
+---
+
+## 2. ☁️ Cloudinary (Image Storage)
+
+**What you need:**
+- Cloud Name
+- API Key
+- API Secret
+
+### Setup Steps:
+
+1. **Create Account**
+   - Go to [https://cloudinary.com](https://cloudinary.com)
+   - Click "Sign Up Free"
+   - Sign up with email or Google
+
+2. **Verify Email**
+   - Check your email for verification link
+   - Click to verify your account
+
+3. **Get Credentials**
+   - After login, you'll see the **Dashboard**
+   - Find "Account Details" section (top right)
+   - Copy the following:
+     - **Cloud Name** → Save as `CLOUDINARY_CLOUD_NAME`
+     - **API Key** → Save as `CLOUDINARY_API_KEY`
+     - **API Secret** → Save as `CLOUDINARY_API_SECRET` (click "eye" icon to reveal)
+
+4. **Configure Upload Settings** (Optional)
+   - Go to **Settings** → **Upload**
+   - Set upload presets if needed
+   - Configure folder structure:
+     - `/swiftops/tickets/`
+     - `/swiftops/users/`
+     - `/swiftops/receipts/`
+
+5. **Set Up Transformations** (Optional)
+   - Go to **Settings** → **Upload**
+   - Create named transformations:
+     - `thumbnail`: 150x150, quality 80
+     - `medium`: 800x600, quality 85
+     - `large`: 1920x1080, quality 90
+
+### Environment Variables:
+```bash
+CLOUDINARY_CLOUD_NAME=your-cloud-name
+CLOUDINARY_API_KEY=123456789012345
+CLOUDINARY_API_SECRET=abcdefghijklmnopqrstuvwxyz123456
+```
+
+### Free Tier Limits:
+- 25 GB storage
+- 25 GB bandwidth/month
+- 25,000 transformations/month
+
+---
+
+## 3. 📧 Resend (Email Service)
+
+**What you need:**
+- API Key
+- Verified domain (optional for production)
+
+### Setup Steps:
+
+1. **Create Account**
+   - Go to [https://resend.com](https://resend.com)
+   - Click "Get Started"
+   - Sign up with email or GitHub
+
+2. **Verify Email**
+   - Check your email for verification link
+   - Click to verify
+
+3. **Get API Key**
+   - After login, go to **API Keys**
+   - Click "Create API Key"
+   - Name it: `swiftops-production` (or `swiftops-dev`)
+   - Select permissions: **Full Access** (or **Sending access** only)
+   - Click "Create"
+   - Copy the API key (shown only once!) → Save as `RESEND_API_KEY`
+
+4. **Add Domain** (For Production)
+   - Go to **Domains**
+   - Click "Add Domain"
+   - Enter your domain: `swiftops.com`
+   - Follow DNS verification steps:
+     - Add TXT record to your DNS
+     - Add CNAME records for DKIM
+     - Wait for verification (can take up to 48 hours)
+
+5. **Test Email** (Development)
+   - For development, you can send from `onboarding@resend.dev`
+   - For production, use your verified domain: `noreply@swiftops.com`
+
+### Environment Variables:
+```bash
+RESEND_API_KEY=re_123456789abcdefghijklmnop
+FROM_EMAIL=noreply@swiftops.com
+```
+
+### Free Tier Limits:
+- 100 emails/day
+- 3,000 emails/month
+
+---
+
+## 4. 💳 M-Pesa (Payment Gateway) - Kenya
+
+**What you need:**
+- Consumer Key
+- Consumer Secret
+- Shortcode
+- Passkey
+- Initiator Name
+- Security Credential
+
+### Setup Steps:
+
+1. **Create Safaricom Developer Account**
+   - Go to [https://developer.safaricom.co.ke](https://developer.safaricom.co.ke)
+   - Click "Sign Up"
+   - Fill in your details
+   - Verify your email
+
+2. **Create App (Sandbox)**
+   - Login to developer portal
+   - Go to **My Apps**
+   - Click "Create App"
+   - Fill in details:
+     - **App Name:** SwiftOps Backend
+     - **Description:** Field service management platform
+   - Select APIs:
+     - ✅ M-Pesa Sandbox
+     - ✅ M-Pesa B2C (Business to Customer)
+   - Click "Create App"
+
+3. **Get Sandbox Credentials**
+   - Go to your app details
+   - Under "Keys", copy:
+     - **Consumer Key** → Save as `MPESA_CONSUMER_KEY`
+     - **Consumer Secret** → Save as `MPESA_CONSUMER_SECRET`
+
+4. **Get Test Credentials**
+   - Go to **Test Credentials** tab
+   - Copy the following:
+     - **Shortcode** → Save as `MPESA_SHORTCODE` (usually `174379` for sandbox)
+     - **Passkey** → Save as `MPESA_PASSKEY`
+     - **Initiator Name** → Save as `MPESA_INITIATOR_NAME` (usually `testapi`)
+     - **Security Credential** → Save as `MPESA_SECURITY_CREDENTIAL`
+
+5. **Configure Callback URLs**
+   - In your app settings, add callback URLs:
+     - **Validation URL:** `https://your-api.com/api/v1/webhooks/mpesa/validation`
+     - **Confirmation URL:** `https://your-api.com/api/v1/webhooks/mpesa/confirmation`
+     - **Result URL:** `https://your-api.com/api/v1/webhooks/mpesa/result`
+     - **Timeout URL:** `https://your-api.com/api/v1/webhooks/mpesa/timeout`
+
+6. **Go Live (Production)**
+   - Once tested, apply for production access
+   - Go to **Go Live** section
+   - Fill in business details
+   - Submit for approval (takes 2-5 business days)
+   - Once approved, get production credentials
+
+### Environment Variables:
+```bash
+# Sandbox
+MPESA_ENVIRONMENT=sandbox
+MPESA_CONSUMER_KEY=your-consumer-key
+MPESA_CONSUMER_SECRET=your-consumer-secret
+MPESA_SHORTCODE=174379
+MPESA_PASSKEY=your-passkey
+MPESA_INITIATOR_NAME=testapi
+MPESA_SECURITY_CREDENTIAL=your-security-credential
+
+# Production (after approval)
+MPESA_ENVIRONMENT=production
+MPESA_CONSUMER_KEY=your-prod-consumer-key
+MPESA_CONSUMER_SECRET=your-prod-consumer-secret
+MPESA_SHORTCODE=your-business-shortcode
+MPESA_PASSKEY=your-prod-passkey
+MPESA_INITIATOR_NAME=your-initiator-name
+MPESA_SECURITY_CREDENTIAL=your-prod-security-credential
+```
+
+### Important Notes:
+- Sandbox is for testing only (uses test phone numbers)
+- Production requires business registration and approval
+- Keep security credentials encrypted and secure
+
+---
+
+## 5. 📱 Africa's Talking (SMS Service) - V2 Feature
+
+**What you need:**
+- Username
+- API Key
+
+### Setup Steps:
+
+1. **Create Account**
+   - Go to [https://africastalking.com](https://africastalking.com)
+   - Click "Sign Up"
+   - Choose your country (Kenya, Uganda, etc.)
+   - Fill in your details
+   - Verify your email
+
+2. **Get Sandbox Credentials**
+   - After login, go to **Sandbox**
+   - You'll see:
+     - **Username:** `sandbox` → Save as `AFRICASTALKING_USERNAME`
+     - **API Key:** Click "Generate" → Save as `AFRICASTALKING_API_KEY`
+
+3. **Test SMS**
+   - In sandbox, you can only send to test numbers
+   - Add test numbers in **Sandbox** → **Simulator**
+
+4. **Go Live (Production)**
+   - Go to **Go Live** section
+   - Fill in business details
+   - Add payment method
+   - Purchase SMS credits
+   - Get production credentials:
+     - **Username:** Your chosen username
+     - **API Key:** Generate new production key
+
+### Environment Variables:
+```bash
+# Sandbox
+AFRICASTALKING_USERNAME=sandbox
+AFRICASTALKING_API_KEY=your-sandbox-api-key
+AFRICASTALKING_ENVIRONMENT=sandbox
+
+# Production
+AFRICASTALKING_USERNAME=your-username
+AFRICASTALKING_API_KEY=your-production-api-key
+AFRICASTALKING_ENVIRONMENT=production
+```
+
+### Pricing (Kenya):
+- KES 0.80 per SMS (local)
+- Buy credits in bulk for discounts
+
+---
+
+## 6. 🗺️ Google Maps Platform
+
+**What you need:**
+- API Key with enabled services
+
+### Setup Steps:
+
+1. **Create Google Cloud Account**
+   - Go to [https://console.cloud.google.com](https://console.cloud.google.com)
+   - Sign in with Google account
+   - Accept terms of service
+
+2. **Create New Project**
+   - Click project dropdown (top left)
+   - Click "New Project"
+   - Name: `swiftops-backend`
+   - Click "Create"
+
+3. **Enable Billing**
+   - Go to **Billing**
+   - Click "Link a billing account"
+   - Add payment method (credit card)
+   - Note: Google gives $300 free credits for 90 days
+
+4. **Enable APIs**
+   - Go to **APIs & Services** → **Library**
+   - Search and enable the following:
+     - ✅ **Maps JavaScript API**
+     - ✅ **Geocoding API**
+     - ✅ **Distance Matrix API**
+     - ✅ **Directions API**
+     - ✅ **Places API** (optional)
+
+5. **Create API Key**
+   - Go to **APIs & Services** → **Credentials**
+   - Click "Create Credentials" → "API Key"
+   - Copy the API key → Save as `GOOGLE_MAPS_API_KEY`
+
+6. **Restrict API Key** (Important!)
+   - Click on your API key to edit
+   - Under "Application restrictions":
+     - Select "IP addresses"
+     - Add your server IP addresses
+   - Under "API restrictions":
+     - Select "Restrict key"
+     - Select only the APIs you enabled
+   - Click "Save"
+
+### Environment Variables:
+```bash
+GOOGLE_MAPS_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+### Free Tier:
+- $200 free credits per month
+- Geocoding: $5 per 1,000 requests (40,000 free/month)
+- Distance Matrix: $5 per 1,000 requests (40,000 free/month)
+
+---
+
+## 7. 🔴 Redis (Caching & Queue)
+
+**What you need:**
+- Redis URL
+
+### Option A: Local Redis (Development)
+
+1. **Install Redis**
+   - **Windows:** Download from [https://github.com/microsoftarchive/redis/releases](https://github.com/microsoftarchive/redis/releases)
+   - **Mac:** `brew install redis`
+   - **Linux:** `sudo apt-get install redis-server`
+
+2. **Start Redis**
+   - **Windows:** Run `redis-server.exe`
+   - **Mac/Linux:** `redis-server`
+
+3. **Test Connection**
+   ```bash
+   redis-cli ping
+   # Should return: PONG
+   ```
+
+### Environment Variables:
+```bash
+REDIS_URL=redis://localhost:6379/0
+```
+
+### Option B: Redis Cloud (Production)
+
+1. **Create Account**
+   - Go to [https://redis.com/try-free](https://redis.com/try-free)
+   - Sign up with email or Google
+
+2. **Create Database**
+   - Click "New Database"
+   - Choose "Free" plan (30MB)
+   - Select region closest to your server
+   - Click "Create"
+
+3. **Get Connection URL**
+   - Click on your database
+   - Copy "Public endpoint"
+   - Format: `redis://default:password@redis-12345.c1.us-east-1-2.ec2.cloud.redislabs.com:12345`
+   - Save as `REDIS_URL`
+
+### Environment Variables:
+```bash
+REDIS_URL=redis://default:password@redis-12345.cloud.redislabs.com:12345
+```
+
+---
+
+## 8. 📊 Sentry (Error Tracking) - Optional
+
+**What you need:**
+- DSN (Data Source Name)
+
+### Setup Steps:
+
+1. **Create Account**
+   - Go to [https://sentry.io](https://sentry.io)
+   - Click "Get Started"
+   - Sign up with email or GitHub
+
+2. **Create Project**
+   - Click "Create Project"
+   - Select platform: **Python**
+   - Select framework: **FastAPI**
+   - Name: `swiftops-backend`
+   - Click "Create Project"
+
+3. **Get DSN**
+   - After project creation, you'll see setup instructions
+   - Copy the DSN (looks like):
+     ```
+     https://xxxxx@o123456.ingest.sentry.io/123456
+     ```
+   - Save as `SENTRY_DSN`
+
+4. **Configure Alerts** (Optional)
+   - Go to **Alerts** → **Create Alert**
+   - Set up alerts for:
+     - Error rate > 5%
+     - Response time > 2s
+     - Failed payments
+
+### Environment Variables:
+```bash
+SENTRY_DSN=https://xxxxx@o123456.ingest.sentry.io/123456
+SENTRY_ENVIRONMENT=production
+```
+
+### Free Tier:
+- 5,000 errors/month
+- 10,000 performance units/month
+
+---
+
+## 9. 🔐 JWT Secret Key
+
+**What you need:**
+- Strong secret key for JWT signing
+
+### Generate Secret Key:
+
+**Option 1: Using Python**
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+**Option 2: Using OpenSSL**
+```bash
+openssl rand -base64 32
+```
+
+**Option 3: Online Generator**
+- Go to [https://randomkeygen.com](https://randomkeygen.com)
+- Use "CodeIgniter Encryption Keys" (256-bit)
+
+### Environment Variables:
+```bash
+SECRET_KEY=your-super-secret-key-here-min-32-characters
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=1440
+REFRESH_TOKEN_EXPIRE_DAYS=30
+```
+
+---
+
+## 10. 📋 Complete .env File Template
+
+Create a `.env` file in your project root with all credentials:
+
+```bash
+# ============================================
+# Application Settings
+# ============================================
+APP_NAME=SwiftOps API
+DEBUG=False
+ENVIRONMENT=production
+SECRET_KEY=your-super-secret-key-here
+ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=1440
+REFRESH_TOKEN_EXPIRE_DAYS=30
+
+# ============================================
+# Database & Supabase
+# ============================================
+DATABASE_URL=postgresql://postgres:YOUR_PASSWORD@db.xxxxx.supabase.co:5432/postgres
+SUPABASE_URL=https://xxxxx.supabase.co
+SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_JWT_SECRET=your-jwt-secret
+
+# ============================================
+# Redis
+# ============================================
+REDIS_URL=redis://localhost:6379/0
+
+# ============================================
+# Celery
+# ============================================
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/0
+
+# ============================================
+# Cloudinary
+# ============================================
+CLOUDINARY_CLOUD_NAME=your-cloud-name
+CLOUDINARY_API_KEY=123456789012345
+CLOUDINARY_API_SECRET=abcdefghijklmnopqrstuvwxyz
+
+# ============================================
+# M-Pesa
+# ============================================
+MPESA_ENVIRONMENT=sandbox
+MPESA_CONSUMER_KEY=your-consumer-key
+MPESA_CONSUMER_SECRET=your-consumer-secret
+MPESA_SHORTCODE=174379
+MPESA_PASSKEY=your-passkey
+MPESA_INITIATOR_NAME=testapi
+MPESA_SECURITY_CREDENTIAL=your-security-credential
+
+# ============================================
+# Resend (Email)
+# ============================================
+RESEND_API_KEY=re_123456789abcdefghijklmnop
+FROM_EMAIL=noreply@swiftops.com
+
+# ============================================
+# Africa's Talking (SMS) - V2
+# ============================================
+AFRICASTALKING_USERNAME=sandbox
+AFRICASTALKING_API_KEY=your-api-key
+AFRICASTALKING_ENVIRONMENT=sandbox
+
+# ============================================
+# Google Maps
+# ============================================
+GOOGLE_MAPS_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+
+# ============================================
+# Sentry (Optional)
+# ============================================
+SENTRY_DSN=https://xxxxx@o123456.ingest.sentry.io/123456
+SENTRY_ENVIRONMENT=production
+
+# ============================================
+# CORS Settings
+# ============================================
+CORS_ORIGINS=http://localhost:3000,https://swiftops.com
+```
+
+---
+
+## 11. ✅ Verification Checklist
+
+After setting up all services, verify each one:
+
+### Database & Auth
+- [ ] Can connect to Supabase database
+- [ ] Can create a test user via Supabase Auth
+- [ ] JWT tokens are being generated correctly
+
+### Image Storage
+- [ ] Can upload image to Cloudinary
+- [ ] Can retrieve image URL
+- [ ] Can delete image from Cloudinary
+
+### Email
+- [ ] Can send test email via Resend
+- [ ] Email is delivered to inbox (check spam)
+- [ ] Email templates are rendering correctly
+
+### Payments
+- [ ] Can generate M-Pesa access token
+- [ ] Can initiate test B2C payment (sandbox)
+- [ ] Webhook callbacks are being received
+
+### SMS (V2)
+- [ ] Can send test SMS via Africa's Talking
+- [ ] SMS is delivered to test number
+
+### Maps
+- [ ] Can geocode an address
+- [ ] Can calculate distance between two points
+- [ ] Can get directions
+
+### Caching
+- [ ] Can connect to Redis
+- [ ] Can set and get cache values
+- [ ] Celery workers can connect to Redis
+
+### Monitoring
+- [ ] Sentry is receiving test errors
+- [ ] Error alerts are being sent
+
+---
+
+## 12. 🔒 Security Best Practices
+
+1. **Never commit .env file to Git**
+   ```bash
+   # Add to .gitignore
+   .env
+   .env.local
+   .env.production
+   ```
+
+2. **Use different credentials for dev/staging/production**
+   - Development: Use sandbox/test credentials
+   - Staging: Use separate production-like credentials
+   - Production: Use production credentials with restrictions
+
+3. **Rotate credentials regularly**
+   - API keys: Every 90 days
+   - Database passwords: Every 180 days
+   - JWT secrets: Every 365 days
+
+4. **Restrict API keys**
+   - Add IP restrictions where possible
+   - Use least privilege (only enable needed APIs)
+   - Monitor usage for anomalies
+
+5. **Encrypt sensitive credentials**
+   - Use environment variables (never hardcode)
+   - Use secret management tools (AWS Secrets Manager, HashiCorp Vault)
+   - Encrypt .env files in production
+
+---
+
+## 13. 💰 Cost Estimation
+
+### Development (Free Tier)
+- Supabase: Free (500MB database, 2GB bandwidth)
+- Cloudinary: Free (25GB storage, 25GB bandwidth)
+- Resend: Free (100 emails/day)
+- M-Pesa: Free (sandbox)
+- Africa's Talking: Free (sandbox)
+- Google Maps: Free ($200 credits/month)
+- Redis Cloud: Free (30MB)
+- Sentry: Free (5,000 errors/month)
+
+**Total: $0/month**
+
+### Production (Estimated)
+- Supabase: $25/month (Pro plan)
+- Cloudinary: $89/month (Plus plan) or stay on free tier
+- Resend: $20/month (10,000 emails)
+- M-Pesa: Transaction fees only (~1% per transaction)
+- Africa's Talking: ~$50/month (5,000 SMS)
+- Google Maps: ~$50/month (within free credits)
+- Redis Cloud: $7/month (250MB)
+- Sentry: $26/month (Team plan)
+
+**Total: ~$267/month** (scales with usage)
+
+---
+
+## 14. 📞 Support & Resources
+
+### Supabase
+- Docs: [https://supabase.com/docs](https://supabase.com/docs)
+- Discord: [https://discord.supabase.com](https://discord.supabase.com)
+
+### Cloudinary
+- Docs: [https://cloudinary.com/documentation](https://cloudinary.com/documentation)
+- Support: support@cloudinary.com
+
+### Resend
+- Docs: [https://resend.com/docs](https://resend.com/docs)
+- Support: support@resend.com
+
+### M-Pesa
+- Docs: [https://developer.safaricom.co.ke/docs](https://developer.safaricom.co.ke/docs)
+- Support: apisupport@safaricom.co.ke
+
+### Africa's Talking
+- Docs: [https://developers.africastalking.com](https://developers.africastalking.com)
+- Support: support@africastalking.com
+
+### Google Maps
+- Docs: [https://developers.google.com/maps](https://developers.google.com/maps)
+- Support: Google Cloud Console
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** November 2025  
+**Next Review:** Before production deployment

docs/prod/TEST_TEMPLATES.md

@@ -0,0 +1,234 @@
+# Testing the New Template Architecture
+
+## ✅ What We Built
+
+### **Proper FastAPI Architecture**
+```
+src/app/
+├── templates/          # Jinja2 templates (HTML)
+├── static/            # CSS, JS, images
+├── api/v1/pages.py    # Page routes (separate from API)
+├── constants/         # Centralized configuration
+└── main.py            # Application entry point
+```
+
+---
+
+## 🚀 How to Test
+
+### 1. Install New Dependencies
+
+```bash
+pip install jinja2==3.1.2 aiofiles==23.2.1
+```
+
+### 2. Start the Server
+
+```bash
+uvicorn src.app.main:app --reload
+```
+
+### 3. Visit the Pages
+
+- **Landing Page**: http://localhost:8000/
+- **API Docs**: http://localhost:8000/api/docs
+- **Health Check**: http://localhost:8000/health
+
+### 4. Test Theme Switching
+
+**Windows:**
+- Settings → Personalization → Colors → Choose your mode
+
+**Mac:**
+- System Preferences → General → Appearance
+
+**Linux:**
+- Depends on desktop environment
+
+The page will automatically switch between light and dark themes! 🌓
+
+---
+
+## 📁 File Structure
+
+### **Templates** (`src/app/templates/`)
+- `base.html` - Base layout (header, footer, meta tags)
+- `index.html` - Landing page content
+- `README.md` - Template documentation
+
+### **Static Files** (`src/app/static/`)
+- `css/main.css` - Styles with theme support
+- `js/main.js` - Client-side JavaScript
+
+### **Routes** (`src/app/api/v1/pages.py`)
+- Page routes (HTML responses)
+- Separate from API routes (JSON responses)
+
+### **Configuration** (`src/app/constants/app_metadata.py`)
+- Centralized app metadata
+- Version, name, description
+- Used across all pages
+
+---
+
+## 🎯 Benefits of This Architecture
+
+### ✅ **Separation of Concerns**
+- Templates handle HTML structure
+- CSS handles styling
+- JavaScript handles behavior
+- Python handles logic
+
+### ✅ **Maintainability**
+- Easy to find files
+- Clear responsibilities
+- Consistent structure
+
+### ✅ **Scalability**
+- Add new pages easily
+- Extend base template
+- Reuse components
+
+### ✅ **Best Practices**
+- Follows FastAPI conventions
+- Uses Jinja2 templates
+- Static file serving
+- Template inheritance
+
+---
+
+## 📝 Adding New Pages
+
+### Example: Add an "About" Page
+
+**1. Create template** (`templates/about.html`):
+```html
+{% extends "base.html" %}
+
+{% block title %}About - {{ app_name }}{% endblock %}
+
+{% block content %}
+<div class="container">
+    <h1>About {{ app_name }}</h1>
+    <p>{{ app_description }}</p>
+</div>
+{% endblock %}
+```
+
+**2. Add route** (`api/v1/pages.py`):
+```python
+@router.get("/about", response_class=HTMLResponse)
+async def about(request: Request):
+    return templates.TemplateResponse("about.html", {
+        "request": request,
+        "app_name": APP_NAME,
+        "app_description": APP_DESCRIPTION
+    })
+```
+
+**3. Visit**: http://localhost:8000/about
+
+---
+
+## 🎨 Customization
+
+### Update App Info
+
+Edit `src/app/constants/app_metadata.py`:
+```python
+APP_NAME = "Your App Name"
+APP_VERSION = "2.0.0"
+APP_DESCRIPTION = "Your description"
+```
+
+### Add Custom Styles
+
+Edit `src/app/static/css/main.css`:
+```css
+.custom-button {
+    background: var(--accent-color);
+    padding: 1rem 2rem;
+}
+```
+
+### Add Custom JavaScript
+
+Edit `src/app/static/js/main.js`:
+```javascript
+console.log('Custom script loaded!');
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### Templates Not Found
+```bash
+# Check templates directory exists
+ls src/app/templates/
+
+# Should show: base.html, index.html, README.md
+```
+
+### Static Files Not Loading
+```bash
+# Check static directory exists
+ls src/app/static/css/
+ls src/app/static/js/
+
+# Should show: main.css and main.js
+```
+
+### Import Errors
+```bash
+# Reinstall dependencies
+pip install -r requirements.txt
+
+# Check Jinja2 is installed
+pip show jinja2
+```
+
+---
+
+## ✨ Features
+
+### 🌓 **Theme Support**
+- Automatic dark/light mode
+- Respects system preferences
+- Smooth transitions
+
+### 📱 **Responsive Design**
+- Mobile-friendly
+- Tablet-optimized
+- Desktop-enhanced
+
+### ⚡ **Performance**
+- Fast page loads
+- Minimal dependencies
+- Optimized assets
+
+### 🎯 **SEO Ready**
+- Proper meta tags
+- Semantic HTML
+- Accessible markup
+
+---
+
+## 📚 Documentation
+
+- **Architecture**: `docs/dev/TEMPLATES_ARCHITECTURE.md`
+- **Template Guide**: `src/app/templates/README.md`
+- **API Docs**: http://localhost:8000/api/docs
+
+---
+
+## 🎉 Success!
+
+Your FastAPI application now has:
+- ✅ Proper template architecture
+- ✅ Theme-aware landing page
+- ✅ Separated concerns (HTML/CSS/JS/Python)
+- ✅ Scalable structure
+- ✅ Best practices followed
+
+**Ready for production and easy to maintain!** 🚀

docs/spec/USER_STORIES.md

@@ -0,0 +1,1118 @@
+# User Stories & API Endpoints
+
+## Overview
+This document outlines user stories for the Field Service Management Platform, organized by user role. Each story includes acceptance criteria and required FastAPI backend endpoints.
+
+**Architecture:** FastAPI backend handles all database interactions. Frontend queries the backend via REST API.
+
+**User Roles:**
+- Platform Admin
+- Client Admin (Telecom Operator)
+- Contractor Admin
+- Project Manager
+- Dispatcher
+- Field Agent
+- Sales Agent
+- Sales Manager
+
+---
+
+## 1. PLATFORM ADMIN
+
+### 1.1 Organization Management
+
+**US-PA-001: Create Client Organization**
+- **As a** Platform Admin
+- **I want to** create new client organizations (telecom operators)
+- **So that** they can use the platform for their field operations
+
+**Acceptance Criteria:**
+- Can create client with name, industry, contact details
+- System validates unique client name and email
+- Client is created with default SLA settings
+- Client admin user is automatically invited
+
+**API Endpoints:**
+```
+POST   /api/v1/clients
+GET    /api/v1/clients
+GET    /api/v1/clients/{client_id}
+PUT    /api/v1/clients/{client_id}
+DELETE /api/v1/clients/{client_id}
+```
+
+**US-PA-002: Create Contractor Organization**
+- **As a** Platform Admin
+- **I want to** create contractor organizations
+- **So that** they can be assigned to client projects
+
+**Acceptance Criteria:**
+- Can create contractor with name, competencies, contact details
+- System validates unique contractor name
+- Contractor admin user is automatically invited
+- Can specify contractor specializations (FTTH, Fixed Wireless, etc.)
+
+**API Endpoints:**
+```
+POST   /api/v1/contractors
+GET    /api/v1/contractors
+GET    /api/v1/contractors/{contractor_id}
+PUT    /api/v1/contractors/{contractor_id}
+DELETE /api/v1/contractors/{contractor_id}
+```
+
+
+### 1.2 Platform Billing Management
+
+**US-PA-003: Manage Billing Plans**
+- **As a** Platform Admin
+- **I want to** create and manage billing plans
+- **So that** organizations can subscribe to different service tiers
+
+**Acceptance Criteria:**
+- Can create plans with pricing, features, and limits
+- Can set user limits, project limits, and storage quotas
+- Can mark plans as public or private
+- Can activate/deactivate plans
+
+**API Endpoints:**
+```
+POST   /api/v1/billing/plans
+GET    /api/v1/billing/plans
+GET    /api/v1/billing/plans/{plan_id}
+PUT    /api/v1/billing/plans/{plan_id}
+DELETE /api/v1/billing/plans/{plan_id}
+```
+
+**US-PA-004: Monitor Platform Usage**
+- **As a** Platform Admin
+- **I want to** view usage metrics across all organizations
+- **So that** I can monitor platform health and billing
+
+**Acceptance Criteria:**
+- Can view active users, projects, tickets per organization
+- Can see storage usage and API call counts
+- Can filter by date range and organization type
+- Can export usage reports
+
+**API Endpoints:**
+```
+GET    /api/v1/usage-metrics
+GET    /api/v1/usage-metrics/summary
+GET    /api/v1/usage-metrics/by-organization
+POST   /api/v1/usage-metrics/export
+```
+
+---
+
+## 2. CLIENT ADMIN (Telecom Operator)
+
+### 2.1 Project Setup
+
+**US-CA-001: Initiate Project Creation**
+- **As a** Client Admin
+- **I want to** initiate a project and invite a contractor
+- **So that** we can collaborate on field work
+
+**Acceptance Criteria:**
+- Can create project with title, description, service type
+- Can invite contractor from available contractors
+- Contractor receives invitation to join project
+- Project is created in 'pending' state until contractor accepts
+- Can set project dates and budget
+- Can define activation requirements (ONT serial, MAC address, etc.)
+- Can specify photo requirements for installations
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/initiate                  # Client initiates
+POST   /api/v1/projects/invitations               # Send contractor invitation
+GET    /api/v1/projects
+GET    /api/v1/projects/{project_id}
+PUT    /api/v1/projects/{project_id}
+DELETE /api/v1/projects/{project_id}
+POST   /api/v1/projects/{project_id}/close
+```
+
+
+**US-CA-002: Define Project Regions**
+- **As a** Client Admin
+- **I want to** create regional hubs within a project
+- **So that** inventory and teams can be organized geographically
+
+**Acceptance Criteria:**
+- Can create regions with name, location, and manager
+- Can assign regional manager from project team
+- Regions are used for inventory distribution
+- Can view all regions on a map
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/{project_id}/regions
+GET    /api/v1/projects/{project_id}/regions
+GET    /api/v1/regions/{region_id}
+PUT    /api/v1/regions/{region_id}
+DELETE /api/v1/regions/{region_id}
+```
+
+### 2.2 User Management
+
+**US-CA-003: Invite Users**
+- **As a** Client Admin
+- **I want to** invite users to my organization
+- **So that** they can access the platform
+
+**Acceptance Criteria:**
+- Can invite users with email and role
+- System sends invitation email
+- Can set user role (sales_manager, project_manager, dispatcher, sales_agent)
+- User receives onboarding instructions
+
+**API Endpoints:**
+```
+POST   /api/v1/users/invite
+GET    /api/v1/users
+GET    /api/v1/users/{user_id}
+PUT    /api/v1/users/{user_id}
+DELETE /api/v1/users/{user_id}
+POST   /api/v1/users/{user_id}/suspend
+POST   /api/v1/users/{user_id}/activate
+```
+
+---
+
+## 3. CONTRACTOR ADMIN
+
+### 3.1 Project Collaboration
+
+**US-CO-001: Accept or Initiate Project**
+- **As a** Contractor Admin
+- **I want to** accept project invitations from clients or initiate projects
+- **So that** I can collaborate with clients on field work
+
+**Acceptance Criteria:**
+- Can view pending project invitations from clients
+- Can accept or decline project invitations
+- Can also initiate projects and invite clients
+- Project becomes 'active' when both parties agree
+- Can negotiate project terms before acceptance
+
+**API Endpoints:**
+```
+GET    /api/v1/projects/invitations/pending
+POST   /api/v1/projects/invitations/{invitation_id}/accept
+POST   /api/v1/projects/invitations/{invitation_id}/decline
+POST   /api/v1/projects/initiate                  # Contractor initiates
+POST   /api/v1/projects/invitations               # Invite client
+```
+
+### 3.2 Team Management
+
+**US-CO-002: Manage Field Agents**
+- **As a** Contractor Admin
+- **I want to** add and manage field agents
+- **So that** they can be assigned to projects
+
+**Acceptance Criteria:**
+- Can add field agents with contact details
+- Can record health & safety information
+- Can record PPE sizes for equipment allocation
+- Can assign financial accounts for payouts
+- Can track agent location in real-time
+
+**API Endpoints:**
+```
+POST   /api/v1/field-agents
+GET    /api/v1/field-agents
+GET    /api/v1/field-agents/{agent_id}
+PUT    /api/v1/field-agents/{agent_id}
+GET    /api/v1/field-agents/{agent_id}/location
+POST   /api/v1/field-agents/{agent_id}/financial-accounts
+```
+
+**US-CO-003: Invite Team Members to Project**
+- **As a** Contractor Admin
+- **I want to** invite my team members to join a project
+- **So that** they can be assigned work
+
+**Acceptance Criteria:**
+- Can invite field agents to specific projects
+- Can set project role and compensation structure
+- Can assign agents to specific regions
+- Team members receive invitation notification
+- Can track agent availability across projects
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/{project_id}/team/invite
+GET    /api/v1/projects/{project_id}/team/invitations
+POST   /api/v1/projects/{project_id}/team/invitations/{id}/resend
+DELETE /api/v1/projects/{project_id}/team/invitations/{id}/cancel
+GET    /api/v1/projects/{project_id}/team
+DELETE /api/v1/projects/{project_id}/team/{member_id}
+GET    /api/v1/field-agents/{agent_id}/projects
+```
+
+---
+
+## 4. PROJECT MANAGER
+
+### 4.1 Sales Order Management
+
+**US-PM-001: Create Sales Order (Single)**
+- **As a** Project Manager
+- **I want to** create individual sales orders
+- **So that** I can add orders one at a time
+
+**Acceptance Criteria:**
+- Can enter customer details (name, phone, address)
+- System deduplicates customers by phone number
+- Can specify package, price, and installation details
+- Can set preferred installation date/time
+- Can add installation address with GPS coordinates
+- Order is created with 'pending' status
+
+**API Endpoints:**
+```
+POST   /api/v1/sales-orders
+GET    /api/v1/sales-orders
+GET    /api/v1/sales-orders/{order_id}
+PUT    /api/v1/sales-orders/{order_id}
+DELETE /api/v1/sales-orders/{order_id}
+POST   /api/v1/customers/check-duplicate
+```
+
+**US-PM-002: Upload Sales Orders (CSV Bulk Import)**
+- **As a** Project Manager
+- **I want to** upload sales orders via CSV
+- **So that** installation tickets can be generated in bulk
+
+**Acceptance Criteria:**
+- Can upload CSV with customer details and installation addresses
+- System validates and deduplicates customers by phone
+- System creates SalesOrder records in batch
+- Can preview orders before confirming
+- Can see validation errors for invalid rows
+- Can download error report for failed rows
+- Successfully imported orders are marked as 'pending'
+
+**API Endpoints:**
+```
+POST   /api/v1/sales-orders/upload-csv
+POST   /api/v1/sales-orders/validate-csv
+POST   /api/v1/sales-orders/confirm-csv-import
+GET    /api/v1/sales-orders/import-history
+GET    /api/v1/sales-orders/import/{import_id}/errors
+```
+
+**US-PM-002: Generate Tickets from Sales Orders**
+- **As a** Project Manager
+- **I want to** convert unprocessed sales orders into tickets
+- **So that** field agents can execute installations
+
+**Acceptance Criteria:**
+- Can select multiple sales orders to process
+- System creates installation tickets with cached location data
+- Tickets are created with 'open' status
+- Sales orders are marked as 'processed'
+- Can bulk generate tickets
+
+**API Endpoints:**
+```
+POST   /api/v1/sales-orders/{order_id}/create-ticket
+POST   /api/v1/sales-orders/bulk-create-tickets
+GET    /api/v1/sales-orders/unprocessed
+```
+
+
+### 4.2 Inventory Management
+
+**US-PM-003: Receive Inventory from Client**
+- **As a** Project Manager
+- **I want to** record inventory received from the client
+- **So that** equipment can be tracked and distributed
+
+**Acceptance Criteria:**
+- Can record equipment type, quantity, and serial numbers
+- Can specify if items are tools (returnable) or equipment (installable)
+- Can record delivery note reference
+- Can track inventory value
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/{project_id}/inventory
+GET    /api/v1/projects/{project_id}/inventory
+GET    /api/v1/inventory/{inventory_id}
+PUT    /api/v1/inventory/{inventory_id}
+GET    /api/v1/inventory/{inventory_id}/serial-numbers
+```
+
+**US-PM-004: Distribute Inventory to Regional Hubs**
+- **As a** Project Manager
+- **I want to** distribute inventory from main office to regional hubs
+- **So that** field agents can collect equipment locally
+
+**Acceptance Criteria:**
+- Can allocate quantities to specific regions
+- Can track serial numbers per region
+- System updates available quantities
+- Can view inventory levels per region
+
+**API Endpoints:**
+```
+POST   /api/v1/inventory/{inventory_id}/distribute
+GET    /api/v1/regions/{region_id}/inventory
+GET    /api/v1/inventory-distribution/{distribution_id}
+PUT    /api/v1/inventory-distribution/{distribution_id}
+```
+
+### 4.3 Task Management (Infrastructure Projects)
+
+**US-PM-005: Create Infrastructure Tasks**
+- **As a** Project Manager
+- **I want to** create tasks for infrastructure rollout
+- **So that** contractors can execute infrastructure work
+
+**Acceptance Criteria:**
+- Can create tasks with title, description, location
+- Can set task type (installation, maintenance, survey, testing)
+- Can assign priority and schedule date
+- Can generate tickets from tasks
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/{project_id}/tasks
+GET    /api/v1/projects/{project_id}/tasks
+GET    /api/v1/tasks/{task_id}
+PUT    /api/v1/tasks/{task_id}
+DELETE /api/v1/tasks/{task_id}
+POST   /api/v1/tasks/{task_id}/create-ticket
+```
+
+
+### 4.4 Financial Management
+
+**US-PM-006: Track Project Finances**
+- **As a** Project Manager
+- **I want to** record project income and expenses
+- **So that** I can monitor project cash flow
+
+**Acceptance Criteria:**
+- Can record inflows (funding from finance department)
+- Can record outflows (payroll, equipment, transport)
+- Can link transactions to specific entities (tickets, payroll, invoices)
+- Can view financial summary and balance
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/{project_id}/finance
+GET    /api/v1/projects/{project_id}/finance
+GET    /api/v1/projects/{project_id}/finance/summary
+GET    /api/v1/finance/{transaction_id}
+PUT    /api/v1/finance/{transaction_id}
+POST   /api/v1/finance/{transaction_id}/approve
+POST   /api/v1/finance/{transaction_id}/reject
+```
+
+**US-PM-007: Generate Contractor Invoices**
+- **As a** Project Manager
+- **I want to** generate invoices for contractor work
+- **So that** contractors can be paid for completed tickets
+
+**Acceptance Criteria:**
+- Can select completed tickets for invoicing
+- System calculates total based on compensation structure
+- Can add line items and adjustments
+- Can mark invoice as paid
+
+**API Endpoints:**
+```
+POST   /api/v1/projects/{project_id}/invoices
+GET    /api/v1/projects/{project_id}/invoices
+GET    /api/v1/invoices/{invoice_id}
+PUT    /api/v1/invoices/{invoice_id}
+POST   /api/v1/invoices/{invoice_id}/mark-paid
+GET    /api/v1/invoices/{invoice_id}/tickets
+```
+
+---
+
+## 5. DISPATCHER
+
+### 5.1 Ticket Assignment
+
+**US-DI-001: View Available Tickets**
+- **As a** Dispatcher
+- **I want to** view all open tickets
+- **So that** I can assign them to field agents
+
+**Acceptance Criteria:**
+- Can view tickets filtered by status, priority, region
+- Can see ticket details including location and requirements
+- Can view tickets on a map
+- Can see agent availability and current workload
+
+**API Endpoints:**
+```
+GET    /api/v1/tickets
+GET    /api/v1/tickets/open
+GET    /api/v1/tickets/by-region/{region_id}
+GET    /api/v1/tickets/map-view
+GET    /api/v1/field-agents/availability
+```
+
+
+**US-DI-002: Assign Tickets to Field Agents**
+- **As a** Dispatcher
+- **I want to** assign tickets to field agents
+- **So that** work can be executed
+
+**Acceptance Criteria:**
+- Can assign single or multiple tickets to an agent
+- Can set scheduled date and time slot
+- System creates ticket assignment record
+- Agent receives notification
+- Ticket status changes to 'assigned'
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/assign
+POST   /api/v1/tickets/bulk-assign
+GET    /api/v1/tickets/{ticket_id}/assignments
+POST   /api/v1/tickets/{ticket_id}/reassign
+POST   /api/v1/tickets/{ticket_id}/unassign
+```
+
+### 5.2 Inventory Issuance
+
+**US-DI-003: Issue Equipment to Field Agents**
+- **As a** Dispatcher
+- **I want to** issue equipment to field agents from regional hub
+- **So that** they have materials for installations
+
+**Acceptance Criteria:**
+- Can scan or enter serial numbers/box numbers
+- Can issue multiple items at once
+- System tracks who issued and who received
+- Can link equipment to specific tickets
+- System updates inventory quantities
+
+**API Endpoints:**
+```
+POST   /api/v1/regions/{region_id}/issue-equipment
+GET    /api/v1/field-agents/{agent_id}/equipment
+GET    /api/v1/equipment-assignments
+POST   /api/v1/equipment-assignments/{assignment_id}/return
+GET    /api/v1/equipment-assignments/unreturned
+```
+
+### 5.3 Expense Approval
+
+**US-DI-004: Review and Approve Expenses**
+- **As a** Dispatcher
+- **I want to** review expense claims from field agents
+- **So that** valid expenses can be reimbursed
+
+**Acceptance Criteria:**
+- Can view pending expense claims
+- Can see expense details, receipts, and location verification
+- Can approve or reject with reason
+- Can filter by agent, date, or ticket
+- System validates location before approval
+
+**API Endpoints:**
+```
+GET    /api/v1/expenses/pending
+GET    /api/v1/expenses/{expense_id}
+POST   /api/v1/expenses/{expense_id}/approve
+POST   /api/v1/expenses/{expense_id}/reject
+GET    /api/v1/tickets/{ticket_id}/expenses
+GET    /api/v1/field-agents/{agent_id}/expenses
+```
+
+
+---
+
+## 6. FIELD AGENT
+
+### 6.1 Ticket Management
+
+**US-FA-001: View My Assigned Tickets**
+- **As a** Field Agent
+- **I want to** view tickets assigned to me
+- **So that** I know what work I need to do
+
+**Acceptance Criteria:**
+- Can view assigned tickets in list or map view
+- Can see ticket details, customer info, and location
+- Can filter by status and priority
+- Can see route to customer location
+- Can set execution order for my tickets
+
+**API Endpoints:**
+```
+GET    /api/v1/field-agents/me/tickets
+GET    /api/v1/field-agents/me/tickets/today
+GET    /api/v1/tickets/{ticket_id}
+PUT    /api/v1/tickets/{ticket_id}/execution-order
+GET    /api/v1/tickets/{ticket_id}/route
+```
+
+**US-FA-002: Accept or Reject Ticket Assignment**
+- **As a** Field Agent
+- **I want to** accept or reject assigned tickets
+- **So that** I can manage my workload
+
+**Acceptance Criteria:**
+- Can accept ticket (status changes to 'in_progress')
+- Can reject ticket with reason
+- Can request reassignment
+- System records response timestamp
+- Dispatcher is notified of rejection
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/accept
+POST   /api/v1/tickets/{ticket_id}/reject
+POST   /api/v1/tickets/{ticket_id}/request-reassignment
+```
+
+**US-FA-003: Start Journey to Customer Site**
+- **As a** Field Agent
+- **I want to** start journey tracking when I leave for a ticket
+- **So that** my travel can be monitored
+
+**Acceptance Criteria:**
+- Can start journey with one tap
+- System records journey start location and time
+- GPS tracking begins (breadcrumb trail)
+- Can see estimated arrival time
+- Can pause/resume journey
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/start-journey
+POST   /api/v1/tickets/{ticket_id}/pause-journey
+POST   /api/v1/tickets/{ticket_id}/resume-journey
+POST   /api/v1/tickets/{ticket_id}/location-update
+GET    /api/v1/tickets/{ticket_id}/journey-status
+```
+
+
+**US-FA-004: Mark Arrival at Customer Site**
+- **As a** Field Agent
+- **I want to** mark when I arrive at customer location
+- **So that** my arrival time is recorded
+
+**Acceptance Criteria:**
+- Can mark arrival with GPS verification
+- System validates location matches customer address
+- Journey tracking stops
+- Arrival time is recorded
+- Can proceed to work execution
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/mark-arrival
+GET    /api/v1/tickets/{ticket_id}/verify-location
+```
+
+### 6.2 Customer Communication
+
+**US-FA-005: Contact Customer**
+- **As a** Field Agent
+- **I want to** record customer communication attempts
+- **So that** contact history is tracked
+
+**Acceptance Criteria:**
+- Can record call, SMS, WhatsApp, or in-person contact
+- Can record outcome (successful, no answer, busy, etc.)
+- Can schedule follow-up
+- Can see previous communication history
+- Can initiate call from app
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/communications
+GET    /api/v1/tickets/{ticket_id}/communications
+GET    /api/v1/customers/{customer_id}/communications
+POST   /api/v1/communications/{comm_id}/follow-up
+```
+
+### 6.3 Work Execution
+
+**US-FA-006: Complete Installation**
+- **As a** Field Agent
+- **I want to** record installation details and activate service
+- **So that** customer can start using the service
+
+**Acceptance Criteria:**
+- Can enter equipment details (ONT serial, MAC address, etc.)
+- Can capture before/after photos
+- Can record activation details
+- Can create subscription record
+- Ticket status changes to 'completed'
+- System validates all required fields
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/complete
+POST   /api/v1/tickets/{ticket_id}/photos
+POST   /api/v1/tickets/{ticket_id}/equipment-details
+POST   /api/v1/subscriptions
+GET    /api/v1/projects/{project_id}/activation-requirements
+```
+
+
+**US-FA-007: Log Expenses**
+- **As a** Field Agent
+- **I want to** record expenses incurred during ticket execution
+- **So that** I can be reimbursed
+
+**Acceptance Criteria:**
+- Can log transport, materials, meals, etc.
+- Can attach receipt photos
+- Can specify quantity and unit cost
+- System validates location (must be at customer site)
+- Can see expense approval status
+
+**API Endpoints:**
+```
+POST   /api/v1/tickets/{ticket_id}/expenses
+GET    /api/v1/field-agents/me/expenses
+GET    /api/v1/expenses/{expense_id}
+PUT    /api/v1/expenses/{expense_id}
+DELETE /api/v1/expenses/{expense_id}
+```
+
+### 6.4 Inventory Management
+
+**US-FA-008: View My Equipment**
+- **As a** Field Agent
+- **I want to** view equipment issued to me
+- **So that** I know what I have and what needs to be returned
+
+**Acceptance Criteria:**
+- Can see all equipment currently in my possession
+- Can see tools that need to be returned
+- Can see equipment installed at customer sites
+- Can scan equipment for quick lookup
+
+**API Endpoints:**
+```
+GET    /api/v1/field-agents/me/equipment
+GET    /api/v1/field-agents/me/equipment/unreturned
+GET    /api/v1/equipment/{serial_number}
+```
+
+**US-FA-009: Return Equipment**
+- **As a** Field Agent
+- **I want to** return tools to the regional hub
+- **So that** they can be reissued to other agents
+
+**Acceptance Criteria:**
+- Can scan equipment to return
+- Can specify condition (good, damaged, worn)
+- Can add return notes
+- System updates inventory quantities
+- Dispatcher confirms receipt
+
+**API Endpoints:**
+```
+POST   /api/v1/equipment-assignments/{assignment_id}/return
+POST   /api/v1/equipment-assignments/bulk-return
+```
+
+
+### 6.5 Attendance & Timesheets
+
+**US-FA-010: Clock In/Out**
+- **As a** Field Agent
+- **I want to** record my daily attendance
+- **So that** my work hours are tracked
+
+**Acceptance Criteria:**
+- Can clock in at start of day
+- Can clock out at end of day
+- System records timestamps and location
+- Can view my timesheet history
+- Can request leave
+
+**API Endpoints:**
+```
+POST   /api/v1/field-agents/me/clock-in
+POST   /api/v1/field-agents/me/clock-out
+GET    /api/v1/field-agents/me/timesheets
+POST   /api/v1/field-agents/me/request-leave
+```
+
+---
+
+## 7. SALES AGENT
+
+### 7.1 Sales Order Management
+
+**US-SA-001: Create Sales Order**
+- **As a** Sales Agent
+- **I want to** create sales orders for new customers
+- **So that** installations can be scheduled
+
+**Acceptance Criteria:**
+- Can enter customer details (name, phone, address)
+- System deduplicates customers by phone number
+- Can specify package and price
+- Can set preferred installation date/time
+- Can add installation address with GPS coordinates
+
+**API Endpoints:**
+```
+POST   /api/v1/sales-orders
+GET    /api/v1/sales-agents/me/orders
+GET    /api/v1/sales-orders/{order_id}
+PUT    /api/v1/sales-orders/{order_id}
+POST   /api/v1/customers/check-duplicate
+```
+
+**US-SA-002: Track My Sales**
+- **As a** Sales Agent
+- **I want to** view my sales performance
+- **So that** I can track my commissions
+
+**Acceptance Criteria:**
+- Can view total orders, completed installations, pending
+- Can see commission earned and pending
+- Can filter by date range
+- Can see conversion funnel (orders → tickets → installations)
+
+**API Endpoints:**
+```
+GET    /api/v1/sales-agents/me/stats
+GET    /api/v1/sales-agents/me/commissions
+GET    /api/v1/sales-agents/me/conversion-funnel
+```
+
+
+---
+
+## 8. SALES MANAGER
+
+### 8.1 Team Performance
+
+**US-SM-001: View Team Sales Performance**
+- **As a** Sales Manager
+- **I want to** view sales performance across my team
+- **So that** I can identify top performers and areas for improvement
+
+**Acceptance Criteria:**
+- Can view sales by agent, region, package type
+- Can see conversion rates and average deal size
+- Can filter by date range
+- Can export reports
+
+**API Endpoints:**
+```
+GET    /api/v1/sales/team-performance
+GET    /api/v1/sales/by-agent
+GET    /api/v1/sales/by-region
+GET    /api/v1/sales/by-package
+POST   /api/v1/sales/export-report
+```
+
+---
+
+## 9. SUPPORT TICKETS (All Roles)
+
+### 9.1 Incident Management
+
+**US-SUP-001: Create Support Incident**
+- **As a** Support Staff
+- **I want to** create incidents for customer complaints
+- **So that** support tickets can be generated
+
+**Acceptance Criteria:**
+- Can search for customer by phone or subscription
+- Can record incident type and description
+- Can set priority
+- System creates support ticket automatically
+- Customer is notified
+
+**API Endpoints:**
+```
+POST   /api/v1/incidents
+GET    /api/v1/incidents
+GET    /api/v1/incidents/{incident_id}
+PUT    /api/v1/incidents/{incident_id}
+POST   /api/v1/incidents/{incident_id}/create-ticket
+POST   /api/v1/incidents/{incident_id}/resolve
+```
+
+---
+
+## 10. COMMON ENDPOINTS
+
+### 10.1 Authentication & Authorization
+
+**API Endpoints:**
+```
+POST   /api/v1/auth/login
+POST   /api/v1/auth/logout
+POST   /api/v1/auth/refresh-token
+GET    /api/v1/auth/me
+PUT    /api/v1/auth/me/profile
+POST   /api/v1/auth/change-password
+POST   /api/v1/auth/forgot-password
+POST   /api/v1/auth/reset-password
+```
+
+
+### 10.2 Dashboard & Analytics
+
+**API Endpoints:**
+```
+GET    /api/v1/dashboard/overview
+GET    /api/v1/dashboard/tickets-pipeline
+GET    /api/v1/dashboard/sla-compliance
+GET    /api/v1/dashboard/team-performance
+GET    /api/v1/dashboard/financial-summary
+GET    /api/v1/dashboard/inventory-status
+GET    /api/v1/dashboard/map-view
+```
+
+### 10.3 Notifications
+
+**API Endpoints:**
+```
+GET    /api/v1/notifications
+GET    /api/v1/notifications/unread
+POST   /api/v1/notifications/{notification_id}/mark-read
+POST   /api/v1/notifications/mark-all-read
+DELETE /api/v1/notifications/{notification_id}
+```
+
+### 10.4 Documents & Files
+
+**API Endpoints:**
+```
+POST   /api/v1/documents/upload
+GET    /api/v1/documents/{document_id}
+GET    /api/v1/documents/{document_id}/download
+DELETE /api/v1/documents/{document_id}
+GET    /api/v1/tickets/{ticket_id}/documents
+GET    /api/v1/users/{user_id}/documents
+```
+
+### 10.5 Search & Filters
+
+**API Endpoints:**
+```
+GET    /api/v1/search/customers
+GET    /api/v1/search/tickets
+GET    /api/v1/search/users
+GET    /api/v1/search/global
+```
+
+---
+
+## 11. WORKFLOW ENDPOINTS
+
+### 11.1 Sales Order → Installation Workflow
+
+**Complete Flow:**
+```
+1. POST   /api/v1/sales-orders                    # Create order
+2. POST   /api/v1/sales-orders/{id}/create-ticket # Generate ticket
+3. POST   /api/v1/tickets/{id}/assign             # Assign to agent
+4. POST   /api/v1/tickets/{id}/accept             # Agent accepts
+5. POST   /api/v1/tickets/{id}/start-journey      # Start travel
+6. POST   /api/v1/tickets/{id}/mark-arrival       # Arrive at site
+7. POST   /api/v1/tickets/{id}/complete           # Complete work
+8. POST   /api/v1/subscriptions                   # Activate service
+```
+
+
+### 11.2 Support Incident → Resolution Workflow
+
+**Complete Flow:**
+```
+1. POST   /api/v1/incidents                       # Create incident
+2. POST   /api/v1/incidents/{id}/create-ticket    # Generate ticket
+3. POST   /api/v1/tickets/{id}/assign             # Assign to agent
+4. POST   /api/v1/tickets/{id}/accept             # Agent accepts
+5. POST   /api/v1/tickets/{id}/start-journey      # Start travel
+6. POST   /api/v1/tickets/{id}/mark-arrival       # Arrive at site
+7. POST   /api/v1/tickets/{id}/complete           # Complete repair
+8. POST   /api/v1/incidents/{id}/resolve          # Mark resolved
+```
+
+### 11.3 Infrastructure Task → Completion Workflow
+
+**Complete Flow:**
+```
+1. POST   /api/v1/projects/{id}/tasks             # Create task
+2. POST   /api/v1/tasks/{id}/create-ticket        # Generate ticket
+3. POST   /api/v1/tickets/{id}/assign             # Assign to contractor
+4. POST   /api/v1/tickets/{id}/accept             # Contractor accepts
+5. POST   /api/v1/tickets/{id}/start-journey      # Start travel
+6. POST   /api/v1/tickets/{id}/mark-arrival       # Arrive at site
+7. POST   /api/v1/tickets/{id}/complete           # Complete work
+```
+
+---
+
+## 12. API DESIGN PRINCIPLES
+
+### 12.1 RESTful Conventions
+
+- **GET** - Retrieve resources
+- **POST** - Create new resources
+- **PUT** - Update entire resource
+- **PATCH** - Partial update
+- **DELETE** - Remove resource
+
+### 12.2 Response Format
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "data": { ... },
+  "message": "Operation completed successfully",
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+**Error Response:**
+```json
+{
+  "success": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input data",
+    "details": { ... }
+  },
+  "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+### 12.3 Pagination
+
+**Query Parameters:**
+```
+?page=1&limit=25&sort_by=created_at&sort_order=desc
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "limit": 25,
+    "total": 150,
+    "total_pages": 6
+  }
+}
+```
+
+
+### 12.4 Filtering & Search
+
+**Query Parameters:**
+```
+?status=open&priority=high&region_id=uuid&search=customer_name
+```
+
+### 12.5 Authentication
+
+**Header:**
+```
+Authorization: Bearer <jwt_token>
+```
+
+### 12.6 Rate Limiting
+
+**Headers:**
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 999
+X-RateLimit-Reset: 1640000000
+```
+
+---
+
+## 13. PRIORITY IMPLEMENTATION ORDER
+
+### Phase 1: Core Foundation (MVP)
+1. Authentication & User Management
+2. Organization Management (Clients, Contractors)
+3. Project Setup
+4. User Invitations
+
+### Phase 2: Sales & Ticketing
+1. Sales Order Management
+2. Customer Management
+3. Ticket Generation
+4. Ticket Assignment
+
+### Phase 3: Field Operations
+1. Field Agent Ticket Management
+2. Journey Tracking
+3. Work Completion
+4. Subscription Activation
+
+### Phase 4: Inventory & Expenses
+1. Inventory Management
+2. Equipment Issuance
+3. Expense Logging
+4. Expense Approval
+
+### Phase 5: Financial & Reporting
+1. Project Finance Tracking
+2. Contractor Invoicing
+3. Payroll Management
+4. Dashboard Analytics
+
+### Phase 6: Advanced Features
+1. Support Incidents
+2. Infrastructure Tasks
+3. Document Management
+4. Advanced Analytics
+
+---
+
+## 14. TECHNICAL NOTES
+
+### 14.1 Database Access
+- All database operations go through FastAPI backend
+- Frontend NEVER queries Supabase directly
+- Backend handles all business logic and validation
+
+### 14.2 Real-time Updates
+- Use WebSockets for real-time location tracking
+- Use Server-Sent Events (SSE) for notifications
+- Polling for dashboard updates (every 30 seconds)
+
+### 14.3 File Uploads
+- Images uploaded to Supabase Storage
+- Backend generates signed URLs
+- Maximum file size: 10MB per file
+- Supported formats: JPG, PNG, PDF
+
+### 14.4 GPS & Location
+- Location accuracy threshold: 50 meters
+- Location updates every 30 seconds during journey
+- Offline support: Queue location updates, sync when online
+
+### 14.5 Security
+- JWT tokens with 24-hour expiry
+- Refresh tokens with 30-day expiry
+- Role-based access control (RBAC)
+- Row-level security (RLS) in database
+- API rate limiting: 1000 requests/hour per user
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** 2024-01-15  
+**Status:** Draft - Ready for Backend Implementation

requirements-dev.txt

@@ -0,0 +1,25 @@
+# Development dependencies
+-r requirements.txt
+
+# Testing
+pytest==7.4.3
+pytest-asyncio==0.21.1
+pytest-cov==4.1.0
+pytest-mock==3.12.0
+faker==20.1.0
+
+# Code Quality
+black==23.11.0
+isort==5.12.0
+flake8==6.1.0
+mypy==1.7.1
+pylint==3.0.3
+
+# Documentation
+mkdocs==1.5.3
+mkdocs-material==9.5.2
+
+# Development Tools
+ipython==8.18.1
+ipdb==0.13.13
+watchdog==3.0.0

requirements.txt

@@ -1,126 +1,49 @@
-# ============================================
 # Core Framework
-# ============================================
-fastapi==0.109.0
-uvicorn[standard]==0.27.0
-gunicorn==21.2.0
-pydantic==2.5.3
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+pydantic==2.5.0
 pydantic-settings==2.1.0
+jinja2==3.1.2
+aiofiles==23.2.1
 
-# ============================================
-# Database & ORM
-# ============================================
-sqlalchemy==2.0.25
-alembic==1.13.1
+# Database
+sqlalchemy==2.0.23
+alembic==1.12.1
 psycopg2-binary==2.9.9
-asyncpg==0.29.0
 
-# ============================================
-# Supabase Integration
-# ============================================
-supabase==2.3.4
-postgrest-py==0.13.2
-
-# ============================================
 # Authentication & Security
-# ============================================
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
 python-multipart==0.0.6
-bcrypt==4.1.2
 
-# ============================================
-# Background Tasks
-# ============================================
-celery==5.3.6
+# Redis & Caching
 redis==5.0.1
+hiredis==2.2.3
+
+# Celery (Background Tasks)
+celery==5.3.4
 flower==2.0.1
 
-# ============================================
-# HTTP Client & Requests
-# ============================================
-httpx==0.26.0
+# External Integrations
+supabase==2.0.3
+cloudinary==1.36.0
+resend==0.7.0
+googlemaps==4.10.0
+
+# HTTP Client
+httpx==0.25.2
 requests==2.31.0
-aiohttp==3.9.1
 
-# ============================================
-# Data Validation & Serialization
-# ============================================
+# Utilities
 python-dateutil==2.8.2
-pytz==2023.3.post1
-
-# ============================================
-# Payment Gateway Integration
-# ============================================
-# M-Pesa (Safaricom)
-# Note: Install specific M-Pesa SDK based on your provider
-# Example: mpesa-sdk==1.0.0
-
-# ============================================
-# SMS & Email
-# ============================================
-sendgrid==6.11.0
-twilio==8.11.1
-# Africa's Talking
-africastalking==1.2.6
+pytz==2023.3
+phonenumbers==8.13.26
 
-# ============================================
-# Google Maps API
-# ============================================
-googlemaps==4.10.0
-
-# ============================================
-# File Storage
-# ============================================
-boto3==1.34.34  # AWS S3
-python-magic==0.4.27  # File type detection
-
-# ============================================
 # Monitoring & Logging
-# ============================================
-sentry-sdk[fastapi]==1.40.0
-structlog==24.1.0
-python-json-logger==2.0.7
-
-# ============================================
-# Testing
-# ============================================
-pytest==7.4.4
-pytest-asyncio==0.23.3
-pytest-cov==4.1.0
-pytest-mock==3.12.0
-faker==22.2.0
-factory-boy==3.3.0
-httpx==0.26.0  # For testing async endpoints
+sentry-sdk==1.38.0
 
-# ============================================
-# Code Quality
-# ============================================
-black==24.1.1
-isort==5.13.2
-flake8==7.0.0
-mypy==1.8.0
-pylint==3.0.3
-pre-commit==3.6.0
+# Rate Limiting
+slowapi==0.1.9
 
-# ============================================
-# Development Tools
-# ============================================
-ipython==8.20.0
-ipdb==0.13.13
-python-dotenv==1.0.1
-
-# ============================================
-# Documentation
-# ============================================
-mkdocs==1.5.3
-mkdocs-material==9.5.6
-
-# ============================================
-# Utilities
-# ============================================
-python-slugify==8.0.2
-phonenumbers==8.13.28
-email-validator==2.1.0.post1
-openpyxl==3.1.2  # Excel file handling
-pandas==2.2.0  # Data processing (for reports)
+# Note: Development dependencies moved to requirements-dev.txt
+# This file contains only production dependencies

scripts/seed_database.py

@@ -0,0 +1,37 @@
+"""
+Database Seeding Script
+Populates database with initial test data
+"""
+from sqlalchemy.orm import Session
+from app.core.database import SessionLocal, engine
+from app.models.base import Base
+
+# TODO: Import models and create seed data
+
+
+def seed_database():
+    """Seed database with initial data"""
+    db = SessionLocal()
+    
+    try:
+        print("Seeding database...")
+        
+        # TODO: Create seed data
+        # - Platform admin user
+        # - Sample client
+        # - Sample contractor
+        # - Sample project
+        # - Sample users
+        
+        db.commit()
+        print("Database seeded successfully!")
+        
+    except Exception as e:
+        print(f"Error seeding database: {e}")
+        db.rollback()
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    seed_database()

src/app/__init__.py

@@ -0,0 +1,6 @@
+"""
+SwiftOps Backend Application
+Field Service Management Platform for African Telecom
+"""
+
+__version__ = "1.0.0"

src/app/api/__init__.py

@@ -0,0 +1,3 @@
+"""
+API Layer - HTTP Endpoints
+"""

src/app/api/deps.py

@@ -0,0 +1,57 @@
+"""
+API Route Dependencies
+"""
+from typing import Generator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.orm import Session
+from app.core.database import SessionLocal
+from app.core.auth import verify_token
+from app.core.permissions import AppRole
+
+security = HTTPBearer()
+
+
+def get_db() -> Generator[Session, None, None]:
+    """Database session dependency"""
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    db: Session = Depends(get_db)
+):
+    """
+    Get current authenticated user from JWT token
+    """
+    token = credentials.credentials
+    payload = verify_token(token)
+    
+    if not payload:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials"
+        )
+    
+    # TODO: Fetch user from database using payload['sub']
+    # For now, return payload
+    return payload
+
+
+def require_role(*allowed_roles: AppRole):
+    """
+    Role-based access control dependency
+    """
+    async def role_checker(current_user: dict = Depends(get_current_user)):
+        user_role = current_user.get("role")
+        if user_role not in [role.value for role in allowed_roles]:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Access denied. Required roles: {', '.join([r.value for r in allowed_roles])}"
+            )
+        return current_user
+    return role_checker

src/app/api/v1/__init__.py

@@ -0,0 +1,3 @@
+"""
+API Version 1
+"""

src/app/api/v1/analytics.py

@@ -0,0 +1,8 @@
+"""
+ANALYTICS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement analytics endpoints

src/app/api/v1/assignments.py

@@ -0,0 +1,8 @@
+"""
+ASSIGNMENTS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement assignments endpoints

src/app/api/v1/auth.py

@@ -0,0 +1,15 @@
+"""
+Authentication Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement authentication endpoints
+# POST /login
+# POST /register
+# POST /logout
+# POST /refresh-token
+# GET /me
+# POST /otp/generate
+# POST /otp/verify

src/app/api/v1/customers.py

@@ -0,0 +1,8 @@
+"""
+CUSTOMERS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement customers endpoints

src/app/api/v1/documents.py

@@ -0,0 +1,8 @@
+"""
+DOCUMENTS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement documents endpoints

src/app/api/v1/expenses.py

@@ -0,0 +1,8 @@
+"""
+EXPENSES Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement expenses endpoints

src/app/api/v1/health.py

@@ -0,0 +1,8 @@
+"""
+HEALTH Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement health endpoints

src/app/api/v1/incidents.py

@@ -0,0 +1,8 @@
+"""
+INCIDENTS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement incidents endpoints

src/app/api/v1/inventory.py

@@ -0,0 +1,8 @@
+"""
+INVENTORY Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement inventory endpoints

src/app/api/v1/media.py

@@ -0,0 +1,8 @@
+"""
+MEDIA Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement media endpoints

src/app/api/v1/organizations.py

@@ -0,0 +1,8 @@
+"""
+ORGANIZATIONS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement organizations endpoints

src/app/api/v1/pages.py

@@ -0,0 +1,69 @@
+"""
+Page Routes (HTML Templates)
+Separate from API routes for clean architecture
+"""
+from fastapi import APIRouter, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+from datetime import datetime
+from pathlib import Path
+from app.constants.app_metadata import (
+    APP_NAME,
+    APP_VERSION,
+    APP_DESCRIPTION,
+    APP_GITHUB_URL,
+    DOCS_URL,
+    REDOC_URL
+)
+
+# Get templates directory
+templates_dir = Path(__file__).parent.parent.parent / "templates"
+templates = Jinja2Templates(directory=str(templates_dir))
+
+router = APIRouter(tags=["Pages"])
+
+
+@router.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def index(request: Request):
+    """
+    Landing page - displays API information and available endpoints
+    """
+    # Application metadata
+    app_data = {
+        "app_name": APP_NAME,
+        "app_version": APP_VERSION,
+        "app_description": APP_DESCRIPTION,
+        "current_year": datetime.now().year,
+        "github_url": APP_GITHUB_URL,
+    }
+    
+    # Available endpoints (will be dynamically generated later)
+    endpoints = [
+        {
+            "method": "GET",
+            "path": "/health",
+            "description": "Health check endpoint to verify API availability and system status.",
+            "status": "Operational"
+        },
+        {
+            "method": "GET",
+            "path": "/api/docs",
+            "description": "Interactive API documentation powered by Swagger UI.",
+            "status": "Operational"
+        },
+        {
+            "method": "GET",
+            "path": "/api/redoc",
+            "description": "Alternative API documentation with ReDoc interface.",
+            "status": "Operational"
+        },
+    ]
+    
+    return templates.TemplateResponse(
+        "index.html",
+        {
+            "request": request,
+            **app_data,
+            "endpoints": endpoints,
+        }
+    )

src/app/api/v1/payroll.py

@@ -0,0 +1,8 @@
+"""
+PAYROLL Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement payroll endpoints

src/app/api/v1/projects.py

@@ -0,0 +1,8 @@
+"""
+PROJECTS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement projects endpoints

src/app/api/v1/reports.py

@@ -0,0 +1,8 @@
+"""
+REPORTS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement reports endpoints

src/app/api/v1/router.py

@@ -0,0 +1,18 @@
+"""
+Main API Router - Aggregates all v1 endpoints
+"""
+from fastapi import APIRouter
+
+# Import all routers
+# from app.api.v1 import auth, users, organizations, projects, tickets
+
+api_router = APIRouter()
+
+# Include all routers
+# api_router.include_router(auth.router, prefix="/auth", tags=["Authentication"])
+# api_router.include_router(users.router, prefix="/users", tags=["Users"])
+# api_router.include_router(organizations.router, prefix="/organizations", tags=["Organizations"])
+# api_router.include_router(projects.router, prefix="/projects", tags=["Projects"])
+# api_router.include_router(tickets.router, prefix="/tickets", tags=["Tickets"])
+
+# TODO: Include remaining routers as they are implemented

src/app/api/v1/sales_orders.py

@@ -0,0 +1,8 @@
+"""
+SALES ORDERS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement sales_orders endpoints

src/app/api/v1/subscriptions.py

@@ -0,0 +1,8 @@
+"""
+SUBSCRIPTIONS Endpoints
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# TODO: Implement subscriptions endpoints