Team
+Full finance hub at /invoices.
+Handles client invoices, expenses, subcontractor invoices, and subcontractor purchase orders.
+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.
+
+
+
+
+
+
+
+
+ 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 |