38156-vm/CLAUDE.md

Fox Fitt LabourPay

Coding Style

• Always add clear section header comments using the format: # === SECTION NAME ===
• Add plain English comments explaining what complex logic does
• The project owner is not a programmer — comments should be understandable by a non-technical person
• When creating or editing code, maintain the existing comment structure

Project Overview

Django payroll management system for Fox Fitt Construction, a civil works contractor specializing in solar farm foundation installations. Manages field worker attendance, payroll processing, employee loans, and business expenses for solar farm projects.

Tech Stack

• Django 5.x, Python 3.11, MariaDB
• Bootstrap 5 with Material Design-inspired styling, vanilla JavaScript
• PDF generation for payslips and receipts
• SMTP email integration for automated document delivery
• Apache reverse proxy with systemd service management

Project Structure

• config/ — Django project settings, URLs, WSGI/ASGI entrypoints
• core/ — Single main app containing ALL business logic, models, views, forms, templates, and migrations
• ai/ — Local AI API integration module
• media/workers/ids/ — Worker ID photo uploads
• static/ — Source static files (custom CSS)
• staticfiles/ — Collected static assets (Bootstrap, Popper.js, admin)

Key Business Rules

• All business logic lives in the core/ app — do not create additional apps
• Workers have a day_rate calculated automatically from monthly salary / 20 working days
• PIN authentication (4-digit) exists alongside password auth for quick field access
• Supervisors can only see their assigned projects and teams
• Admins have full access to payroll, adjustments, and resource management
• WorkLog is the central attendance record — links workers to projects on specific dates
• Attendance logging includes conflict detection to prevent double-logging
• Loans have automated repayment deductions during payroll processing
• Cascading deletes use SET_NULL for supervisors to preserve historical data

Key Models

• UserProfile — extends User with PIN and is_admin flag
• Project — work sites/contracts with supervisor assignments
• Worker — profiles with salary, day_rate, employment details
• Team — groups of workers under a supervisor
• WorkLog — daily attendance records (worker + project + date)
• PayrollRecord — completed payments linked to WorkLog entries
• PayrollAdjustment — bonuses, deductions, overtime, loan repayments
• Loan — worker advances with balance tracking
• ExpenseReceipt / ExpenseLineItem — business expense records

Commands

• python manage.py runserver 0.0.0.0:8000 — run dev server
• python manage.py migrate — apply database migrations
• python manage.py collectstatic — collect static files for production
• python manage.py setup_groups — configure permission groups
• python manage.py update_permission_names — update permission display names
• python manage.py check — system check (ignore staticfiles warnings about missing assets/ and node_modules/ dirs — pre-existing, harmless)

Development Workflow

• Active development branch: ai-dev (PR target: master)
• Admin check in views: is_admin(request.user) helper (imported at top of views.py)
• "Unpaid" adjustment = payroll_record__isnull=True (no linked PayrollRecord)
• POST-only mutation views pattern: check request.method != 'POST' → redirect, then process
• Template UI pattern: Bootstrap 5 modals with dynamic JS wiring, data-* attributes on clickable elements

PayrollAdjustment Type Handling

• BONUS / DEDUCTION — standalone, no linked objects
• LOAN — links to Loan model via adj.loan FK; editing syncs loan amount/balance/reason; deleting cascades to Loan + unpaid repayments (blocked if paid repayments exist)
• OVERTIME — links to WorkLog via adj.work_log FK; deleting removes worker from work_log.overtime_paid_to M2M (un-prices the OT)
• LOAN_REPAYMENT — links to Loan via adj.loan FK; loan balance only changes during payment processing

Important Context

• Read APP_DOCUMENTATION.md for detailed workflows (attendance, payroll, expenses)
• Environment variables loaded from ../.env
• The owner (Konrad) is not a developer — explain changes clearly and avoid unnecessary complexity
• This system handles real payroll for 14 field workers — accuracy is critical