← NEXUS Platform
Investor & Partner Reference

NEXUS Platform
Process & Function Flow

Complete architecture map — from first user registration to final lien waiver release. Every route, service, and data model.

NEXUSPLATFORM
🏗️Owner
👷GC
🔧Sub
🛡️Admin
4
User Roles
28
API Routes
12
Core Services
14
Data Models
5
Flow Stages
100%
AI Verified Payments
Owner
General Contractor
Subcontractor
AI / Automation
Payment / Escrow
System / Shared
User Journey Tracks Click any track to expand • Click any step for details
🏗️

Track 1 — Owner Journey

▼
  • 1
    Register & KYC
    Create account with role=owner, email verification
    POST /register
  • 2
    Create Project
    Name, location, type, budget. Status → draft
    POST /projects/
  • 3
    Upload Blueprint
    PDF parsed by AI — extracts scope, milestones, cost estimate
    POST /projects/{id}/blueprint AI Vision
  • 4
    Open Bidding
    Project posted to marketplace. Status → bidding
    POST /projects/{id}/open-bidding
  • 5
    Review Bids
    View all bids with AI diligence scores, license checks, past performance
    GET /projects/{id}/bids AI Scored
  • 6
    Award GC
    Select winning bid. Contract auto-generated. Status → awarded
    POST /projects/{id}/award/{bid_id}
  • 7
    Fund Vault
    Stripe escrow funded with project total. Money locked until milestones verified
    Stripe Escrow POST /payments/fund-vault
  • 8
    Monitor Progress
    Real-time dashboard — milestones, verifications, chat, payments
  • 9
    Approve Invoices
    Invoice auto-generated on AI verification pass. Owner approves
    POST /payments/approve-invoice
  • ✓
    Release Final Payment
    Retainage released on final lien waiver. Project completed
    Stripe Transfer
👷

Track 2 — GC Journey

▼
  • 1
    Register & License Verify
    Role=gc, license number uploaded, AI verifies via state DB
    POST /register AI Check
  • 2
    Browse Marketplace
    Filter open projects by type, location, budget range
    GET /projects/
  • 3
    Submit Bid
    Bid amount, timeline, team. AI scores GC diligence before submission
    POST /projects/{id}/bids Diligence Score
  • 4
    Get Awarded
    Notification via email + WhatsApp. Contract presented
  • 5
    Sign Contract
    Digital signature. Milestones auto-created from blueprint AI parse
  • 6
    Assign Tasks to Subs
    Create tasks under milestones. Assign to registered subs
    POST /projects/{id}/milestones WhatsApp notify
  • 7
    Monitor Verifications
    Real-time AI verification feed. Override ambiguous results
    GET /verifications/project/{id}
  • 8
    Approve Verified Work
    GC confirms milestone complete. Triggers invoice generation
    POST /verifications/{id}/approve
  • 9
    Invoice Owner
    Auto-generated invoice sent. Owner notified
    Auto-Invoice
  • ✓
    Receive Payment
    Stripe transfer from escrow. GC splits to subs. Retainage held
    Stripe Transfer POST /payments/payout-sub
🔧

Track 3 — Sub Journey

▼
  • 1
    Register
    Role=sub, trade type, insurance upload, bank account
    POST /register
  • 2
    Get Assigned Task
    GC assigns task. SMS + WhatsApp notification with task details
    WhatsApp/SMS
  • 3
    Check In (GPS)
    GPS check-in logged. Location verified against project address
  • 4
    Do Work
    Complete assigned task per milestone specification
  • 5
    Submit Photo/Video
    Via WhatsApp bot OR app upload. Automatically routed to AI
    WhatsApp POST /verifications/submit
  • 6
    AI Verification
    GPT-4o Vision analyzes media against blueprint spec
    AI Vision
  • ?
    Three possible outcomes:
  • ✓
    PASS → Instant Payment
    Confidence ≥ threshold. Invoice auto-created. Stripe payout immediately
    Instant Payout
  • ✗
    FAIL → Resubmit
    AI returns failure reason. Sub notified via WhatsApp with instructions
    WhatsApp notify
  • ~
    AMBIGUOUS → Human Review
    GC or admin reviews. Manual override triggers payment
    POST /verifications/{id}/override
🤖

Track 4 — AI Verification Pipeline

▼
  • 1
    Media Received
    Photo/video arrives via WhatsApp webhook or app API
    Twilio Webhook POST /webhooks/twilio/inbound
  • 2
    GPS Check
    Verify submission location matches project address ± tolerance
  • 3
    OpenRouter GPT-4o Vision
    Media analyzed with blueprint context prompt. Returns structured JSON
    ai_vision.verify_work_submission()
  • 4
    Blueprint Comparison
    AI compares work against parsed blueprint specs for the milestone
    Spec-match algorithm
  • 5
    Confidence Score
    0.0–1.0 score. ≥0.85 = verified, 0.5–0.85 = ambiguous, <0.5 = failed
  • ✓
    If Verified → Auto-Invoice
    Invoice auto-generated, milestone status updated, payment queued
    Automated
  • $
    Auto-Payment + Lien Waiver
    Stripe releases funds. Lien waiver auto-generated and signed
    Stripe Transfer Auto Lien Waiver
💰

Track 5 — Payment Flow

▼
  • 1
    Owner Funds Stripe Vault
    100% of project contract value deposited into escrow
    create_project_vault()
  • 2
    Money Held in Escrow
    Funds locked in ProjectVault. No release without verification
  • 3
    AI Verification Passes
    Confidence threshold met. Verification status → verified
    Trigger
  • 4
    Invoice Auto-Generated
    Invoice created for milestone amount. Owner notified
    Automated
  • 5
    Owner Approves
    Owner clicks approve (or auto-approved after 48hrs silence)
    POST /payments/approve-invoice
  • 6
    Stripe Transfer to GC
    90% of milestone released from escrow to GC Stripe account
    release_payment_to_gc()
  • 7
    GC Splits to Subs
    GC pays sub invoices from their received payment
    release_payment_to_sub() POST /payments/payout-sub
  • 8
    Retainage (10%) Held
    10% withheld per milestone until project final completion
  • 9
    Final Lien Waiver
    All subs sign unconditional lien waivers. Auto-generated
    LienWaiver model
  • ✓
    Retainage Released
    Final 10% released. Project vault closed. Status → completed
    Final Transfer
AI Verification — Visual Pipeline
📱
Sub Submits Media
WhatsApp / App Upload
💬
Twilio Webhook
POST /webhooks/twilio/inbound
or
📡
App API Upload
POST /verifications/submit
📍
GPS Location Validation
Site presence confirmed
🧠
OpenRouter GPT-4o Vision
ai_vision.verify_work_submission() — structured JSON analysis
📐
Blueprint Comparison
Spec-matching against parsed PDF
📊
Confidence Score 0.0–1.0
Threshold routing
✅
VERIFIED
Score ≥ 0.85
→ Auto-Invoice
→ Stripe Payout
→ Lien Waiver
⚠️
AMBIGUOUS
Score 0.5–0.85
→ GC/Admin Review
→ Manual Override
→ Approve or Reject
❌
FAILED
Score < 0.5
→ WhatsApp reason
→ Sub resubmits
→ Back to step 5
Backend API — Route & Function Tree Click module to expand • Click route for details
👤

Users Router

5 routes ▼
POST
Register User
/users/register
POST
Login
/users/login → JWT token
GET
Get Current User
/users/me — auth required
PUT
Update Profile
/users/me — auth required
GET
Public Profile
/users/{id}/profile
🏗️

Projects Router

9 routes ▼
POST
Create Project
/projects/ — owner auth
GET
List Projects
/projects/ — marketplace
GET
Get Project
/projects/{id}
POST
Upload Blueprint
/projects/{id}/blueprint — AI parse
POST
Open Bidding
/projects/{id}/open-bidding
POST
Submit Bid
/projects/{id}/bids — GC auth
GET
Get Bids
/projects/{id}/bids — owner auth
POST
Award Bid
/projects/{id}/award/{bid_id}
POST
Create Milestones
/projects/{id}/milestones
🔍

Verifications Router

4 routes ▼
POST
Submit Verification
/verifications/submit — sub auth
POST
Override Verification
/verifications/{id}/override — GC/admin
POST
Approve Verification
/verifications/{id}/approve
GET
Project Verifications
/verifications/project/{id}
💳

Payments Router

4 routes ▼
POST
Fund Vault
/payments/fund-vault — owner auth
POST
Approve Invoice
/payments/approve-invoice
POST
Payout Sub
/payments/payout-sub — GC auth
GET
Project Payments
/payments/project/{id}/payments
🔗

Webhooks Router

2 routes ▼
POST
Twilio Inbound
/webhooks/twilio/inbound — WhatsApp/SMS
POST
Stripe Webhook
/webhooks/stripe/webhook
💬

Messages Router

2 routes ▼
GET
Get Messages
/messages/project/{id}/messages
POST
Send Message
/messages/project/{id}/messages
Core Services
🧠

ai_vision.py

4 functions ▼
fn
parse_blueprint_pdf()
PDF → milestones, scope, cost estimate JSON
fn
verify_work_submission()
media + blueprint → confidence score + status
fn
generate_cost_estimate()
project scope → line-item cost breakdown
fn
score_gc_diligence()
GC profile + bid → diligence score 0-100
💳

stripe_service.py

5 functions ▼
fn
create_project_vault()
project_id, amount → Stripe PaymentIntent escrow
fn
release_payment_to_gc()
invoice_id → transfer 90% to GC connected account
fn
release_payment_to_sub()
task_id, sub_id → instant transfer to sub
fn
hold_retainage()
10% per milestone withheld in vault
fn
release_retainage()
final lien waiver signed → release all retainage
📱

twilio_service.py

3 functions ▼
fn
send_whatsapp()
to, message, media_url → WhatsApp delivery
fn
handle_inbound_message()
webhook payload → route to verification or support
fn
send_sms()
to, message → SMS fallback for field workers
🔐

security.py

4 functions ▼
fn
create_access_token()
data: dict → signed JWT (24hr expiry)
fn
verify_token()
token → decoded payload or 401
fn
hash_password()
plain → bcrypt hash
fn
verify_password()
plain, hashed → bool
Database Models
👤

User

model▼
id
UUID primary key
str
email, name, phone
enum
role: owner | gc | sub | admin
str
hashed_password
str
stripe_account_id, license_number
bool
is_verified, is_active
🏗️

Project

model▼
uuid
id, owner_id (FK User), gc_id (FK User)
str
name, description, location, project_type
enum
status: draft→bidding→awarded→in_progress→completed
dec
total_budget, contract_value, retainage_pct
json
blueprint_data (AI parsed)
ts
created_at, bidding_opened_at, awarded_at
📋

Bid

model▼
uuid
id, project_id, gc_id
dec
amount, proposed_timeline_days
float
ai_diligence_score (0–100)
enum
status: submitted | awarded | rejected
text
proposal_text, notes
🎯

Milestone

model▼
uuid
id, project_id
str
name, description, specifications
dec
value, retainage_held
enum
status: pending | in_progress | submitted | verified | paid
int
order_index, due_days
🔍

Verification

model▼
uuid
id, milestone_id, task_id, submitted_by
arr
media_urls (photos/videos)
float
confidence_score (0.0–1.0)
enum
status: pending→verified|failed|ambiguous→overridden
json
ai_response (raw GPT-4o output)
str
failure_reason, override_by, override_notes
geo
gps_lat, gps_lng (submission location)
💰

Payment

model▼
uuid
id, project_id, invoice_id
uuid
from_user_id, to_user_id
dec
amount, retainage_amount
str
stripe_transfer_id, stripe_payment_intent_id
enum
status: pending | processing | completed | failed
🏦

ProjectVault

model▼
uuid
id, project_id (1:1)
dec
total_funded, total_released, retainage_held
str
stripe_payment_intent_id
enum
status: unfunded | funded | partially_released | closed
📄

LienWaiver

model▼
uuid
id, project_id, payment_id, signed_by
enum
type: conditional | unconditional
dec
amount_through
ts
signed_at, through_date
❓

RFI / ChangeOrder

models▼
rfi
RFI: id, project_id, submitted_by, question, response, status
co
ChangeOrder: id, project_id, description, amount_delta
enum
ChangeOrder.status: proposed | approved | rejected
🛡️

Insurance / ChatMessage

models▼
ins
Insurance: user_id, policy_number, carrier, expiry, verified
msg
ChatMessage: project_id, sender_id, content, created_at
task
Task: milestone_id, assigned_to (sub), status, instructions