Client App Specification & Architecture Hub

Client App Wireflow (High-Level Page Navigation Logic)

MERMAID LOGIC

Click to Zoom Fullscreen

graph TD
    classDef gateway fill:#27272a,stroke:#71717a,color:#ffffff,font-weight:bold
    classDef owner fill:#064e3b,stroke:#10b981,color:#ecfdf5,font-weight:bold
    classDef proxy fill:#7c2d12,stroke:#f97316,color:#fff7ed,font-weight:bold

    Gateway[Client App Gateway]:::gateway --> RoleCheck{User Role Auth}:::gateway
    
    %% Owner Workspace Navigation
    RoleCheck -->|Business Owner| Today[CA-01 Today Dashboard]:::owner
    Today --> Team[CA-02 Team Directory]:::owner
    Today --> Documents[CA-03 Documents & eSign]:::owner
    Today --> Settings[CA-04 Settings]:::owner
    Today --> Support[CA-05 Support Desk]:::owner
    
    Documents -->|Dispatch Packet| PublicSign[CA-06 Public eSign Portal]:::proxy
    PublicSign -->|Edge Worker| CFWorker[punchcharlie-proxy]:::proxy

Client App Sitemap & Page Hierarchy

SITE MAP TREE

Owner App Pages

1. Today (Velocity Dashboard) /today.html →
2. Team & Staff Management /team.html →
3. Documents & eSign Workflows /documents.html →
4. Settings /settings.html →
5. Support & Help Center /support.html →
6. Public eSign Portal & Proxy /public-esign.html →

Client App System Guardrails & Validation Matrix

COMPLIANCE RULES

Geofence Location Restriction (50m Radius)

Mobile punches must originate within 50m of verified workplace GPS coordinates.

Mandatory Rest Hour Rule (8h minimum)

Prevents roster scheduling if employee rest gap between shifts is less than 8 consecutive hours.

ESIGN Act Compliance Audit Stamp

Requires mandatory full-text scroll before signature canvas unlocks, logging IP & SHA-256 hash.

PIN Failed Lockout Gate

5 consecutive failed PIN attempts trigger 15-minute lock and notify organization owner.

7-Day Trial Expiration & Service Paywall Lockout

When trial_ends_at < NOW() and status is not active, clock-in endpoints return 402 Payment Required, locking kiosk terminal punches and requiring Stripe subscription attachment.

Multi-Email Trial Abuse & Domain Fingerprinting Prevention

Prevents trial recycling via disposable email aliases. Enforces company domain matching, owner phone/tax ID deduplication, Stripe payment method fingerprinting ($0 authorization check), and IP/subnet rate limits (max 1 trial per 90 days per device/subnet).

Client App Backend & Supabase Service Sequence

SEQUENCE FLOW

sequenceDiagram
    autonumber
    actor Staff as Employee
    participant Client as Client Terminal App
    participant Edge as Supabase Edge API
    participant DB as PostgreSQL DB

    Staff->>Client: Enters PIN / Scans Face
    Client->>Edge: POST /api/v2/punch/clock-in
    Edge->>Edge: Validate Geofence GPS & PIN
    Edge->>DB: INSERT into timecard_records
    DB-->>Edge: Returns Record UUID
    Edge-->>Client: 200 OK + Sync Timecard State
    Client-->>Staff: Display Success Toast & Confirmation

Client App Complete Screen Inventory

6 SCREENS

Screen Name	Route URL	Role Access	Action Link
1. Today (Velocity Dashboard)	/client-app/today.html	Owner	View Spec →
2. Team & Staff Management	/client-app/team.html	Owner	View Spec →
3. Documents & eSign Workflows	/client-app/documents.html	Owner / All	View Spec →
4. Settings	/client-app/settings.html	Owner	View Spec →
5. Support & Help Center	/client-app/support.html	Owner	View Spec →
6. Public eSign Portal & Proxy	/client-app/public-esign.html	Cloudflare Proxy	View Spec →

Client Application Visual Architecture

Page Visual Switcher

Client App Wireflow (High-Level Page Navigation Logic)

Client App Sitemap & Page Hierarchy

Client App System Guardrails & Validation Matrix

Client App Backend & Supabase Service Sequence

Client App Complete Screen Inventory

Client Application Visual Architecture

Page Visual Switcher

Client App Wireflow (High-Level Page Navigation Logic)

Client App Sitemap & Page Hierarchy

Client App System Guardrails & Validation Matrix

Client App Backend & Supabase Service Sequence

Client App Complete Screen Inventory

Client App Wireflow — Fullscreen Interactive View