The TPA Ops playbook.

01 — Welcome

What is TPA Ops?

TPA Ops is the single place where the firm tracks everything that touches money and work. If it was in a spreadsheet before, it lives here now.

TPA Ops replaces a sprawl of Excel files, Google Sheets and informal tracking with one opinionated platform. It's where we record every contract we sign, every project we deliver, every milestone we bill against, every rupee that comes in, and every decision we make about who gets paid what.

The goals

02 — Mental model

The big picture in 60 seconds.

TPA's work is shaped like this. If you understand this one diagram, the rest of the platform falls into place.

Reading left to right:

1. A client wants work done. They sign with TPA.
2. A contract captures the deal — what services, how much money, when signed, for how long.
3. Each service becomes a project. If a contract covers Architecture and Interior, that's two projects.
4. Every project builds a payment schedule — the list of milestones we bill against, each with a fee.
5. When money comes in, it's recorded as a receipt, which fills up the payment schedule from the top down.

Everything else on the platform — Receivables, Payout, Commission Ledger, Status Updates, Approvals, Meetings — supports this core flow.

03 — Orientation

Your first login.

Here's what you're looking at when you land on TPA Ops for the first time.

The left sidebar

The main menu. Every module is one click away. The items you see depend on your role — a super admin sees everything; a PM with only status-update rights sees a much shorter list; Finance sees money modules the PMs don't.

Dashboard

Your homepage with key numbers at a glance.

Contracts

Every contract the firm has ever signed.

Projects

Every project — one row per project per service.

Status Updates

A simpler view for PMs — progress only, no money shown.

Receivables

Every receipt from a client, mapped to a project deliverable.

Commission Ledger

Who earned what commission, per receipt, period by period. The abuse-killer drill-down lives here.

Approvals

Things waiting for your sign-off — contract amendments, receipt remaps, ledger corrections, period close.

Meetings

Review meetings, agenda items, and action items with owners.

Employees

The people who work at TPA — payroll, home offering, payout category, platform access.

Masters

Dropdown lists (statuses, locations, project types).

Admin

RBAC (roles + permissions), platform access, integrations, email configuration.

Top-right corner

A bell icon 🔔 sits pinned in the top-right of every page. Click it for notifications — things that happened you might care about, like approvals pending or receipts received. It auto-refreshes every 30 seconds.

Bottom-left of the sidebar

Your name, a theme toggle (light/dark), and a sign-out button. Always pinned at the bottom even when the nav is long.

Forgot your password

The login page has a Forgot? link next to the password label. Click it, type your email, hit Send reset link. Supabase emails you a recovery link within ~1 minute. Click it, set a new password, you're back in. No need to bother an admin for routine resets.

If your admin set you up with a temp password (e.g. TpaOps@<your-e-code>), the recommended first action is to log in once with the temp, then immediately use Forgot to set something memorable. Note that there isn't yet an in-session "change my password" page — the Forgot flow is the canonical path either way.

04 — Super admin

One-time setup.

Three things to seed before anyone uses the platform in anger. Do this once, then forget about it.

4.1 — Dropdown master

Go to Masters in the sidebar. This is where the lists that appear in every dropdown on the platform live.

There are seven categories:

Each option has a label (the text everyone sees) and an optional colour (shows as a badge border — great for status categories so red means terminated, green means active, etc.).

4.2 — Employees

Go to Employees. Add everyone on payroll. This is the canonical employee master — one row per person, always.

For each employee:

Once dropdowns and employees are seeded, you're ready for real work.

05 — The loop

The core workflow.

The day-to-day rhythm. Seven steps that repeat forever.

1. A client signs a contract. Someone at TPA creates the contract in the platform with the terms, value, and services.
2. The contract covers one or more services. Each service needs a project. One contract = one or more projects.
3. Projects and contracts get linked. The platform tracks which contract funds which project and how much money is allocated.
4. Each project builds a payment schedule. Milestones like Concept Design, Schematic, DDs, CDs — each with a fee and a due date.
5. Work happens. The PM updates progress weekly and marks milestones as in_progress or completed.
6. Money comes in. Recorded as receipts, which fill the payment schedule from the top down.
7. At period-close, Finance reconciles. The commission ledger closes for the period. Payouts for PNL / MGP / Variable / normal employees get settled based on that period's receipts.

Every step writes to the audit trail. You can always go back and see who did what, when, and why.

06 — Module deep dive

Contracts.

The legal document with the client. The starting point of everything else.

The list view

Go to Contracts in the sidebar. You see every contract in one table:

Above the table: a search box for client names, filters for status and service, and a sort widget where you pick any column and direction.

Creating a new contract

Click New contract in the top-right. The form has these fields:

Click Create. The contract lands in the list.

Moved to the project module (May 2026): Area (Sq Ft) and Per Sq Ft Rate used to live on the contract. They're now per-project — a contract may bundle Architecture + Interior in different areas, so sqft can't sit at the contract grain. Set them on each linked project after creation.

The contract detail page

Clicking a contract opens its detail page with three tabs:

Overview tab

An editable form with everything you entered. The Save button lives inside the card top-right — changes don't save until you click it. At the bottom: Attachments. Upload PDFs, Word, Excel, or images. Pick the kind — Original / Amendment / Addendum / Other. Each attachment row has three buttons:

• View — opens the file in a new tab so you can preview without downloading.
• Download — saves the file to your machine with the original filename.
• Remove — appears on hover; deletes the attachment after a confirmation.

Projects tab

The key bit. Shows every project linked to this contract with their allocated value and status.

You can:

• Link existing — pick any project from the full list (no status filter) and set its allocation. The reverse flow lives on the Project's Contracts tab — see §7 Projects.
• Create project — quick-create from this contract. Gets auto-linked.

The Unallocated card at the top nudges you: if there's still money not assigned to a project, the card gets a gold border.

What the backend enforces on every link (regardless of which side you started from): the project's service must be in the contract's services array; the new allocation + existing allocations can't exceed the contract value; the same (contract, project) pair can't be linked twice. Status of either side doesn't gate eligibility — a "Pitch - Active" project can be linked to a signed contract, an "On hold" project still receives receipts via its links.

Amendments tab

Change log. When a signed contract needs to be modified:

The Terminate button

Top-right of the contract detail page. For when a contract dies mid-way — client walked away, deal fell through, any "this contract is dead" situation.

Click it → dialog asks for a reason → confirm → status flips to terminated, all active project links cascade to terminated, everything gets logged. Nothing is deleted. The paper trail stays intact.

07 — Module deep dive

Projects.

A chunk of work TPA delivers. One service = one project.

The list view

Simple table: Project ID / Service / Name / Site / Start date / Status. Filters for status and service. Click any row to drill in.

Creating a new project

Click Create. The project exists but isn't linked to a contract yet — do that from the contract detail page.

The project detail page

Where the project's story lives. Four summary cards at the top:

The Work Progress card is clickable. Click it → a dialog opens where the PM can set the new percentage (0-100), add notes ("Mid-CDs, client review next Tuesday"), and see when it was last updated. Every update is audited.

Tabs: Overview · Details · Payment Schedule · Contracts · Payout · Audit

The KPI cards sit above the tabs. Each tab is its own surface:

• Overview — Financials card (Project Value / Contracts / Received / Pending), per-contract breakdown, and the alignment chip.
• Details — Area & Rate, General Info (Site location, City, Description, Expected close date), and Project Owners. Each section is its own Card with an Edit button; everything edits in place. New in May 2026 — these three blocks used to sprawl across the top of the page; they're now in one tab.
• Payment Schedule — milestone rows (see §8).
• Contracts — every contract linked to this project. Two buttons: Link existing contract (pick any contract, set allocation) and Create contract from this project (quick-create). The existing-link picker excludes contracts that are already linked.
• Payout — per-project commission configuration (see §11).
• Audit — append-only log of every change.

Project Value & Alignment

One number, set once, reads everywhere. Where "Project Value" comes from and what the alignment chip is telling you.

Project Value is the single source of truth for a project's money. It's the number the project is budgeted at — not the contract, not the payment schedule sum, not the allocation. Every downstream view (Overview financials, Payment Schedule %, Contract breakdown, Payout projections) derives from it.

Where the value comes from

The alignment chip

Sitting next to Project Value on the detail page is a small chip that compares Project Value against the sum of active contract allocations. Four states:

The tabs below the cards

Overview

The Financials card is the centrepiece: three numbers (Value, Received, Pending) and a green progress bar showing % received.

Below those numbers, a chevron toggle labelled "By contract" — click to expand a mini-table showing each funding contract with its own Value / Received / Pending breakdown. Collapsed by default so the summary stays clean.

Below the Financials card, the Project details card: Project ID & Name, Location & Project Type, Start date & Contract expected by, plus any progress notes.

Payment Schedule

The milestone list. See the full walkthrough below.

Contracts

Every contract funding this project. Usually just one, but in the phased-funding case, two or more.

Payout

The per-project payout configuration — who on TPA gets a cut of this project's receipts, at what rate, for which date range, and with which receipts excluded.

Each person you add is an assignment (project × employee). Each assignment has one or more rate periods (date-effective). Any receipt can be excluded from an assignment with a reason. The Ledger view inside the tab shows the per-receipt projection — what each person would earn on every receipt — with exclusions, uncovered periods, and rate mismatches called out in gold.

Full walkthrough in the Payout module section.

Audit

The full change log for this project. Every edit, every status transition, every financial adjustment, every progress update. Stamped with who, when, and the before/after. No way to delete entries — that's the whole point.

08 — Module deep dive

Payment Schedule.

The milestone-level view of how we invoice a project.

Every project should have a payment schedule — a list of milestones with fees. This drives how much we invoice at each stage, what work the PM is tracking, and where money lands when the client pays.

The columns

Rollup strip above the table: Schedule total % · Received · Pending · % Billed. At a glance: how much of the schedule is laid out, how much money has actually arrived, what's still outstanding.

Adding a milestone

1. Click "Add item" in the top right.
2. Pick a contract from the dropdown. A helper banner appears: Contract X · Value ₹50L · Allocated ₹15L · Remaining ₹35L.
3. Type the milestone name like "Concept Design".
4. Type either % or Fee — the other fills in automatically based on the contract value.
5. Click ✓ to save, or ✕ to cancel.

Guardrails

You cannot enter a fee bigger than the Remaining value. The fee cell turns red and the save button disables. The backend also double-checks this on every request — so there's no way to over-allocate a contract even if someone tries to bypass the form.

Deleting a milestone

Hover over a row. A small ✕ appears on the right. Click it, confirm, done.

Exception: you cannot delete a milestone that has already received money. First the receipt needs to be voided (handled by the Receivables module — currently a rough edge).

Recording a receipt

Click Record receipt next to "Add item". A dialog opens.

Click Apply. The amount waterfalls from the top:

Why waterfall? Payment schedules are typically ordered by completion (Concept → Schematic → DDs → CDs). Money usually arrives in that order. Filling top-down matches reality.

09 — Module deep dive

Status Updates.

The PM's home page. Progress tracking only — zero financial data.

Status Updates is a dedicated page for Project Managers who need to update project progress but shouldn't be seeing money, payout config, or contract values.

What you see

A list of projects you can update:

A search box at the top for quick filtering, and a status filter (default: Active only).

Updating progress

Click Update on any row. A dialog asks for:

• The new progress % (0-100)
• Notes — optional, free text ("Schematic phase, client review next Tuesday")

Click Save. Done. The update writes to the audit log.

Three doors land here

New in May 2026. Updating completion is the same job no matter where you came from — so the tracker accepts you from three other pages with a "Back to..." link at the top:

• From Project → Payment Schedule tab: click any milestone's Completion % cell.
• From Meetings: in a session, expand a project block and click Update progress.
• From Projections: click any row's % Complete cell.

All three land at /status-updates?project=<id> — the project's card is auto-expanded and scrolled into view, the status filter defaults to "All statuses" (so on-hold / pitch / lead projects still show up), and the top of the page has a back-link to where you came from.

09a — Module deep dive

Projections.

"What's coming in" — a billing-prioritization view, not a sales pipeline.

Projections at /projections answers one question: what raises are coming, when, with what confidence, and how does that map to outstanding pending billing? A project shows up here when an associate has captured a "we can raise X targeting month Y" entry — either in a meeting or directly from this page (the "+ Add raise" button).

Cards above the table

Three KPI cards summarize the active filter window (default: next 6 months):

• Weighted Pipeline — confidence-adjusted total (Confirmed × 100% + Likely × 70% + Uncertain × 30%).
• Confirmed — raises tagged Confirmed.
• Likely — raises tagged Likely.

A "Scope" line under the header tells you the active month range and confirms the cards are the sum of the table below.

Filters

The Project-wise Raises table

Sorted by target month ASC → confidence DESC (Confirmed first) → weighted amount DESC. Most actionable raises at the top.

Click a row → milestone breakdown

Each row is clickable (except the interactive cells). Expansion shows a sub-table per project with all milestones: # / Milestone / % / Fee / Compl% / Received / Pending, plus a Totals row. This is the "how much is left to bill" view at granular detail.

"+ Add raise" inline

Top-right of the page. Captures a raise without going through a meeting: pick project, raise amount, target month, confidence. Saves to a synthetic "Projections — direct entries" meeting so the rest of the system reads it the same as a meeting-captured raise.

If the project already has a raise on file (in any month), the dialog surfaces a warning with the existing row. Clicking Overwrite existing raise updates that row in place (audited as meeting.note.inline_raise_overwrite) rather than creating a second one.

Confidence weights

10 — Module deep dive

Payout.

Who on TPA gets a cut of a project's receipts, at what rate, for which date range. Lives on the project detail page under the Payout tab.

Payout is the per-project compensation config. It answers a deceptively simple question: when a receipt of ₹X lands on this project, who gets paid and how much?. The old "one number per project" approach didn't survive contact with reality — partners negotiate custom rates, rates change mid-project after appraisals, specific receipts get carved out for specific people. So the module is built around three concepts that stack cleanly.

The three concepts

The four categories (set on the Employee master)

Each employee has exactly one payout_category (or blank). The category determines how the Ledger treats their receipts.

Working with the Payout tab

Adding an assignment

Click Add person. Pick the employee. The dialog reads their category from the employee master and shows only the fields that apply:

• PNL — just the employee. No rate field.
• MGP — employee + rate. If your rate ≠ their default commission %, a remark field becomes required.
• Variable — employee + rate. No comparison, no forced reason.
• Normal — employee only. Rate comes from contract roles at ledger time.

Save. The assignment appears with its first rate period starting on your effective from date and no end date (open).

Changing a rate (appraisal, promotion, negotiated bump)

Click the [+] icon next to an existing rate period. The Add period dialog asks for the new rate, the new effective_from, and a reason. Saving auto-closes the prior open period one day before your new start date, then inserts the new period as the currently-open one. Historical rates are preserved — old receipts never silently re-rate.

Editing a period in place

Click the pencil icon on the period row — a fat-finger typo in the rate, or a wrong effective-from date. This edits the period without creating a new one. The audit log captures the before/after. Cannot delete the only remaining period on an assignment (delete the assignment instead).

Excluding a receipt

Find the receipt in the Ledger view (below the assignment list). Click the small ✕ on the row. A dialog asks for the exclusion reason — it's non-optional. Save. The receipt now shows excluded: true, applied_pct: null, due: 0 with the reason visible in the cell.

The Ledger view (inside the Payout tab)

Below the assignment list, the Ledger shows what each person would earn on every receipt. A few rules to read it correctly:

Draft review & publish (admin-only)

Payout assignments can be drafted by anyone with payout.create but remain in a draft state until reviewed. Reviewing and publishing drafts requires admin or super_admin role — not just a permission. This is wired as an RBAC-adjacent guard: if your role isn't admin or super_admin, you can create and edit drafts but cannot move them live.

11 — Module deep dive

Commission Ledger.

The append-only record of every rupee of commission the firm has ever recognised. The abuse-killer.

Commission Ledger is the money-fact layer. The Payout module says "what should happen" — this module is "what actually got posted". Every row comes from a receipt landing on a project deliverable, with a fully-logged chain: source receipt → contract → applied rate → rate source → entry. There is no way to edit a row. Corrections are new offsetting rows that reference the original via reverses_entry_id.

The list view — /commission/ledger

Every entry, with filters by employee, period, project, receipt. Columns: Entry # · Employee · Project · Contract · Receipt date · Receipt ₹ · Applied % · Due ₹ · Status (active / reversed / reversing).

The drill-down — /commission/ledger/employees/{id} (the abuse killer)

The single most important screen in the platform. For one employee, every credit they've ever received, with:

• Source receipt — which payment came in when, from which client.
• Contract — which contract the receipt landed on.
• Applied rate — the exact percentage used.
• Policy explainer JSON — a small modal showing the full reasoning: source (manual_role_rate = came from contract_roles.rate_pct, or employee_default = fell back to employees.default_commission_pct), the contract_role row that was read (if any), and the resolved final rate.

If someone disputes their commission, this screen is the answer. Open it, show them the chain, close the conversation.

How entries get created

There is no manual-create form. Ledger entries are produced by the receipt-mapping flow:

1. A receipt comes in, gets mapped to a project deliverable via Receivables.
2. For each commission role on the underlying contract (AP, PA, Finder, Converter), the ledger service resolves a rate using the precedence rule below.
3. One ledger entry per role-holder is inserted in the same DB transaction as the receipt map. The audit row goes in the same transaction too. Atomic, or nothing.

Rate source precedence

1. contract_roles.rate_pct — per-contract override on a role. Percentage scalar (15.0 = 15%). Source label: manual_role_rate.
2. employees.default_commission_pct — the employee's house rate. Fraction (0.1500 = 15%); the ledger multiplies by 100 internally. Source label: employee_default.

No policy table, no lookup — just these two sources. The precedence is deliberate: per-contract overrides win, falling back to the employee default. Every entry records which source it used.

Closing a period

Go to Commission Ledger → Close period. Pick the period (month, quarter). The close action is approval-gated — requires the commission.ledger.close_period permission and is one of the 7 approval target types. Once approved, entries within the period are locked: they still appear in the drill-down forever, but no new entries can be inserted into a closed period.

Corrections (new offsetting rows)

If a historical entry is wrong, use Correct entry. The platform proposes an approval request of type ledger_correction with the offsetting payload. On approval, two new rows go in: the reversing row (negative ₹, reverses_entry_id set), and the corrected row. The original entry is untouched. The drill-down shows all three, with the chain visible.

12 — Module deep dive

Receivables.

The list of every receipt from a client, with its mapping to the project deliverable it covered.

Go to Receivables. Every payment that came in — across every project, every contract — in one list. Filters for date range, client, project, and mapping status (mapped / unmapped / partially mapped).

Columns

Recording a receipt

Two entry points:

• From the project detail — Payment Schedule tab → Record receipt. The contract is auto-scoped to the project; the waterfall applies across the project's deliverables.
• From Receivables itself — New receipt. Lets you record a receipt that hasn't been mapped yet (e.g. an advance before the project is created). The Map button on the row becomes your next step.

Auto-suggest mapping

When you map an unmapped receipt, the platform suggests which project it most likely belongs to based on: payer name match, amount match to an expected deliverable, and recent activity on the project. Accept the suggestion with one click, or pick a different project manually.

Voiding a receipt

If a receipt was entered wrong or the underlying payment bounced, use Void. This is approval-gated — type receipt_void, requires the receipt.update permission plus an approval flow. On approval, the receipt flips to Voided, its mapped amounts are rolled back from every deliverable it hit, and any commission ledger entries it produced are auto-reversed. Nothing is deleted; everything stays visible with the void stamp.

Remapping a receipt

If a receipt was mapped to the wrong project, use Remap. Also approval-gated (receipt_remap). The flow rolls back the old mapping and applies the new one atomically. Commission ledger follows along.

13 — Module deep dive

Approvals.

The pending queue — things proposed that need someone else's sign-off before they go live.

Some actions on the platform are too consequential for one person to do unilaterally. These go through an approval flow: someone proposes, one or more approvers decide, and only on approval does the actual write happen. The proposer cannot approve their own request.

The seven target types

Approval semantics

• Any — one approval is enough. Used for most mutations.
• All — every required approver must sign off independently. Used for commission policy, ledger corrections, period close. Rejection by any one kills the request.

The list view — /approvals

Everything pending, split into two tabs:

• For me — requests waiting on your decision.
• By me — requests you proposed that are still pending (or were rejected).

Click any row for the detail view.

The decide dialog

Opens when you click Act on a row. Shows:

• The proposer, the request time, and the target type.
• The payload — the exact change that will be applied if approved (JSON-formatted for full transparency).
• Other approvers on this request (if "all" semantics) and who has already decided.
• Approve / Reject buttons. Rejecting requires a reason.

What happens on approval

When the threshold is met (any or all), the platform looks up the registered applier for the target type. The applier replays the payload through the originating service, which writes the real row and its own audit row in the same DB transaction. If the applier fails (e.g. a uniqueness violation because something changed between propose and approve), the approval stays pending and the error surfaces — nothing partial gets written.

14 — Module deep dive

Meetings.

Review meetings, agendas, and action items with owners.

Meetings is where the firm tracks the working rhythms it used to run out of WhatsApp and spreadsheets. Weekly PM reviews, monthly finance reviews, project check-ins. Each meeting has an agenda, notes, and action items; each action item has an owner and a due date.

The list view

Every meeting, filterable by date range, type, and attendee. Each row shows date, title, attendees, and open action item count.

Creating a meeting

Click New meeting. The form asks for:

• Title, date, type (review / check-in / standup / ad-hoc)
• Attendees — pick from the employee master (multi-select)
• Linked project (optional) — if the meeting is about one specific project, link it so it shows up in that project's context

Inside a meeting

Two main tabs:

Notes

Free-form markdown area. Write discussion notes, decisions, context. Everyone who was an attendee can edit.

Action items

A list of concrete TODOs generated from the meeting. Each has:

Action items roll up to the owner's dashboard: every person sees their open items across every meeting in one place.

15 — Module deep dive

Employees.

The canonical employee master. One row per person. Everything about a person lives here.

Go to Employees. The list view is a searchable, filterable table — filter by home offering, payout category, active / terminated, and whether they have platform access.

Employee detail page

Clicking a row opens the detail page with several tabs:

Profile

The fields from the master table (see One-time setup). All editable inline, audit-logged, with save-in-card.

Roles on contracts

Every commission role this person currently holds or has held — AP, PA, Finder, Converter, per contract, with dates and rate. Read-only here; the canonical source is the contract's Roles tab.

Payout assignments

Every per-project payout assignment this person has, grouped by project, with the current rate period. Click through to the project's Payout tab.

Commission history

Direct link to the Commission Ledger drill-down — the abuse-killer view for this employee.

Platform access

See the Admin section for the provisioning flow. From the employee detail page, the Platform Access card shows the current state (enabled / not enabled), the provisioned email, the assigned role, and buttons to revoke or change role.

Commission roles & the cross-offering rule

The home offering field is load-bearing. When you try to add someone as AP or PA on a contract whose offering doesn't match their home offering, the platform rejects it with a clean error: "Carl (home: Architecture) cannot hold Principal Associate on an Interior contract." Finder and Converter roles are not constrained — anyone can bring in a lead or close one. Honorary employees cannot hold any commission role regardless.

16 — Module deep dive

Admin.

RBAC, platform access, integrations, email. The settings area for super admins and whoever holds rbac.write.

Go to Admin. Five sub-areas:

RBAC — roles & permissions

TPA Ops ships with a permission model of 52 permissions across 13 modules, following the module.action convention (e.g. project.create, receipt.update, employee.delete, commission.ledger.close_period).

Roles list (left sidebar)

System roles (super_admin, admin, finance, pm, associate, viewer, etc.) plus any custom roles you've added. System roles can't be deleted, but their permissions can be edited.

Permission matrix (detail pane)

Checkbox grid — 13 module groups × create/read/update/delete + specials (contract.amend, receipt.map, commission.ledger.close_period, approval.act, export.create). A module-level toggle at the top of each group checks/unchecks everything in that module in one click. Changes auto-save after a 600ms debounce — no Save button.

Assigned users (below the matrix)

Everyone who currently has this role, with the grant-date and who-granted-it. Remove or reassign inline.

Platform access provisioning

User accounts are admin-provisioned, not self-registered. The flow:

1. Make sure the employee is in the Employee master with an email on the row.
2. Go to Employees → open the person → Platform Access card → Enable access.
3. Pick their role (usually from the role list you've built on the RBAC tab).
4. Click Provision. The platform calls Supabase's Admin API, creates an auth user with a temp password, creates the local users row, links it to the employee via employee.user_id, and assigns the role.
5. The temp password is shown once — copy it, send it securely, gone.

Revoking access

Same card → Revoke. This bans the Supabase auth user (100-year ban, reversible), deactivates the local user row, and unlinks the employee's user_id. The employee row itself stays — only platform login is gone.

Resetting a password (admin-driven)

If a user can't access their email or is locked out, an admin can reset their password from the same Platform Access card → Reset Password button. Two prompts: optionally type a custom temp password (leave blank for the default TpaOps@<e_code>), then confirm. The new temp password shows in a 15-second toast — copy it and send via secure channel. The change is audit-logged with action employee.reset_password.

For routine forgot-password cases (user has email access), prefer the user-driven Forgot link on the login page — no admin involvement needed, and the user picks their own value.

Changing someone's role

From the Platform Access card, pick a different role. Effective immediately; their next request hits the new permission set.

Dashboard Access — assigning the dashboard tier

Each platform user has a dashboard tier that controls which dashboard they land on after login. There are 7 tiers: partner, admin, pnl, mgp, finance, hr, finance_hr, plus none (generic landing). Each renders a tier-specific dashboard component.

Admin → Dashboard Access lists every platform user with their current tier. Pick a tier from the dropdown to change it; auto-saves. Tier assignment is fully admin-managed — never auto-derived from role or permissions.

One carve-out: super_admin users with tier set to none are auto-promoted to the admin dashboard at read-time. So you don't have to set a tier explicitly for super_admins — they'll see the operational command centre by default.

Tier preview (super_admin only)

Add ?preview=<tier> to any URL when logged in as super_admin to render the dashboard as if you're in that tier — without changing the DB. Useful for inspecting all 7 tier views without re-provisioning users. Examples: /?preview=partner, /?preview=mgp, /?preview=finance.

Integrations

Configuration for external systems the platform talks to. At launch, this mostly means the email sender (SMTP credentials for the outbound email queue) and any future webhook endpoints. Credentials are stored encrypted.

Email configuration

The outbound email queue uses ARQ (async job queue). Admin → Email lets you:

• Pick the active sender: stub (logs only, dev use), resend (production — API-key based), outlook (production — OAuth-based).
• Send a test email to verify the configuration before flipping the sender live.
• See the recent send log — last 50 emails with status, timestamp, and any failure reason.

Dropdown Master

Same page as Dropdown Master — lives under Admin on the sidebar but has its own dedicated page for frequent use.

17 — Module deep dive

Dropdown Master.

Where the lists that drive everything on the platform live.

The short version: this is where status labels, city names, project types, lead sources, and project statuses live. Everyone on the platform uses these lists.

Add a new status or city once, and it appears in every dropdown, every filter, every detail page, every report automatically. No code change. No developer needed.

See One-time setup for the fuller story on each category.

18 — Deeper patterns

The 3 shapes of a deal.

TPA's deals aren't always a simple one-contract-one-project arrangement. The platform supports three shapes — one simple, one common, one that confused everyone in the old Excel world.

Every Project Value state — the 20-scenario reference

Every combination of Project Value + contracts + receipts you can hit, and what the platform will show you.

The three shapes above cover structure (how contracts and projects relate). The table below covers state — what happens at every combination of "Project Value typed or not", "contracts linked or not", "money received or not". Use it as a lookup: find the row that matches the project in front of you, read across to see what the platform should be showing.

Scenario detail — one block per row.

Plain English walkthrough of each scenario from the matrix above. If the behaviour you see doesn't match the On screen line, take a screenshot — it's a bug.

19 — When things happen

Common situations.

Real scenarios from day-to-day work, with step-by-step answers.

"The client walked away."

Go to the contract → click Terminate → give a reason. The contract flips to terminated, all project links cascade. Nothing is deleted — everything stays visible with a terminated badge for the audit trail.

"The client wants more work — add it to the contract."

Go to the contract → Amendments tab → pick the type:

• More money, same scope → Value Revised
• Added scope in an existing service → Scope Added
• A whole new service was added (was Arch-only, now also Interior) → Service Added
• Dropping a service → Service Removed (this cascade-terminates affected project links)

Every amendment writes to the change log with before/after snapshots.

"I started a project before the contract was signed."

Totally fine. Create the project anyway. In the Contract expected by field, set your reminder date. The project will have an empty Financials card with that reminder shown. When the contract comes in later, create it and link them.

"A project isn't going anywhere — put it on ice."

Change its Status to On Hold on the project detail page. Bring it back to Active later when things resume.

"The payment schedule got set up wrong."

If the milestone has no money received: hover, click the ✕, confirm. Gone. Add it again correctly.

If it already has money received: void the receipt first (coming in the Receivables module), then delete the milestone.

"We invoiced for something and got paid."

Temporary flow: Project → Payment Schedule tab → Record receipt → enter amount → applies top-down.

Future flow: When Receivables ships, this moves to a proper receipt entry module with receipt numbers, dates, instruments, and payer names.

"A new status is needed — e.g. 'Awaiting Client Signoff'."

Go to Masters → contract_status → add the label. It appears in every filter and dropdown immediately. No developer needed.

"Who changed this number?"

Project detail → Audit tab. Every change is there with who, when, and before/after.

"I can't see a module in my sidebar."

Your role doesn't have the {module}.read permission. Talk to your super admin, or check Admin → RBAC if you have the rights yourself.

20 — Quick answers

Frequently asked questions.

21 — Reference

Glossary.

The words TPA Ops uses, in plain English.

Contract

The legal document signed with a client. Has an ID, a value, services, and dates.

Project

A single unit of work. One service = one project. Can be funded by one or more contracts.

Service / Offering

Architecture, Interior, or Municipal. A contract can bundle multiple; a project is always exactly one.

N:M (many-to-many)

The fact that one contract can fund many projects, and one project can be funded by many contracts. The platform was built for this from day one.

Link / Allocation

The connection between a contract and a project. Each link has an allocated ₹ value.

Payment Schedule

The ordered list of milestones we bill against, per project per contract.

Milestone / Deliverable

An entry in the payment schedule. Has a name, a fee, a % of the contract, a work status, and a received amount.

Receipt

Money coming in from a client.

Waterfall

The algorithm that fills a payment schedule from the top when a receipt is applied.

Payout category

One of pnl, mgp, variable, normal, or blank. Set on the employee master, drives how Payout and Commission Ledger treat that person.

PNL (payout category)

Partner profit share — flag-only, no per-receipt rate. Used for partners who take a cut of project profit at settlement time.

MGP

Minimum Guarantee Payout — an employee category where the per-project rate is compared against the employee's default commission %. Any deviation is recorded as an override with a required reason.

Variable (payout category)

Ad-hoc bonus employees. Per-project rate is typed manually, with no house-rate comparison.

Rate period

A date-effective rate inside a payout assignment. "15% from 1 Jan to 28 Feb; 17% from 1 Mar onwards." Historical rates are preserved so old receipts never silently re-rate.

Receipt exclusion

A specific receipt removed from a specific payout assignment, with a required reason. Shows up on the Ledger view with the reason visible.

Commission role

A named role on a contract — AP (Associate Principal), PA (Principal Associate), Finder, Converter — each with an optional rate override.

Home offering

An employee's primary service (ARCH / INT / MUNI). Constrains which contracts they can hold an AP/PA commission role on.

Append-only

A table where UPDATE and DELETE are blocked at the database level. Corrections are new offsetting rows, not edits. audit_log and commission_ledger_entries are append-only.

Platform access

The ability to sign in. Provisioned by super admin from the Employees module — creates a Supabase Auth user, links it to the employee row, assigns a role. Employees exist on the master independently of whether they can log in.

RBAC

Role-Based Access Control. 52 permissions across 13 modules. Each role has a set of permissions; each user has one or more roles. super_admin bypasses all checks.

Terminate

End something prematurely with a reason. Non-destructive — keeps the audit trail.

Dropdown Master

The central lists that drive every dropdown on the platform. Add once, use everywhere.

Audit trail

The complete log of who changed what, when, and why. Baked into every table on the platform.

Approval

A gated action that needs sign-off from one or more approvers.

Hero case (Scenario C)

Nickname for the "2 contracts, 1 project" pattern — the one that broke Excel forever.

Staging

A copy of the live site at staging-ops.64-227-180-82.nip.io where new code gets tested before going to the real site. Separate database, separate everything — touching staging cannot touch production.

Heartbeat

An automatic check that runs every 5 minutes from GitHub's servers (not from our server) to verify the live site is up. Emails the repo owner and opens a GitHub issue on failure.

Parked decision

A design question we've deliberately left open because answering it wrongly is more expensive than waiting. Documented so nobody is surprised and nobody "fixes" them silently.

22 — Behind the scenes

Life of a change.

How code and data moves from a laptop, through staging, and into the live site — with the checks and safety nets at each step.

This section is for anyone curious, and for whoever takes the platform over in future. The deployment machinery isn't something users touch directly — but understanding it makes the platform feel less like a black box, and makes incident response faster when something breaks.

The mental model: four stacked copies

Think of four stacked copies of the system. Each copy is identical in shape, different in purpose.

A change starts in #1 and ends in #4. Each step has a purpose, a check, and a safety net.

The flow at a glance

     ┌─────────┐      ┌─────────┐      ┌─────────────┐      ┌─────────────┐
     │ 1 LOCAL │ ───▶ │ 2  CI   │ ───▶ │ 3  STAGING  │ ───▶ │ 4   PROD    │
     │ laptop  │      │ GH Acts │      │ droplet     │      │ droplet     │
     └─────────┘      └─────────┘      └─────────────┘      └─────────────┘
          │                │                   │                    │
     (write code)    (run the tests)    (click the feature)   (real money lives here)
          │                │                   │                    │
          ▼                ▼                   ▼                    ▼
     one laptop      5 parallel jobs     public URL on nip.io   public URL (nip.io today,
     Postgres in     must ALL pass       zero-downtime deploy   tparch.net after DNS)
     Docker          before merge        on every push to
                                         `staging` branch       deploys only from `main`

Stage-by-stage

main (live, production)
  │
  ├─ staging (mirror of what's queued for prod)
  │
  └─ sprint/28-my-feature  ← work happens here

                   ┌──────────────────────────┐
                   │  Push to GitHub triggers │
                   └────────────┬─────────────┘
                                │
        ┌───────────────┬───────┴────────┬──────────────┬─────────────┐
        ▼               ▼                ▼              ▼             ▼
   ┌─────────┐    ┌────────────┐   ┌────────────┐  ┌──────────┐  ┌──────┐
   │ api     │    │ web-build  │   │ playwright │  │ docker-  │  │ done │
   │ tests   │    │ typecheck  │   │ smoke E2E  │  │ builds   │  │ (ok) │
   └─────────┘    └────────────┘   └────────────┘  └──────────┘  └──────┘
   ruff+mypy+     TypeScript        5 browser      docker build   aggregator —
   102 pytests    compiles,         test flows     both api +     passes only
   w/ Postgres    Next.js builds    (login,        web Docker     if all 4 above
   + Redis        without errors   protected       images         passed
                                   routes,
                                   etc.)

staging branch push
        │
        ▼
Build Docker images, tag with commit SHA
        │
        ▼
Push images to GitHub Container Registry (ghcr.io)
        │
        ▼
SSH into droplet (64.227.180.82)
        │
        ▼
docker compose -f docker-compose.staging.yml pull
docker compose -f docker-compose.staging.yml up -d
        │
        ▼
Run Alembic migrations against the staging Supabase project
        │
        ▼
Health check: curl staging-api.64-227-180-82.nip.io/health

main branch push
        │
        ▼
Build Docker images, tag with commit SHA (e.g. sha-aaa2e8b)
        │
        ▼
Push to ghcr.io
        │
        ▼
  ┌─ APPROVAL GATE ─┐
  │ GitHub Env:     │ ← requires a human to click "Approve and deploy"
  │  production     │   in the GitHub UI before the rest of the job runs
  └────────┬────────┘
           ▼
SSH into droplet
        │
        ▼
docker compose -f docker-compose.production.yml pull
docker compose -f docker-compose.production.yml up -d
        │
        ▼
Run Alembic migrations against the prod Supabase project
        │
        ▼
Health check: curl api.ops.64-227-180-82.nip.io/health → expect env=prod

Where does each thing live?

If something breaks

1. Heartbeat opens a GitHub issue labelled heartbeat. Go read the latest comment — it has the workflow run link.
2. Check /health manually: curl https://api.ops.64-227-180-82.nip.io/health. Wrong env or a fail = API or DB down.
3. Check Sentry (wired via Admin → Integrations) for any recent exceptions.
4. Roll back: SSH to droplet → docker compose pull tpa-ops-api:sha-<previous_good> → up -d api. See docs/rollback.md.
5. If the database is wrong: staging data is disposable; production has a nightly pg_dump on the droplet. Restore procedure in docs/runbook.md.

23 — Behind the scenes

Parked architectural decisions.

Some design questions have been deliberately left open. They're not bugs — they're known forks in the road we chose not to walk down yet, because walking down them wrongly is more expensive than waiting.

Writing them down explicitly so that (a) nobody is surprised, (b) nobody "fixes" them silently, (c) whoever picks them up later knows what the two sides of the question look like.

24 — Behind the scenes

Uptime monitoring.

How we know the site is up — and how we find out the moment it isn't.

A GitHub Actions workflow called heartbeat runs every 5 minutes. It's deliberately not running on the droplet — if the droplet dies, a droplet-based checker would die with it and the outage would go silent. So it runs on GitHub's runners.

What it checks

The workflow pings 4 URLs in parallel:

When something fails

• GitHub emails the repo owner (Abhas) automatically — no extra wiring.
• A second job opens (or appends to) a rolling GitHub issue labelled heartbeat. One issue per outage cluster, so the inbox doesn't flood with dupes.

On-demand trigger

To test the workflow without waiting 5 minutes:

gh workflow run heartbeat.yml

Or from the GitHub UI: Actions → Heartbeat → "Run workflow".

Known limit — schedule drift

GitHub's scheduled workflows are best-effort and can lag 5–15 minutes under load. That's fine for uptime awareness at TPA scale. If the platform ever needs sub-minute detection (it doesn't, today), layer UptimeRobot or BetterUptime on top — the heartbeat workflow doesn't need to be removed.

False alarms

If heartbeat opens an issue but the site is actually fine, it's probably a GitHub Actions scheduling hiccup or a 15-second transient. Close the issue. If it recurs within 30 minutes, treat as real and start the incident steps in docs/runbook.md.