Vantage Platform — Business Logic Diagrams

For AWS migration validation. Derived from codebase analysis and stakeholder discovery sessions. Lambda architecture: one Lambda function per API endpoint path for independent scaling. 14 roles across 4 portals. Last updated: reviewer feedback applied June 2026.

Diagram 1 — User Hierarchy & Role Creation Tree

[Diagram]

Sub Proxy vs Sub Admin: Sub Proxy is an internal CW/OIP employee granted temporary access to the sub portal (using OIP credentials) to act on behalf of subs that haven't adopted the platform. Sub Admin is an external sub company employee — the sub company's own portal administrator, created by TA or TM when the sub adopts. Sub Admin has all Sub Writer capabilities plus manages their own company's Sub Writer/Reader accounts.

Role DO / DON'T — Corporate Portal

Role ✅ CAN DO 🚫 CANNOT DO
Super Admin Everything in all portals. Provision any user type. Force-logout any user. Run DB migrations. Manage platform config, backups, schema. Delete territories. Nothing blocked.
Corporate Writer Create territories. Create national accounts (CORP-level). Create Territory Admins. Read + write across all territories via territory switcher. Establish national contracts. Configure NBD rules alongside NAM. Create NBD client profiles and grant client portal access. Upload documents to national accounts. Create and manage invoices for NBD accounts. Create inspection templates and requests for NBD accounts. Create NAM users (IT only). Manage sub portal or client portal sub-side directly. Create or modify franchise staff (TM, TW, TR). Delete territories.
NAM Read + write on assigned national accounts + all their division locations, across any territory. Configure NBD pricing rules (unbreakable). Grant territory visibility to CORP accounts. Distribute Quote Requests to territories (auto-routed by location territory_id). Send approved quotes to NBD clients. Approve/reject territory quotes before they reach clients. Approve NBD invoices before they are sent to clients. Issue Work Orders from approved quotes. Cancel NBD work orders ⚠️Mitch. Manage national approvals queue. Set recurring schedules for national accounts. Create + score inspections for NBD accounts. Upload documents to national accounts. Message NBD clients directly. View + forward NBD client service requests to territories. Convert NBD service requests to quote requests or direct work orders. Touch unassigned national accounts. Create territories. Create, edit, or delete franchise users (TA, TM, TW, TR). Manage local (non-CORP) accounts. Override NBD rules without approval.
NAM Reader Read everything NAM can see across all assigned national accounts and their division locations. Write anything. Edit contact information at division locations ⚠️Pending Mitch confirmation.

Role DO / DON'T — Territory Portal (OIP)

Role ✅ CAN DO 🚫 CANNOT DO
Territory Admin Full module access. Access Settings. Create + manage Territory Managers, Writers, Readers. Create sub company profiles + grant sub portal access. Create Sub Admin (external) accounts. Create client profiles + grant client portal access. Grant Sub Proxy cross-portal permission. Switch between all assigned territories. Manage work orders, quotes, bids, inspections, service requests, tasks, documents, messages. View + edit local division locations under own territory accounts. View division location work orders in their territory. Run inspections. View NBD pricing rules for their territory's national accounts ⚠️Mitch. See CORP-level national accounts directly. Edit NBD (CORP-owned) division location details. Override NBD pricing rules. See data from territories not assigned to them.
Territory Manager Create sub company profiles + grant sub portal access. Create Sub Admin (external) accounts. Create client profiles + grant client portal access. Revoke Sub Proxy grants ⚠️Mitch. Full module access (work orders, quotes, bids, inspections, service requests, tasks, documents, messages). Switch between all assigned territories. View NBD pricing rules for their territory's national accounts ⚠️Mitch. Create or manage CRM users (TA, TM, TW, TR). Access Settings. Modify platform config or financial settings.
Territory Writer Full module access (work orders, quotes, bids, inspections, service requests, tasks, documents, messages). Create sub company profiles + grant sub portal access. Switch between all assigned territories. View NBD pricing rules for their territory's national accounts ⚠️Mitch. Manage any users. Access Settings. Grant client portal access. Create Sub Admin accounts.
Territory Reader Read all modules in assigned territory. Switch between all assigned territories. Write anything.
Sub Proxy Log into sub portal using OIP credentials. Perform tasks on behalf of unadopted subs in granted territories: mark jobs complete, submit bids, update work order status, manage documents, send messages to territory. Create sub portal user accounts (that is Sub Admin's job). Act on subs in territories not explicitly granted. Access CRM modules beyond their normal OIP role. Assign subcontractors to work orders. Create new work orders.

Role DO / DON'T — Sub Portal

Role ✅ CAN DO 🚫 CANNOT DO
Sub Admin Everything Sub Writer can do. Create and manage Sub Writer and Sub Reader accounts within their own company. Deactivate or update company portal users. View full sub company data. See other sub companies. See CRM internal data (margins, costs, client details). Manage users outside their own company.
Sub Writer View all sub company data. Submit and manage bids. Update payment info. Mark jobs complete. Manage sub company documents. Send/receive messages with territory. View inspection scores for their own jobs. View their own vendor bills. See other sub companies. See CRM internal data (margins, costs, client details). Create Sub Reader accounts (Sub Admin handles that).
Sub Reader View all sub company data (full company view, read-only). View own inspection scores. Write anything. Mark jobs complete. Submit bids. Manage payment info.

Role DO / DON'T — Client Portal

Role ✅ CAN DO 🚫 CANNOT DO
Client Writer File service requests. Accept or decline quotes (e-signature). View their own work orders and status. View work orders being completed at their site. View their own invoices. Download client-visible documents. Send/receive messages with territory (local) or NAM (NBD accounts). Mark checklist items as complete. See other client accounts. See cost, margin, or financial internals. See vendor bills or sub information. Create checklist items.
Client Reader View own account data (work orders, quotes, invoices, service requests, documents). Write anything. File service requests. Accept or decline quotes.

Diagram 2 — Account Hierarchy & Visibility

[Diagram]

Visibility Per Role at Each Level

Data Node Super Admin Corp Writer NAM NAM Reader Territory Admin (GFC) Territory Writer/Reader (GFC) Sub Writer Client Writer
CORP territory row ✅ ✅ ✅ ✅ 🚫 🚫 🚫 🚫
National Account (FedEx Corp) ✅ ✅ ✅ assigned ✅ assigned 🚫 🚫 🚫 🚫
NBD Rules ✅ ✅ ✅ r/w ✅ read 📖 ⚠️Mitch 📖 ⚠️Mitch 🚫 🚫
NBD Division Location in GFC (FedEx 312) ✅ ✅ ✅ ✅ ✅ ✅ 🚫 🚫
NBD Division Locations in other territories ✅ ✅ ✅ ✅ 🚫 🚫 🚫 🚫
Local Account in GFC (Acme) ✅ ✅ 🚫 🚫 ✅ ✅ 🚫 🚫
Local Division Location in GFC (Eglin Branch) ✅ ✅ 🚫 🚫 ✅ ✅ 🚫 🚫
Work Orders at NBD division location (GFC) ✅ ✅ ✅ ✅ ✅ manage ✅ manage ✅ if assigned ✅ own site
Work Orders at local account (GFC) ✅ ✅ 🚫 🚫 ✅ ✅ ✅ if assigned ✅ own
Contacts / Client portal users ✅ ✅ 🚫 🚫 ✅ ✅ 🚫 Own only

What Territory Users CAN and CANNOT Do — by Account Type

Action NBD Division Location Local Account / Local Division
View the account ✅ ✅
Edit account details 🚫 ✅
Create and manage work orders ✅ ✅
Assign subcontractors to work orders ✅ ✅
Run inspections ✅ ✅
Submit bids in response to a Quote Request ✅ ✅
Create a quote and send to NAM for approval ✅ N/A
Create a quote and send to local client N/A ✅
Create a Bid Request to subs ✅ ✅
Edit the national account (parent) 🚫 N/A
Change NBD pricing rules 🚫 N/A
Quote above NBD margin floor 🚫 N/A
See national account locations in other territories 🚫 N/A
See cost/margin breakdown ✅ (NBD doesn't mark up) ✅
Create child division locations N/A ✅

Diagram 3 — Quote & Work Order Flows

Flow A: NBD / Corp-Initiated (National Account)

[Diagram]

Flow B: Territory-Initiated (Local Account)

[Diagram]

Flow C: Client-Initiated (Service Request)

[Diagram]

Status Machines

Quote statuses:

[Diagram]

Work Order statuses:

[Diagram]

Bid Request statuses:

[Diagram]

Service Request statuses:

[Diagram]

Diagram 4 — Permission & Capability Matrix

Legend: ✅ Full · 📖 Read-only · 🔒 Scoped (assigned/own data only) · ⚠️ Pending Mitch confirmation · 🚫 No access

Columns: SA = Super Admin · CW = Corporate Writer · NAM · NAMR = NAM Reader · TA = Territory Admin · TM = Territory Manager · TW = Territory Writer · TR = Territory Reader · SubP = Sub Proxy · SubA = Sub Admin · SW = Sub Writer · SR = Sub Reader · CLW = Client Writer · CLR = Client Reader

Action SA CW NAM NAMR TA TM TW TR SubP SubA SW SR CLW CLR
TERRITORY MANAGEMENT
Create territory ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Edit territory ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Delete territory ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View territories ✅ ✅ ✅ ✅ 🔒 own 🔒 own 🔒 own 🔒 own 🚫 🚫 🚫 🚫 🚫 🚫
Territory switcher ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫
Territory financial settings ✅ 📖 🚫 🚫 ✅ own 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
USER MANAGEMENT
Create Corporate users (CW, NAM, NAMR) ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create Territory Admin ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create Territory Manager / Writer / Reader ✅ 🚫 🚫 🚫 ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Grant Sub Proxy permission ✅ 🚫 🚫 🚫 ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Revoke Sub Proxy permission ✅ 🚫 🚫 🚫 ✅ ✅⚠️ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create Sub Admin (external) ✅ 🚫 🚫 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create sub profile + grant portal access ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create Sub Writer / Reader (own company) ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 ✅ 🚫 🚫 🚫 🚫
Sub Writer creates Sub Reader 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create client profile + grant portal access ✅ ✅ NBD 🚫 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Force-logout / revoke any session ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Change own password ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
ACCOUNT MANAGEMENT
Create national account (CORP) ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Edit national account ✅ ✅ 🔒 assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create NBD division location ✅ ✅ ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Edit NBD division location ✅ ✅ 🔒 assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Grant territory visibility to CORP account ✅ ✅ ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create local account ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Edit local account ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create local division location ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Edit local division location ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Soft-delete account ✅ 🚫 🚫 🚫 ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
NBD RULES
Configure NBD pricing rules ✅ ✅ 🔒 assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View NBD pricing rules ✅ ✅ 🔒 assigned 🔒 assigned 📖⚠️ 📖⚠️ 📖⚠️ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Override NBD margin floor ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
QUOTE REQUESTS (NBD)
Create + distribute Quote Request ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Receive + view Quote Request ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 🚫 🚫
Approve territory quote (national approvals queue) ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Reject territory quote ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
QUOTES
Create quote ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Send quote to local client ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Send approved quote to NBD client ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Accept quote (e-signature) 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ 🚫
Decline quote 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ 🚫
Convert accepted quote to Work Order ✅ 🚫 ✅ NBD only 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View quote (price) ✅ ✅ 🔒 assigned 🔒 assigned ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 ✅ own 📖 own
View quote (cost + margin) ✅ ✅ 🔒 assigned 🔒 assigned ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 🚫 🚫
BID REQUESTS
Create Bid Request (to subs) ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View Bid Request (sub) 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ ✅ ✅ 📖 🚫 🚫
Submit bid 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Award bid ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
WORK ORDERS
Create Work Order ✅ 🚫 ✅ NBD only 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Assign sub to Work Order ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Update Work Order status ✅ 🚫 📖 NBD only 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Mark Work Order complete ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Cancel Work Order ✅ 🚫 ✅⚠️ NBD 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Add checklist items ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Mark checklist items complete ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 ✅ own 🚫
Add work order comments ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 ✅ 🚫
Internal comms with territory (NBD WOs) ✅ 🚫 ✅ NBD 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Leave feedback on work order 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ 🚫
View Work Orders ✅ ✅ 🔒 NBD 🔒 NBD ✅ ✅ ✅ 📖 🔒 granted 🔒 own co. 🔒 own co. 🔒 own co. 🔒 own 🔒 own
SERVICE REQUESTS
File Service Request ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 ✅ 🚫
View NBD client service requests ✅ ✅ 🔒 assigned 🔒 assigned 🔒 territory 🔒 territory 🔒 territory 📖 🚫 🚫 🚫 🚫 🚫 🚫
Assign / forward SR to territory ✅ 🚫 ✅ NBD 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Convert NBD SR to Quote Request ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Resolve / close SR ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Convert SR to Work Order (direct) ✅ 🚫 ✅ NBD pre-negotiated 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View SR ✅ 🚫 🔒 assigned 🔒 assigned ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 ✅ own 📖 own
INSPECTIONS
Create Inspection / Inspection Template ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Score / perform inspection ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View inspection scores (full detail) ✅ ✅ 📖 📖 ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 🚫 🚫
View own inspection scores (sub) 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 📖 own 📖 own 📖 own 🚫 🚫
FINANCIAL — AR (Client Invoices)
Create Client Invoice ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Approve NBD invoice before sending to client ✅ 🔒 NBD 🔒 NBD⚠️ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Approve local invoice ✅ 🚫 🚫 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Mark Invoice paid ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Void Invoice ✅ 🔒 NBD 🔒 NBD 🚫 ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View Invoice ✅ ✅ 🔒 assigned 🔒 assigned ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 ✅ own 📖 own
FINANCIAL — AP (Vendor Bills)
Create Vendor Bill 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Approve Vendor Bill ✅ 🚫 🚫 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Dispute Vendor Bill ✅ 🚫 🚫 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Mark Vendor Bill paid ✅ 🚫 🚫 🚫 ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View Vendor Bill ✅ ✅ 🔒 assigned 🔒 assigned ✅ ✅ ✅ 📖 ✅ 🔒 own 🔒 own 📖 own 🚫 🚫
NATIONAL APPROVALS QUEUE
View approvals queue ✅ ✅ 🔒 assigned 🔒 assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Approve item in queue ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Reject item in queue ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
DOCUMENTS
Upload document ✅ 🔒 NBD 🔒 NBD 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Mark document client-visible ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Download document ✅ ✅ 🔒 🔒 ✅ ✅ ✅ 📖 ✅ ✅ ✅ 📖 🔒 visible 🔒 visible
MESSAGES
Send to subcontractor ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Send to local client ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Send to NBD client ✅ 🚫 ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Reply (sub → territory) 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
Reply (local client → territory) 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ local 🚫
Reply (NBD client → NAM) 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ NBD 🚫
Attach file to message ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 ✅ ✅ ✅ 🚫 🚫 🚫
SETTINGS & CONFIG
Platform config (terminology overrides) ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
UDC tables (service categories, payment terms) ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Access Settings tab ✅ ✅ 🚫 🚫 ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Run DB migrations ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View system health ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
TASKS
Create task ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Complete task ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
RECURRING SCHEDULES
Create recurring schedule (local) ✅ 🚫 🚫 🚫 ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 🚫
Create recurring schedule (national) ✅ ✅ ✅ assigned 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
View / edit recurring schedule ✅ 🚫 🔒 assigned 🚫 ✅ ✅ ✅ 📖 🚫 🚫 🚫 🚫 🚫 🚫

⚠️ = Pending Mitch Wayman confirmation before finalizing

Diagram 5 — Portal Data Boundaries

[Diagram]

Diagram 6 — Financial Flow (AR / AP)

[Diagram]

Diagram 7 — Recurring Schedule → Work Order Generation

[Diagram]

Diagram 8 — Sub Onboarding & Role Lifecycle

[Diagram]

Diagram 9 — Inspection Flow

[Diagram]

Diagram 10 — Account Health Score

[Diagram]

Key Architecture Notes

Lambda Deployment (one per endpoint path)

GET  /accounts              → lambda: accounts-list
POST /accounts              → lambda: accounts-create
GET  /accounts/{id}         → lambda: accounts-get
PUT  /accounts/{id}         → lambda: accounts-update

GET  /work-orders           → lambda: work-orders-list
POST /work-orders           → lambda: work-orders-create
GET  /work-orders/{id}      → lambda: work-orders-get
PUT  /work-orders/{id}      → lambda: work-orders-update

... (one Lambda per path for all ~150 endpoints)

Each Lambda:

  1. Receives Cognito JWT claims from API Gateway authorizer
  2. Calls set_user_context() in a transaction to set RLS context (SET LOCAL)
  3. Executes business logic via FastAPI route handler
  4. RLS enforces row-level tenant isolation automatically at query time

14-Role Summary

# Role Portal Identity
1 Super Admin Corporate Internal
2 Corporate Writer Corporate Internal
3 NAM Corporate Internal
4 NAM Reader Corporate Internal
5 Territory Admin Territory Internal
6 Territory Manager Territory Internal
7 Territory Writer Territory Internal
8 Territory Reader Territory Internal
9 Sub Proxy Sub portal (OIP login) Internal — acts for unadopted subs
10 Sub Admin Sub portal External — sub company's own user manager
11 Sub Writer Sub portal External
12 Sub Reader Sub portal External
13 Client Writer Client portal External
14 Client Reader Client portal External

Confirmed Architecture Decisions

Decision Answer
Email uniqueness across user types Globally unique — clients and subs cannot share emails
Multi-territory user assignments stored where DB only (territory_assignment table) — not in Cognito token
Real-time messaging Polling acceptable for now (30s sub, 60s client)
Lambda granularity One Lambda per API endpoint path (~150 total)
Cognito pools One pool, four groups, custom attributes for role + entity linkage
RLS approach SET LOCAL per transaction — safe with RDS Proxy connection pooling
Territory financial settings ownership Territory Admin owns + edits; Corporate can view only
NBD division location editing Territory users cannot edit; local division locations they can
Cost/margin visibility No hidden margins on NBD quotes (NBD does not mark up)
Sub Proxy vs Sub Admin Sub Proxy = internal OIP employee (bridging); Sub Admin = external sub company admin

Open Items Pending Mitch Wayman

Item Current decision Note
NAM Reader contact editing at division locations 🚫 Cannot edit Awaiting Mitch
NBD pricing rules visible to TA/TM/TW 📖 Read-only allowed Awaiting Mitch
NAM approves NBD invoice before client sees it ✅ Yes Awaiting Mitch
NAM can cancel NBD work orders ✅ Yes Awaiting Mitch
TM can revoke Sub Proxy grants ✅ Yes Awaiting Mitch