clean

2026-01-10 21:22:35 -05:00
parent 90455d9181
commit d43a14ee0c
116 changed files with 41323 additions and 19 deletions
--- a/internal/launchpad/assets/diagrams/architectures/0-infra-compliance.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/0-infra-compliance.mermaid
@@ -0,0 +1,67 @@
+
+graph TB
+    Title["<b>KROW - Cloud Architecture</b><br/>Production Solution"]
+    
+    subgraph Prototype[" "]
+        Proto["🔧 Current KROW Prototype<br/>(Demo Only)"]
+    end
+    
+    Title --> Prototype
+    Title --> Production
+    
+    subgraph Production["🏢 KROW - PRODUCTION ARCHITECTURE"]
+        subgraph GCP["☁️ Google Cloud Platform - US Regions"]
+            
+            subgraph Auth["🔐 Authentication"]
+                Firebase["Firebase Auth<br/>• MFA<br/>• OAuth 2.0"]
+            end
+            
+            subgraph Backend["⚙️ Backend"]
+                Functions["Cloud Functions<br/>• Serverless<br/>• Auto-scaling"]
+                API["API Gateway<br/>• Secure APIs<br/>• Rate limiting"]
+            end
+            
+            subgraph Data["💾 Data Storage"]
+                Firestore["Firestore/Cloud SQL<br/>• Encrypted at rest<br/>• Auto backup"]
+                Storage["Cloud Storage<br/>• Encrypted<br/>• Access control"]
+            end
+            
+            subgraph Security["🛡️ Security"]
+                IAM["Cloud IAM<br/>• Access control<br/>• Least privilege"]
+                Logs["Logging & Monitoring<br/>• Audit trails<br/>• Real-time alerts"]
+            end
+        end
+        
+        subgraph Compliance["✅ COMPLIANCE"]
+            GDPR["📋 GDPR Ready<br/>• US data hosting<br/>• User rights<br/>• Data portability"]
+            SOC2["🏆 SOC 2 Ready<br/>• Google certified<br/>• Security controls<br/>• Full audit trails"]
+        end
+    end
+    
+    Users["👥 End Users"]
+    
+    Proto -.->|Migration vers| Production
+    Users --> Auth
+    Auth --> API
+    API --> Functions
+    Functions --> Firestore
+    Functions --> Storage
+    IAM --> Auth
+    IAM --> Backend
+    IAM --> Data
+    Logs --> Security
+    GCP --> GDPR
+    GCP --> SOC2
+    
+    style Prototype fill:#FFF3CD,stroke:#856404,stroke-width:2px,stroke-dasharray: 5 5
+    style Proto fill:#FFF3CD,stroke:#856404
+    style Title fill:#1976D2,stroke:#0D47A1,stroke-width:3px,color:#FFFFFF
+    style Production fill:#D4EDDA,stroke:#155724,stroke-width:3px
+    style GCP fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
+    style Auth fill:#E8F5E9,stroke:#2E7D32
+    style Backend fill:#E8F5E9,stroke:#2E7D32
+    style Data fill:#E8F5E9,stroke:#2E7D32
+    style Security fill:#FFE0B2,stroke:#E65100
+    style Compliance fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px
+    style GDPR fill:#E1BEE7,stroke:#6A1B9A
+    style SOC2 fill:#E1BEE7,stroke:#6A1B9A
--- a/internal/launchpad/assets/diagrams/architectures/1-core-workflow.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/1-core-workflow.mermaid
@@ -0,0 +1,70 @@
+sequenceDiagram
+    participant Client as 🏢 Client App
+    participant Backend as 🌐 Backend API
+    participant Admin as ⚙️ KROW Admin
+    participant Staff as 👥 Staff App
+    
+    %% Event Creation
+    Note over Client,Backend: 1. Event & Shift Creation
+    Client->>Backend: Create Event with Shifts & Positions
+    Backend-->>Client: Event Created (Draft)
+    Client->>Backend: Publish Event
+    Backend-->>Client: Event Published
+    
+    %% Staff Assignment
+    Note over Admin,Backend: 2. Staff Assignment
+    Admin->>Backend: View Available Events
+    Backend-->>Admin: Event List
+    Admin->>Backend: Assign Staff to Shift
+    Backend-->>Admin: Assignment Confirmed
+    Backend->>Staff: Notification: New Shift Assigned
+    
+    %% Shift Acceptance
+    Note over Staff,Backend: 3. Shift Acceptance
+    Staff->>Backend: View Shift Details
+    Backend-->>Staff: Shift Information
+    Staff->>Backend: Accept Shift
+    Backend-->>Staff: Shift Confirmed
+    Backend->>Client: Notification: Staff Confirmed
+    
+    %% Clock In
+    Note over Client,Staff: 4. Clock In - Day of Event
+    Client->>Client: Generate QR Code for Event
+    Staff->>Staff: Scan QR Code
+    Staff->>Backend: Clock In Request (via QR)
+    Backend-->>Staff: Clock In Confirmed
+    Backend->>Client: Notification: Staff Clocked In
+    Client->>Backend: (Alternative) Manual Clock In
+    Backend-->>Client: Manual Clock In Confirmed
+    
+    %% Shift Active
+    Note over Staff: 5. Shift In Progress
+    Staff->>Staff: View Real-time Timer
+    
+    %% Clock Out
+    Note over Client,Staff: 6. Clock Out - End of Shift
+    Staff->>Staff: Scan QR Code
+    Staff->>Backend: Clock Out Request (via QR)
+    Backend-->>Staff: Clock Out Confirmed
+    Backend-->>Staff: Shift Status: Completed
+    Backend->>Client: Notification: Staff Clocked Out
+    
+    %% Rating & Invoicing
+    Note over Client,Backend: 7. Post-Shift Activities
+    Client->>Backend: Rate Staff Performance
+    Backend-->>Client: Rating Recorded
+    Backend->>Backend: Generate Invoice
+    Backend->>Client: Invoice Created
+    Client->>Backend: Review & Approve Invoice
+    Backend-->>Client: Invoice Approved
+    
+    %% Payment
+    Note over Staff,Backend: 8. Staff Payment
+    Backend->>Staff: Payment Processed
+    Staff->>Backend: View Earnings & Payment History
+    Backend-->>Staff: Payment Details
+    
+    alt Payment Dispute
+        Staff->>Backend: Contest Payment Amount
+        Backend-->>Staff: Dispute Opened
+    end
--- a/internal/launchpad/assets/diagrams/architectures/2-high-level-architecture.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/2-high-level-architecture.mermaid
@@ -0,0 +1,61 @@
+graph TB
+    subgraph "Actors"
+        Staff[👥 Staff/Employee]
+        Client[🏢 Client/Business]
+        Admin[⚙️ KROW Admin]
+    end
+    
+    subgraph "KROW Staff App"
+        SA_Auth[Authentication & Onboarding]
+        SA_Shifts[Shift Management]
+        SA_Earnings[Earnings & Payments]
+        SA_Profile[Profile Management]
+    end
+    
+    subgraph "KROW Client App"
+        CA_Events[Event Creation]
+        CA_Staff[Staff Management]
+        CA_Time[Time Tracking - QR Code]
+        CA_Invoice[Invoicing]
+    end
+    
+    subgraph "Backend System"
+        API[Backend API]
+        DB[(Database)]
+    end
+    
+    %% Staff interactions
+    Staff -->|Registers & Manages Profile| SA_Auth
+    Staff -->|Views & Accepts Shifts| SA_Shifts
+    Staff -->|Scans QR Code - Clock In/Out| SA_Shifts
+    Staff -->|Tracks Earnings| SA_Earnings
+    Staff -->|Updates Skills & Documents| SA_Profile
+    
+    %% Client interactions
+    Client -->|Creates Events & Shifts| CA_Events
+    Client -->|Views Assigned Staff| CA_Staff
+    Client -->|Generates QR Code| CA_Time
+    Client -->|Manual Clock In/Out| CA_Time
+    Client -->|Rates Staff| CA_Staff
+    Client -->|Reviews & Approves Invoices| CA_Invoice
+    
+    %% Admin interactions
+    Admin -->|Assigns Staff to Shifts| API
+    Admin -->|Validates Staff Profiles| API
+    
+    %% App to Backend connections
+    SA_Auth -.->|Profile Data| API
+    SA_Shifts -.->|Shift Status Updates| API
+    SA_Earnings -.->|Payment Data| API
+    SA_Profile -.->|User Data| API
+    
+    CA_Events -.->|Event & Shift Data| API
+    CA_Staff -.->|Staff Ratings| API
+    CA_Time -.->|Time Records| API
+    CA_Invoice -.->|Invoice Data| API
+    
+    API <-->|Data Storage & Retrieval| DB
+    
+    style Staff fill:#e1f5ff
+    style Client fill:#fff4e1
+    style Admin fill:#f0e1ff
--- a/internal/launchpad/assets/diagrams/architectures/3-invoice-workflow-simple.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/3-invoice-workflow-simple.mermaid
@@ -0,0 +1,40 @@
+graph LR
+    START[💼 Shift<br/>Completed<br/>& Rated]
+    
+    START --> CALC[📊 INTERNAL<br/><br/>Calculate Invoice<br/>• Hours worked<br/>• Rates × Hours<br/>• Overtime calc<br/>• Platform fees<br/>• Tax amounts]
+    
+    CALC --> GENERATE[📄 INTERNAL<br/><br/>Generate Invoice<br/>• Create PDF<br/>• Invoice number<br/>• Line items<br/>• Due date]
+    
+    GENERATE --> SAVE[💾 INTERNAL<br/><br/>Save to Database<br/>• Store invoice<br/>• Status: pending<br/>• Track history]
+    
+    SAVE --> SEND[📧 API INTEGRATION<br/><br/>SendGrid<br/>• Send email<br/>• Track delivery<br/>• Reliable inbox]
+    
+    SEND --> CLIENT[📱 Client<br/>Reviews<br/>Invoice]
+    
+    CLIENT --> DECISION{Approve or<br/>Dispute?}
+    
+    DECISION -->|⚠️ Dispute| DISPUTE[🔧 INTERNAL<br/><br/>Handle Dispute<br/>• Admin reviews<br/>• Adjustments<br/>• Re-calculate]
+    
+    DISPUTE --> SAVE
+    
+    DECISION -->|✅ Approve| PAY[💳 API INTEGRATION<br/><br/>Stripe<br/>• Credit card<br/>• ACH transfer<br/>• Payment tracking]
+    
+    PAY --> CONFIRM[💾 INTERNAL<br/><br/>Update Status<br/>• Mark as paid<br/>• Record payment<br/>• Update reports]
+    
+    CONFIRM --> PAYOUT[💰 API INTEGRATION<br/><br/>Stripe Connect<br/>• Pay staff<br/>• Direct deposit<br/>• Automated]
+    
+    PAYOUT --> RECORD[📊 INTERNAL<br/><br/>Track Payments<br/>• Staff earnings<br/>• Payment history<br/>• Reports]
+    
+    RECORD --> DONE[✅ Complete]
+    
+    style START fill:#E1F5FF
+    style CALC fill:#FFF9E6,stroke:#F9A825,stroke-width:3px
+    style GENERATE fill:#FFF9E6,stroke:#F9A825,stroke-width:3px
+    style SAVE fill:#FFF9E6,stroke:#F9A825,stroke-width:3px
+    style DISPUTE fill:#FFF9E6,stroke:#F9A825,stroke-width:3px
+    style CONFIRM fill:#FFF9E6,stroke:#F9A825,stroke-width:3px
+    style RECORD fill:#FFF9E6,stroke:#F9A825,stroke-width:3px
+    style SEND fill:#E3F2FD,stroke:#1976D2,stroke-width:3px
+    style PAY fill:#E3F2FD,stroke:#1976D2,stroke-width:3px
+    style PAYOUT fill:#E3F2FD,stroke:#1976D2,stroke-width:3px
+    style DONE fill:#90EE90
--- a/internal/launchpad/assets/diagrams/architectures/4-mobile-app-architecture.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/4-mobile-app-architecture.mermaid
@@ -0,0 +1,24 @@
+graph TD
+    subgraph KROW Mobile Applications
+        direction LR
+        Mobile_Client[<b>Mobile Client App</b><br>Flutter]
+        Mobile_Staff[<b>Mobile Staff App</b><br>Flutter]
+    end
+
+    subgraph Firebase Backend Services - GCP
+        direction TB
+        Auth[Firebase Authentication]
+        DataConnect[<b>Firebase Data Connect</b><br>GraphQL API &<br>Generated SDKs]
+        SQL_DB[<b>Cloud SQL for PostgreSQL</b><br><i>Managed by Data Connect</i>]
+    end
+
+    Mobile_Client -- "Authenticates with" --> Auth
+    Mobile_Client -- "Calls API via generated SDK" --> DataConnect
+
+    Mobile_Staff -- "Authenticates with" --> Auth
+    Mobile_Staff -- "Calls API via generated SDK" --> DataConnect
+
+    DataConnect -- "Manages & Queries" --> SQL_DB
+    
+    style Mobile_Client fill:#eef,stroke:#333,stroke-width:2px
+    style Mobile_Staff fill:#eef,stroke:#333,stroke-width:2px
--- a/internal/launchpad/assets/diagrams/architectures/5-web-app-architecture.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/5-web-app-architecture.mermaid
@@ -0,0 +1,29 @@
+graph LR
+    subgraph Base44 Environment
+        direction TB
+        Client[Client] -- Modifies --> B44_UI[<b>Base44 Visual Builder</b><br><i>Features:</i><br>- Event Management<br>- Staff Directory<br>- Vendor Onboarding]
+        B44_UI --> B44_Backend[<b>Base44 Backend</b><br>Provides Entity Schemas<br>& SDK Operations]
+        B44_Backend --> B44_DB[Base44 Database]
+    end
+
+    subgraph Firebase Ecosystem - GCP
+        direction TB
+        KROW_FE[<b>KROW Frontend</b><br>Vite/React + TanStack Query<br><i>From Export</i>]
+        
+        subgraph Firebase Services
+            direction TB
+            Auth[Firebase Authentication]
+            DataConnect[<b>Firebase Data Connect</b><br>GraphQL API &<br>Generated SDKs]
+            SQL_DB[<b>Cloud SQL for PostgreSQL</b><br><i>Managed by Data Connect</i>]
+        end
+
+        KROW_FE -- "Uses" --> Auth
+        KROW_FE -- "Calls Queries/Mutations via SDK" --> DataConnect
+        DataConnect -- "Manages & Queries" --> SQL_DB
+    end
+
+    B44_UI -- "<b>UI Code Export</b><br>(React Components)" --> KROW_FE
+
+    style Client fill:#f9f,stroke:#333,stroke-width:2px
+    style B44_UI fill:#ffe,stroke:#333,stroke-width:2px
+    style KROW_FE fill:#eef,stroke:#333,stroke-width:2px
--- a/internal/launchpad/assets/diagrams/architectures/6-geofencing-clockin-clockout.mermaid
+++ b/internal/launchpad/assets/diagrams/architectures/6-geofencing-clockin-clockout.mermaid
@@ -0,0 +1,32 @@
+sequenceDiagram
+    participant Staff as Staff Member
+    participant App as KROW Staff App
+    participant Client as Client
+    participant Backend as Backend
+
+    Staff->>App: Opens shift and taps "Clock In"
+
+    activate App
+    App->>App: **1. Geofencing Check (GPS) BEFORE scan**
+
+    alt Proximity Validated
+        App->>Client: Requests QR Code
+        Client-->>Staff: Presents QR Code
+        Staff->>App: Scans the code
+        App->>Backend: Validates Clock In with eventId
+        Backend-->>App: Confirmation
+        App->>Staff: Displays "Clock In Successful"
+    else Proximity Failed (GPS bug, too far)
+        App->>Staff: Displays "Error: You are too far"
+    end
+    deactivate App
+
+    loop Continuous Monitoring DURING the shift
+        App->>App: **2. Checks GPS position (anti-fraud)**
+        opt Staff member leaves the > 500m area
+            App->>Backend: Notifies area exit
+            Backend-->>App: Triggers a "Force Clock-Out"
+        end
+    end
+
+    %% Clock Out process follows a similar logic (Geofencing + QR Code) %%