Krow-workspace/docs/ARCHITECTURE/architecture.md

Krow Platform: System Architecture Overview

1. Executive Summary: The Business Purpose

The Krow Platform is an end-to-end workforce management ecosystem designed to bridge the gap between businesses that need staff ("Clients") and the temporary workers who fill those roles ("Staff").

Traditionally, this process involves phone calls, paper timesheets, and manual payroll. Krow digitizes the entire lifecycle:

1. Finding Work: Clients post shifts instantly; workers claim them via mobile.
2. Doing Work: GPS-verified clock-ins and digital timesheets ensure accuracy.
3. Managing Business: A web dashboard provides analytics, billing, and compliance oversight.

The system's goal is to reduce administrative friction, ensure legal compliance, and optimize labor costs through automation and real-time data.

2. The Application Ecosystem

The platform consists of three distinct applications, each tailored to a specific user group:

A. Client Mobile App (The "Requester")

• User: Business Owners, Venue Managers.
• Role: The demand generator. It allows clients to request staff on the fly, track who is arriving, and approve hours worked.
• Key Value: Speed and visibility. A manager can fill a sudden "no-show" gap in seconds from their phone.

B. Staff Mobile App (The "Worker")

• User: Temporary Staff (Servers, Cooks, Bartenders).
• Role: The supply pool. It acts as their personal agency, handling job discovery, schedule management, and instant payouts.
• Key Value: Flexibility and financial security. Workers choose when they work and get paid faster.

C. Krow Web Application (The "HQ")

• User: Administrators, HR, Finance, and Client Executives.
• Role: The command center. It handles the heavy lifting—complex invoicing, vendor management, compliance audits, and strategic data analysis.
• Key Value: Control and insight. It turns operational data into cost-saving strategies.

3. How the Applications Interact

The three applications do not "talk" directly to each other (e.g., the staff app doesn't send a message directly to the client app). Instead, they all communicate with a central Shared Backend System (The "Brain").

• Scenario: Filling a Shift
  1. Client App: Manager posts a shift for "Friday, 6 PM".
  2. Backend: Receives the request, validates it, and notifies eligible workers.
  3. Staff App: Worker sees the notification and taps "Accept".
  4. Backend: Confirms the match, updates the schedule, and alerts the client.
  5. Web App: Admin sees the shift status change from "Open" to "Filled" on the live dashboard.

4. Shared Services & Infrastructure

To function as a cohesive unit, the ecosystem relies on several shared foundational services:

• Central Database: The "Single Source of Truth." Whether a worker updates their profile photo on mobile or an admin updates it on the web, the change is saved in one place (Firebase/Firestore) and reflects everywhere instantly.
• Authentication Service: A unified login system. While users have different roles (Client vs. Staff), the security mechanism verifying their identity is shared.
• Notification Engine: A centralized service that knows how to reach users—sending push notifications to phones (Mobile Apps) and emails to desktops (Web App).
• Payment Gateway: A shared financial pipe. It collects money from clients (Credit Card/ACH) and disburses it to workers (Direct Deposit/Instant Pay).

5. Data Ownership & Boundaries

To maintain privacy and organization, data is strictly compartmentalized:

• Worker Data: Owned by the worker but accessible to the platform. Clients can only see limited details (Name, Rating, Skills) of workers assigned to their specific shifts. They cannot see a worker's full financial history or assignments with other clients.
• Client Data: Owned by the business. Workers see only what is necessary to do the job (Location, Dress Code, Supervisor Name). They cannot see the client's internal billing or strategic reports.
• Platform Data: owned by Krow (Admins). This includes the aggregate data used for "Smart Strategies" and market analysis—e.g., "Average hourly rate for a Bartender in downtown."

6. Security & Access Control

The system operates on a Role-Based Access Control (RBAC) model:

• Authentication (Who are you?): Strict verification using email/password or phone/OTP (One-Time Password).
• Authorization (What can you do?):
  • Staff: Can read job details but write only to their own timesheets and profile.
  • Clients: Can write new orders and read reports for their own venues only.
  • Admins: Have "Super User" privileges to view and modify data across the entire system to resolve disputes or manage configurations.

7. Inter-Application Dependencies

While the apps are installed separately, they are operationally dependent:

• Dependency A: The Client App cannot function without the Staff App users. An order posted by a client is useless if no workers exist to claim it.
• Dependency B: The Staff App relies on the Web App for financial processing. A worker can "clock out," but they don't get paid until the backend logic (managed via Web App rules) processes the invoice.
• Dependency C: All apps depend on the Backend API. If the central server goes down, no app can fetch data, effectively pausing the entire operation.

---

System Overview Diagram

flowchart LR
    subgraph Users [Users]
        ClientUser((Client Manager))
        StaffUser((Temporary Worker))
        AdminUser((Admin / Ops))
    end

    subgraph FrontEnd [Application Ecosystem]
        direction TB
        ClientApp[Client Mobile App]
        StaffApp[Staff Mobile App]
        WebApp[Web Management Console]
    end

    subgraph Backend [Shared Backend Services]
        direction TB
        APIGateway[API Gateway]
        
        subgraph CoreServices [Core Business Logic]
            AuthService[Authentication Service]
            OrderService[Order & Shift Service]
            WorkerService[Worker Profile Service]
            FinanceService[Billing & Payroll Service]
            NotificationEngine[Notification Engine]
            AnalyticsEngine[Analytics & AI Engine]
        end
        
        Database[("Central Database (Firebase/Firestore)")]
    end

    subgraph External [External Integrations]
        PaymentProvider["Payment Gateway (Stripe/Bank)"]
        MapService[Maps & Geolocation]
        SMSGateway[SMS / OTP Service]
    end

    %% User Interactions
    ClientUser -- Uses --> ClientApp
    StaffUser -- Uses --> StaffApp
    AdminUser -- Uses --> WebApp

    %% App to Backend Communication
    ClientApp -- "Auth, Orders, Timesheets" --> APIGateway
    StaffApp -- "Auth, Job Claims, Clock-In" --> APIGateway
    WebApp -- "Auth, Admin, Reports" --> APIGateway

    %% Internal Backend Flow
    APIGateway --> CoreServices
    CoreServices --> Database
    
    %% Specific Service Interactions
    AuthService -- "Verifies Identity" --> Database
    OrderService -- "Matches Shifts" --> Database
    WorkerService -- "Stores Profiles" --> Database
    FinanceService -- "Processes Invoices" --> Database
    AnalyticsEngine -- "Reads Data" --> Database

    %% External Connections
    AuthService -- "Sends OTP" --> SMSGateway
    StaffApp -- "Verifies Location" --> MapService
    FinanceService -- "Processes Payouts" --> PaymentProvider
    NotificationEngine -- "Push Alerts" --> ClientApp
    NotificationEngine -- "Push Alerts" --> StaffApp

    %% Styling
    classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
    classDef app fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
    classDef db fill:#e0e0e0,stroke:#616161,stroke-width:2px;

    class ClientUser,StaffUser,AdminUser user;
    class ClientApp,StaffApp,WebApp app;
    class APIGateway,AuthService,OrderService,WorkerService,FinanceService,NotificationEngine,AnalyticsEngine backend;
    class PaymentProvider,MapService,SMSGateway external;
    class Database db;