admin/38156-vm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/ai-dev' into claude/loving-buck

Browse Source
This commit is contained in:
Konradzar 2026-02-08 23:43:47 +02:00
commit 95979921dc
1 changed files with 96 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
APP_DOCUMENTATION.md Normal file
View File

@ -0,0 +1,96 @@
# Comprehensive Application Documentation: Fox Fitt Management System
## 1. Executive Summary
The Fox Fitt Management System is a specialized ERP/CMS designed for the **Energy & Utilities** industry. It provides a centralized platform for managing work projects, field worker attendance, payroll processing, employee loans, and business expenses. The system is built to handle the complexities of field operations, ensuring that labor costs are accurately tracked and that workers are paid correctly based on their daily contributions.
---
## 2. Core Functionalities (What the App Does)
- **Attendance Tracking:** Allows supervisors to log worker attendance for specific projects, either daily or across a date range. It features a conflict detection system to prevent double-logging.
- **Payroll Management:** A comprehensive dashboard that calculates worker pay based on logged days, daily rates, and financial adjustments (bonuses, deductions, loan repayments).
- **Loan Management:** Tracks advances given to workers, including principal amounts and remaining balances, with automated deduction capabilities during payroll.
- **Expense Digitization:** A module to record business expenses, generate digital receipts, and integrate with external bookkeeping systems like Spark AI.
- **Resource Management:** CRUD (Create, Read, Update, Delete) operations for Projects, Workers, and Teams, including the ability to toggle active/inactive status.
- **Automated Document Generation:** Generates PDF payslips and receipts that can be emailed directly to workers or financial systems.
---
## 3. Database Structure & Models
The application utilizes a relational database (MariaDB/MySQL) with the following key models:
### User & Authentication
- **User (Django Built-in):** Standard authentication.
- **UserProfile:** Extends the User model to include a **4-digit PIN** (for quick field access) and an `is_admin` flag to distinguish between supervisors and management.
### Organizational Structure
- **Project:** Represents specific work sites or contracts. Tracks whether a project is active and which supervisors are assigned to it.
- **Worker:** Stores worker profiles, including identification numbers, contact details, monthly salary, and employment dates. It calculates a `day_rate` automatically based on the monthly salary (assuming 20 working days).
- **Team:** A grouping of workers assigned to a specific supervisor, facilitating quick attendance logging.
### Operational Data
- **WorkLog (Attendance):** The central record of labor. Links multiple workers to a specific project on a specific date.
- **PayrollRecord:** A record of a completed payment to a worker. It links to the specific `WorkLog` entries being paid.
- **Loan:** Tracks financial advances given to workers, managing the `balance` as repayments are made.
- **PayrollAdjustment:** Records bonuses, overtime, deductions, and loan repayments that modify the final payout in a `PayrollRecord`.
### Financial Data
- **ExpenseReceipt:** Records vendor information, dates, payment methods, and VAT types for business expenditures.
- **ExpenseLineItem:** Individual line items within a receipt, allowing for detailed expense breakdown.
---
## 4. Workflows & Process Logic
### A. Attendance Logging Workflow
1. **Selection:** Supervisor selects a project, a date (or range), and the workers/teams present.
2. **Conflict Check:** The system checks if any selected worker is already logged on the chosen dates.
3. **Resolution:** If conflicts exist, the supervisor can choose to:
- **Skip:** Only log workers who aren't already recorded.
- **Overwrite:** Remove workers from previous logs for those dates and add them to the new one.
4. **Finalization:** Work logs are created and become available for payroll processing.
### B. Payroll Workflow
1. **Calculation:** The system identifies all unpaid `WorkLog` entries for a worker.
2. **Adjustments:** The manager adds bonuses or deductions. If the worker has an active `Loan`, a repayment adjustment is automatically calculated.
3. **Execution:** The payment is "processed," creating a `PayrollRecord` and marking the logs as paid.
4. **Distribution:** A PDF payslip is generated and can be sent via email. The system specifically identifies the worker as the **Beneficiary** to ensure third-party systems (like Spark AI) map payments correctly.
### C. Expense Management Workflow
1. **Entry:** User enters receipt details (vendor, items, VAT).
2. **Generation:** A professional PDF receipt is generated.
3. **Integration:** The receipt is optionally emailed to a designated bookkeeping address (e.g., Spark AI) for automated accounting.
---
## 5. Menus & Navigation
The application uses a sidebar-driven navigation structure:
- **Dashboard (Home):** Real-time analytics showing total workers, active project costs, outstanding payments, and recent activity.
- **Log Attendance:** The primary interface for field supervisors to record daily work.
- **Work Log History:** A searchable/filterable list of all attendance records, with CSV export functionality.
- **Manage Resources:** A management hub for adding or editing Workers, Projects, and Teams.
- **Payroll Dashboard:** The financial center for reviewing unpaid work and processing monthly/weekly payments.
- **Loans:** Tracking and issuing worker advances.
- **Create Receipt:** Interface for digitizing business expenses on the go.
---
## 6. Security & Permissions
- **PIN Authentication:** In addition to standard passwords, users can log in via a 4-digit PIN, optimized for mobile use in the field.
- **Role-Based Access (RBAC):**
- **Supervisors:** Can only see and log attendance for their assigned projects and teams.
- **Admins:** Have full access to payroll, financial adjustments, and global resource management.
- **Data Integrity:** Cascading deletes are carefully managed (e.g., using `SET_NULL` for supervisors) to ensure historical logs remain intact even if a supervisor leaves.
---
## 7. Technical Architecture
- **Framework:** Django 5.x (Python 3.11).
- **Frontend:** HTML5, Bootstrap 5 (with custom Material Design-inspired styling), and vanilla JavaScript for dynamic calculations and form handling.
- **PDF Engine:** Utilizes a custom utility to render Django templates into PDF documents.
- **Email System:** Integrated SMTP settings for automated delivery of payslips and expense reports.
- **Environment:** Served via Apache as a reverse proxy, with systemd managing the Django development service for high availability.
---
*Document Version: 1.0*
*Date: February 8, 2026*