# Krow System Architecture Overview

## 1. System Purpose: The Digital Workforce Marketplace
The **Krow Ecosystem** is a complete digital solution for the temporary staffing industry. Its primary purpose is to seamlessly connect two groups of people:
1.  **Businesses** (restaurants, event venues) who need temporary staff.
2.  **Workers** (waiters, security, chefs) who are looking for flexible shifts.

Instead of using agencies, phone calls, or spreadsheets, the Krow system automates the entire process: finding staff, verifying their skills, tracking their work hours on-site, and processing payments. It turns a chaotic manual process into a smooth, transparent digital workflow.

## 2. The Role of Each Application
The system is composed of three distinct applications, each tailored for a specific user:

### A. The Client App (Mobile)
*   **User:** Business Owners & Managers.
*   **Role:** The "Demand" side. It allows businesses to post jobs ("Shifts"), see who is working for them, monitor attendance in real-time, and handle invoices.
*   **Key Analogy:** Like the "Uber" app for a passenger—requesting a service and paying for it.

### B. The Staff App (Mobile)
*   **User:** Temporary Workers.
*   **Role:** The "Supply" side. It allows workers to build a professional profile, find and accept jobs, and use their phone to "Clock In" and "Clock Out" at venues.
*   **Key Analogy:** Like the "Uber Driver" app—accepting jobs and proving the work was done.

### C. The Web Platform (Web & Backend)
*   **User:** Krow Operations Team (Admins) & System Logic.
*   **Role:** The "Brain" and "Control Tower." It stores all the data, enforces the rules (e.g., "You can't work if your visa is expired"), and provides a dashboard for Krow staff to oversee the entire business.
*   **Key Analogy:** The Uber HQ dashboard—managing the market, resolving disputes, and ensuring safety.

## 3. How They Interact
These applications do not speak to each other directly; they all speak to the **Web Platform**.

*   **Client to Platform:** When a business posts a shift in the Client App, it sends that request to the Web Platform. The Platform saves it and makes it searchable.
*   **Platform to Staff:** The Platform identifies which workers match the new shift (based on skills and location) and makes the job visible in their Staff App.
*   **Staff to Platform:** When a worker taps "Accept," the Staff App tells the Platform. The Platform checks if they are still available and confirms the booking.
*   **Staff to Client (via Platform):** When a worker scans a QR code to Clock In, the Staff App tells the Platform "I'm here." The Platform instantly updates the Client App, so the manager sees "Active" on their screen.

## 4. Shared Services & Infrastructure
To keep the system fast, secure, and reliable, all three apps share a common foundation:

*   **Central Database:** A single source of truth. Whether you look at a shift on the iPhone Client App, Android Staff App, or Web Dashboard, you are looking at the exact same record in the database.
*   **GraphQL API:** The "Language" of the system. It’s a specialized way for the mobile apps to ask the server for data. It ensures that even if a user has a slow connection, the app remains responsive by asking only for exactly what it needs.
*   **Firebase Authentication:** A shared security service. It handles the complex work of storing passwords and verifying emails. This means a user’s identity is secure across the entire ecosystem.
*   **Maps & Geolocation:** All apps use the same mapping services to understand where "Venue A" is and whether "Worker B" is standing inside it.

## 5. Data Ownership & Boundaries
*   **The Web Platform Owns Everything:** The mobile apps are just "viewers." They don't permanently own the data. If a phone is lost or the app is deleted, the data (shifts, earnings, invoices) is safe on the server.
*   **Client Data Boundary:** A Business can *only* see their own hubs, their own events, and the staff assigned to *their* shifts. They cannot see a worker's history with other businesses.
*   **Staff Data Boundary:** A Worker can *only* see shifts they are eligible for and their own financial history. They cannot see internal business details or other workers' pay rates.

## 6. Security & Access Control
The system uses a strict **Role-Based Access Control (RBAC)** model:
*   **Authentication (Who are you?):** Handled by Firebase. Every request to the server must include a digital "ID Card" (Token) proving the user is logged in.
*   **Authorization (What can you do?):** Handled by the Web Platform. Even if a Staff member tries to "hack" the app to ask for an Invoice, the Server will check their role, see they are "Staff" (not "Client"), and block the request immediately.
*   **Verification Gates:** The system includes human-in-the-loop security. A staff member cannot just sign up and work; they enter a "Pending" state until a Krow Admin manually reviews their documents on the Web Platform.

## 7. Critical Dependencies
The ecosystem relies on the **Web Platform** being online.
*   **If the Staff App fails:** Only workers are affected.
*   **If the Client App fails:** Only businesses are affected.
*   **If the Web Platform fails:** The entire system stops. No new shifts can be posted, no one can apply, and real-time clock-ins might fail (though the apps have some offline safeguards).
*   **3rd Party Reliance:** The system depends on **Firebase** (for login) and **Payment Gateways** (to move money). If these global services go down, Krow's ability to log users in or pay them will pause.

## 8. Overview Diagram
```mermaid
flowchart LR
    %% Define Styles
    classDef clientApp fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
    classDef staffApp fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
    classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef db fill:#eee,stroke:#333,stroke-width:2px,color:#333
    classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c

    subgraph Mobile_Apps["Mobile Ecosystem"]
        direction TB
        ClientApp["Client Mobile App<br/>(Business Owners)"]:::clientApp
        StaffApp["Staff Mobile App<br/>(Workers)"]:::staffApp
    end

    subgraph Core_Platform["Krow Web Platform"]
        direction TB
        AdminPanel["Admin Dashboard<br/>(Operations Team)"]:::backend
        APIServer["Central API Server<br/>(GraphQL Logic)"]:::backend
        Database[("Central Database")]:::db
        Storage["File Storage<br/>(Photos/Docs)"]:::db
    end

    subgraph External_Services["Cloud Services"]
        direction TB
        Firebase["Firebase<br/>(Auth & Push)"]:::external
        Maps["Google Maps API<br/>(Location)"]:::external
    end

    %% Communication Flows
    ClientApp <-->|Post Shifts, View Invoices| APIServer
    StaffApp <-->|Apply for Jobs, Clock In| APIServer
    AdminPanel <-->|Manage Users, Resolve Disputes| APIServer

    APIServer <-->|Read/Write Data| Database
    APIServer <-->|Save/Retrieve Files| Storage

    ClientApp -.->|Secure Login| Firebase
    StaffApp -.->|Secure Login| Firebase
    AdminPanel -.->|Secure Login| Firebase

    APIServer -->|Send Notifications| Firebase
    APIServer -->|Validate Addresses| Maps
    StaffApp -.->|Verify Location| Maps
```