Fourge Portal Finance Summary

Role cheat sheet, finance lanes, and data flow for team, client, and subcontractor users.

1. Executive Summary

The finance area is not one shared page for all roles. It is split into three lanes with different permissions and different page sets.

Team

Full finance hub at /invoices.

Handles client invoices, expenses, subcontractor invoices, and subcontractor purchase orders.

Client

Invoice-only lane at /my-invoices.

Clients can view invoices, filter by company, and download PDFs.

Subcontractor

Two finance lanes: /my-invoices-sub and /my-purchase-orders.

They can submit invoices to Fourge and approve POs sent by Fourge.

2. Role-by-Role Cheat Sheet

Role	Main Routes	Can Do	Cannot Do
Team	/invoices	Create/send client invoices, track expenses, create POs, review subcontractor invoices, mark paid, export/send PDFs	Not limited in finance UI
Client	/my-invoices	View invoices, filter by company, download invoice PDFs	No expenses, no invoice editing, no POs, no subcontractor finance tools
Subcontractor / External	/my-invoices-sub /my-purchase-orders	Create/submit invoices to Fourge, view status, download receipts after payment, approve POs	No team finance overview, no client invoice management, no internal expenses

3. Core Data Models

invoices

invoice_items

expenses

subcontractor_invoices

subcontractor_invoice_items

subcontractor_payments

subcontractor_po_items

tasks

submissions

companies

profiles

Simple mental model: invoices bill clients, expenses track internal costs, subcontractor_invoices let subcontractors bill Fourge, and subcontractor_payments are POs Fourge sends to subcontractors.

4. System Flow

Client Billing Flow

Approved client work reaches tasks.status = client_approved.

Team finance loads uninvoiced tasks and revisions, builds line items, saves an invoice, and emails the PDF to the client.

Later, team marks the invoice paid.

Expense Flow

Team logs expenses, optionally with receipt files.

Expenses feed overview charts, yearly summaries, and profit calculations.

Subcontractor Invoice Flow

Subcontractor creates an invoice from completed approved tasks assigned to them.

Fourge reviews it, then marks it paid and sends a receipt PDF back.

Purchase Order Flow

Team creates a PO for a subcontractor, optionally tied to project tasks.

Subcontractor reviews the PO and can approve it from their own portal view.

5. Status Logic

Client Invoice

draft → sent → paid

Subcontractor Invoice

draft → submitted → paid

Purchase Order

draft → sent → approved → ready_to_pay → paid

cancelled is exit state.

6. Key Business Rules

Client invoices only pull approved, uninvoiced work.
Tasks and revisions are marked invoiced after invoice creation.
Deleting a team invoice rolls linked invoice flags back.
Team invoice status changes also push task status changes.
Revision billing rule: R00 = new work, R01 = free, R02+ = billable increments.
Subcontractor invoices are created by the external user and then reviewed/paid by team.
POs are created by team and approved by the subcontractor.

7. Database Relationship Chart

COMPANIES └─ invoices └─ invoice_items ├─ task_id → tasks └─ submission_id → submissions PROJECTS └─ tasks └─ submissions PROFILES (external) ├─ subcontractor_invoices │ └─ subcontractor_invoice_items │ └─ task_id → tasks └─ subcontractor_payments (POs) └─ subcontractor_po_items └─ task_id → tasks EXPENSES └─ standalone internal finance records

8. Quick Route Map

Surface	Route	User
Finance Hub	/invoices	Team
Client Invoices	/my-invoices	Client
Subcontractor Invoices	/my-invoices-sub	External
Create Subcontractor Invoice	/my-invoices-sub/new	External
Purchase Orders	/my-purchase-orders	External