# bhupesh-debug/staffpilot architecture

> Architecture diagram of the GitHub repository bhupesh-debug/staffpilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhupesh-debug/staffpilot
- Repository: https://github.com/bhupesh-debug/staffpilot

## Overview

StaffPilot is a B2B staffing-operations platform, with a separate static marketing site. The application is a Phase 3 scaffold: its landing and login pages are present, but live sign-in and operational workflows are not yet wired. The intended product flow covers assignments, timesheet submission and approvals, billing, and payroll-preparation estimates; reports and C2C vendor tracking are documented capabilities. Workflow edges reflect the README or the sampled landing page, not inspected operational handlers or migrations.

Main entry points: [`app/app/page.tsx`](https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/page.tsx) (Application home), [`app/src/lib/state-machines.ts`](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/state-machines.ts) (Timesheets), [`app/supabase/migrations`](https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations) (Assignments), [`app/app/login/page.tsx`](https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/login/page.tsx) (Sign-in placeholder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Staffing operations"]
  node_assignments["Assignments"]
  node_timesheets["Timesheets<br/>[state-machines.ts]"]
  node_clients_workers["Clients and workers"]
  node_c2c_tracking["C2C vendor tracking"]
end

subgraph group_finance["Billing and payroll prep"]
  node_billing["Invoices and billing"]
  node_payroll_prep["Payroll estimates<br/>[state-machines.ts]"]
  node_profitability["Margin and utilization<br/>[money.ts]"]
end

subgraph group_foundation["Application foundation"]
  node_app_home["Application home<br/>[page.tsx]"]
  node_login["Sign-in placeholder<br/>[page.tsx]"]
  node_money_math["Decimal money math<br/>[money.ts]"]
  node_access["Roles and permissions<br/>[permissions.ts]"]
  node_tenant_db[("Tenant database and RLS")]
  node_supabase_client["Supabase clients<br/>[supabase.ts]"]
  node_health["Health endpoint<br/>[route.ts]"]
end

subgraph group_public["Public presence"]
  node_marketing["Marketing website<br/>[index.html]"]
end

node_firm_user(("Firm user"))

node_firm_user -->|"opens"| node_app_home
node_firm_user -->|"signs in"| node_login
node_app_home -->|"documents capability"| node_assignments
node_app_home -->|"documents capability"| node_timesheets
node_app_home -->|"documents capability"| node_billing
node_app_home -->|"documents capability"| node_payroll_prep
node_assignments -->|"timesheet workflow"| node_timesheets
node_timesheets -->|"approved hours feed"| node_billing
node_timesheets -->|"approved hours feed"| node_payroll_prep
node_assignments -->|"tracks vendors"| node_c2c_tracking
node_assignments -->|"reports margin"| node_profitability
node_timesheets -->|"reports utilization"| node_profitability
node_billing -->|"uses exact decimals"| node_money_math
node_payroll_prep -->|"uses exact decimals"| node_money_math
node_access -->|"RLS enforced"| node_tenant_db
node_supabase_client -->|"connects to"| node_tenant_db
node_login -.->|"planned auth"| node_supabase_client
node_firm_user -.->|"visits"| node_marketing

click node_app_home "https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/page.tsx"
click node_login "https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/login/page.tsx"
click node_assignments "https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations"
click node_timesheets "https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/state-machines.ts"
click node_clients_workers "https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations"
click node_c2c_tracking "https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations"
click node_billing "https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations"
click node_payroll_prep "https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/state-machines.ts"
click node_profitability "https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/money.ts"
click node_money_math "https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/money.ts"
click node_access "https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/permissions.ts"
click node_tenant_db "https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations"
click node_supabase_client "https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/supabase.ts"
click node_health "https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/api/health/route.ts"
click node_marketing "https://github.com/bhupesh-debug/staffpilot/blob/main/website/index.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_assignments,node_timesheets,node_clients_workers,node_c2c_tracking,node_firm_user toneBlue
class node_billing,node_payroll_prep,node_profitability toneAmber
class node_app_home,node_login,node_money_math,node_access,node_tenant_db,node_supabase_client,node_health toneMint
class node_marketing toneRose
```

## Components

### Staffing operations

- [Assignments](https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations): `app/supabase/migrations`
- [Timesheets](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/state-machines.ts): `app/src/lib/state-machines.ts`
- [Clients and workers](https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations): `app/supabase/migrations`
- [C2C vendor tracking](https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations): `app/supabase/migrations`

### Billing and payroll prep

- [Invoices and billing](https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations): `app/supabase/migrations`
- [Payroll estimates](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/state-machines.ts): `app/src/lib/state-machines.ts`
- [Margin and utilization](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/money.ts): `app/src/lib/money.ts`

### Application foundation

- [Application home](https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/page.tsx): `app/app/page.tsx`
- [Sign-in placeholder](https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/login/page.tsx): `app/app/login/page.tsx`
- [Decimal money math](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/money.ts): `app/src/lib/money.ts`
- [Roles and permissions](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/permissions.ts): `app/src/lib/permissions.ts`
- [Tenant database and RLS](https://github.com/bhupesh-debug/staffpilot/tree/main/app/supabase/migrations): `app/supabase/migrations`
- [Supabase clients](https://github.com/bhupesh-debug/staffpilot/blob/main/app/src/lib/supabase.ts): `app/src/lib/supabase.ts`
- [Health endpoint](https://github.com/bhupesh-debug/staffpilot/blob/main/app/app/api/health/route.ts): `app/app/api/health/route.ts`

### Public presence

- [Marketing website](https://github.com/bhupesh-debug/staffpilot/blob/main/website/index.html): `website/index.html`

### Other components

- **Firm user**

## Connections

- Firm user → Application home: opens (evidence: `app/app/page.tsx`)
- Firm user → Sign-in placeholder: signs in (evidence: `app/app/login/page.tsx`)
- Application home → Assignments: documents capability (evidence: `app/app/page.tsx`)
- Application home → Timesheets: documents capability (evidence: `app/app/page.tsx`)
- Application home → Invoices and billing: documents capability (evidence: `app/app/page.tsx`)
- Application home → Payroll estimates: documents capability (evidence: `app/app/page.tsx`)
- Assignments → Timesheets: timesheet workflow (evidence: `README.md`)
- Timesheets → Invoices and billing: approved hours feed
- Timesheets → Payroll estimates: approved hours feed (evidence: `README.md`)
- Assignments → C2C vendor tracking: tracks vendors (evidence: `README.md`)
- Assignments → Margin and utilization: reports margin (evidence: `README.md`)
- Timesheets → Margin and utilization: reports utilization (evidence: `README.md`)
- Invoices and billing → Decimal money math: uses exact decimals
- Payroll estimates → Decimal money math: uses exact decimals (evidence: `app/src/lib/money.ts`)
- Roles and permissions → Tenant database and RLS: RLS enforced (evidence: `app/src/lib/permissions.ts`)
- Supabase clients → Tenant database and RLS: connects to (evidence: `app/src/lib/supabase.ts`)
- Sign-in placeholder → Supabase clients: planned auth (evidence: `app/app/login/page.tsx`)
- Firm user → Marketing website: visits (evidence: `README.md`)
