Expenses Module

- What the Expenses Module
 

The Expenses Module is not just a data entry screen.

It is a financial control layer designed to capture, organize, validate, analyze, and connect outgoing business costs with suppliers, documents, projects, taxes, and revenue.
 

It works as the counterpart to the Documents (Income) module, enabling a full Profit & Loss view of the organization.
 

In short:
 

Documents = Money Coming In
Expenses = Money Going Out

Together, they power financial accuracy, compliance, and decision-making.



 

- Core Business Purpose
 

The Expenses Module exists to solve these problems:
 

• Scattered expense records

• Lost invoices & receipts

• No clear supplier expense history

• No monthly or yearly cost visibility

• No project-based cost tracking

• Manual tax calculations

• Difficulty reconciling expenses with accounting
   

The module converts raw expense data into structured, reportable, and auditable financial records.



 

- Fundamental Design Principles
 

The Expenses Module is built on five core principles:
 

1. Categorization

2. Traceability

3. Time Accuracy

4. Supplier Accountability

5. Financial Analytics
    

Every feature supports at least one of these principles.


 

-  What an Expense Actually Represents
 

Each expense record represents one financial outflow event, such as:
 

• Paying a supplier

• Receiving an invoice

• Paying via check or credit card

• Recording operational costs

• Logging tax-related payments
   

An expense always answers:

 

-  What an Expense Actually Represents
 

Each expense record represents one financial outflow event, such as:
 

• Paying a supplier

• Receiving an invoice

• Paying via check or credit card

• Recording operational costs

• Logging tax-related payments
   

An expense always answers:

questions :-


What was paid?       =        Amount + Category
To whom?                =        Supplier
Why?                       =        Notes + Category
When?                     =        Payment / Document / Created date
For which project?   =        Project link
Is tax included?       =        VAT flag
Proof?                     =         Attached document


 

-  Expense Lifecycle – Step-By-Step Flow
 

1️⃣ Expense Creation
 

When a user adds an expense:
 

• Category is selected (mandatory)

• Amount is entered

• Supplier is linked

• Document type is chosen

• Dates are defined

• VAT inclusion is marked

• Files/images are attached

• Optional project/customer is linked
   

The system then:
 

✔ Validates inputs
✔ Verifies invoice number (if provided)
✔ Determines paid status
✔ Saves financial data
✔ Stores files securely


 

Document Type Behavior (Important Logic)
 

The document_type field affects system behavior:


Document Type                   Paid status                       Purpose

Invoice                                  unpaid by default           Supplier Invoice  
receipt                                   paid                                Proof of payment
receipt_tax_invoice              paid                               Legal text invoice
delivery_invoice                   unpaid                            Delivery Confirmation


This ensures financial realism instead of manual assumptions.


 

3️⃣ VAT & Tax Handling
 

VAT logic is handled using vat_includes:

• 0 → Amount is net (VAT excluded)

• 1 → Amount includes VAT
   

The system then:
 

✔ Separates tax amount
✔ Includes it in reports
✔ Feeds pie-chart tax analytics
 

This allows accurate tax reporting and compliance.


 

4️⃣ Category-Based Expense Architecture
 

Expenses are always grouped under categories.
 

Categories:
 

• Are user-specific or global

• Support multi-language names

• Drive analytics & charts

• Control grouping & exports
   

Deleting a category does not delete expenses, preserving historical accuracy.


 

5️⃣ Supplier-Centric Expense Tracking
 

Each expense can be linked to a supplier.
 

This allows:
 

• Viewing supplier cost history

• Filtering expenses by supplier

• Invoice duplication prevention

• Long-term supplier analysis
   

Suppliers act as financial identities, not just contacts.



 

6️⃣ Date Intelligence (Critical Feature)
 

Expenses support three different date dimensions


Data Type                                      Meaning

Payment Date                               When money left
Docuemnt Date                             Invoice/Receipt Date
Created Time                                 System record time

Filters can be applied to any date type, which is crucial for:
 

✔ Accounting
✔ Audits
✔ Cash-flow analysis


 

7️⃣ Paid Status Logic
 

Each expense has a paid_status:
 

• Automatically set for receipts

• Manually adjustable if needed

• Used for financial tracking

• Supports future reconciliation
   

This allows separation between:
 

-  Revenue vs Expense Analysis (Pie Chart)
 

• Expenses incurred

• Expenses actually paid
  
  
   

  -  Financial Analytics Engine
   

  The Expenses Module powers two financial perspectives:
   

  -  Cost Trend Analysis (Line Chart)
   

• Monthly category spending

• Yearly comparison

• Budget trend visibility

• Category growth tracking
   

• Combines:
   

• Income (from Documents)

• Expenses

• Revenue (profit)

• Tax totals

• This creates a live P&L snapshot per month.
  
  
   

  -  File & Evidence Management
   

  Each expense can include:
   

• Multiple images

• Invoice scans
   

• Files are:

• Stored securely

• Linked to expense

• Used during audits

• Available in exports
  
  
   

  -  Module Connections (Why This Module Matters)
   

  The Expenses Module is deeply connected to:
   

  - Documents Module
   

• Revenue & tax calculation

• Profit computation

• Financial balance
   

• - Projects Module
   

• Project cost tracking

• Profitability per project
   

• - Customers Module
   

• Customer-related expenses

• Cost attribution

• Financial widgets

• Expense summaries
   

• - Calendar Module
   

• Timeline view of expenses
   

• - Reports Module
   

• Excel exports

• Accounting handoff
  
   

  - Permissions & Security
   

  Expenses are protected by:
   

• Module access control

• Organization scoping
   

• Users can only:
  
  ✔ View allowed data
  ✔ Edit permitted records
  
  
   

  -  Final Summary
   

  The Expenses Module is a financial backbone that transforms everyday costs into structured financial intelligence.
   

  It ensures:
   

• Every expense is documented

• Every supplier cost is traceable

• Every tax amount is calculated

• Every project cost is visible

• Every decision is data-driven

• Role-based permissions
  
  
  This module is essential for financial discipline, compliance, and business growth.