# Client Mobile Application: Architecture Overview

## 1. Executive Summary
The **Client Mobile Application** is a specialized tool designed for business owners and managers ("Clients") to effortlessly manage their temporary workforce. It serves as the command center for staffing operations, allowing clients to request new staff, monitor active shifts in real-time, handle billing, and analyze operational performance.

Think of it as the "Uber for Staffing" from the business perspective—providing on-demand access to a workforce, real-time tracking, and administrative control in a pocket-sized interface.

## 2. High-Level Architecture
The application is built using **Flutter**, a cross-platform framework that allows a single codebase to run natively on both iOS and Android devices.

The architecture follows a **Feature-First Layered approach**. This means the code is organized primarily by the business features (e.g., "Creating an Order," "Viewing Reports") rather than just technical file types. This structure makes the app easier to navigate and maintain as it grows.

At a high level, the system operates in three layers:
1.  **Presentation Layer (UI):** What the user sees and interacts with (Screens, Buttons, Forms).
2.  **Logic Layer (State Management):** The "brain" that handles user inputs and decides what to show next (currently managed via Riverpod and local widget state).
3.  **Data Layer (Infrastructure):** The connection points to the backend database and external services (currently simulated with mock data for the prototype).

## 3. Major Components & Modules

The application is broken down into several key functional modules:

### A. Authentication Module
*   **Responsibility:** Handles secure user entry into the app.
*   **Key Features:** `Sign In`, `Sign Up`, and `Get Started` onboarding flows.
*   **Purpose:** Ensures only authorized business personnel can access sensitive staffing and billing data.

### B. Dashboard & Home Module
*   **Responsibility:** Provides an immediate "pulse check" of the business's staffing status.
*   **Key Features:** `Live Activity` feed, `Spending Insights`, `Today's Coverage` summary, and `Quick Actions` for common tasks.
*   **Purpose:** Gives managers the critical info they need within seconds of opening the app.

### C. Order Management Module
*   **Responsibility:** The core engine for requesting staff.
*   **Key Features:**
    *   **Rapid Order:** For urgent, same-day needs.
    *   **One-Time Order:** For specific upcoming events.
    *   **Recurring Order:** For regular weekly needs.
    *   **Permanent Order:** For long-term staffing solutions.
*   **Purpose:** Simplifies the complex logistics of scheduling shifts into intuitive, guided forms.

### D. Workforce Management Module
*   **Responsibility:** Managing the people and their time.
*   **Key Features:**
    *   **Shifts:** View upcoming, active, and past shifts.
    *   **Workers:** Directory of assigned staff.
    *   **Timesheets:** Review and approve work hours.
    *   **Verify Attire:** Tools to ensure staff meet dress code compliance.

### E. Analytics & Reporting Module
*   **Responsibility:** Business intelligence and data visualization.
*   **Key Features:** Reports for `Daily Operations`, `Spending`, `Forecasting`, `Performance`, and `Attendance` (No-shows).
*   **Purpose:** Empowers clients to make data-driven decisions about their staffing budget and strategy.

### F. Administration Module
*   **Responsibility:** Account and configuration management.
*   **Key Features:** `Billing` management, `Settings`, and `Hubs` (managing different business locations).

## 4. Component Responsibilities

| Component | Primary Responsibility | Example Task |
| :--- | :--- | :--- |
| **Router (GoRouter)** | Navigation traffic cop | Directs the user from the "Login" screen to the "Home" dashboard upon success. |
| **Screens (UI)** | Displaying information | Renders the "Create Order" form and captures the user's input for date and time. |
| **Providers (Riverpod)** | Data management & State | Holds the list of today's active shifts so multiple screens can access it without reloading. |
| **Widgets** | Reusable UI building blocks | A "Shift Card" widget that displays shift details effectively, used in multiple lists throughout the app. |

## 5. Data Flow

1.  **User Action:** A client taps "Post Shift" on the Create Order screen.
2.  **Input Processing:** The app validates the input (e.g., checking if the start time is before the end time).
3.  **State Update:** The app updates its internal "State" to reflect that a submission is in progress (showing a loading spinner).
4.  **Data Transmission (Future State):** The app sends a structured request to the backend server (API).
5.  **Confirmation:** Upon success, the app navigates the user back to the Home screen and updates the "Live Activity" feed to show the newly created open shift.
6.  **Read Action:** When viewing the Dashboard, the app requests the latest coverage metrics to display the "80% Covered" status.

## 6. External System Communication

While currently operating as a high-fidelity prototype with mock data, the architecture is designed to connect with:

*   **Backend API (Firebase/Cloud Functions):** The app will communicate with a cloud backend to store and retrieve data. It uses `Firebase Core` and `Data Connect`.
*   **Authentication Service:** Manages user identities securely.
*   **Notification Service:** Sends push notifications to the client when a worker clocks in or if a shift is missed.

## 7. Architectural Patterns

*   **Model-View-ViewModel (MVVM) Inspiration:** The app separates the **View** (UI Screens) from the **Data Models**.
*   **Declarative UI:** Using Flutter, the UI is built by describing *what* it should look like based on the current state, rather than manually updating elements.
*   **Provider Pattern (Riverpod):** Used for Dependency Injection and State Management. This allows different parts of the app to share data (like the current user's profile) without tightly coupling components together.
*   **Feature-Based Folder Structure:** Code is organized by "what it does" (e.g., `screens/client/reports`) rather than just technical type, making it easier for new developers to understand the business logic.

## 8. Key Design Decisions

*   **Flutter Framework:** chosen for its ability to produce high-performance, native-feeling apps for both iOS and Android from a single codebase, reducing development time and cost.
*   **GoRouter for Navigation:** A modern routing package that handles complex navigation scenarios (like deep linking and sub-routes) which are essential for a multi-layered app like this.
*   **Riverpod for State Management:** A robust solution that catches programming errors at compile-time (while writing code) rather than run-time (while using the app), increasing app stability.
*   **Mock Data Services:** The decision to use extensive mock data allows for rapid UI/UX iteration and testing of business flows without waiting for the full backend infrastructure to be built.

## 9. Overview Diagram
```mermaid
flowchart TD
    subgraph ClientMobileApp["Client Mobile Application"]
        direction TB
        subgraph PresentationLayer["Presentation Layer (UI)"]
            direction TB
            Router["GoRouter Navigation"]
            subgraph FeatureModules["Feature Modules"]
                AuthUI["Auth Screens"]
                DashUI["Dashboard & Home"]
                OrderUI["Order Management"]
                WorkUI["Workforce Management"]
                ReportUI["Analytics & Reporting"]
                AdminUI["Administration"]
            end
            Router --> FeatureModules
        end
        
        subgraph LogicLayer["Logic Layer (State Management)"]
            direction TB
            Providers["Riverpod Providers"]
            State["App State"]
            Validation["Input Validation"]
        end
        
        subgraph DataLayer["Data Layer (Infrastructure)"]
            direction TB
            Repositories["Repositories"]
            Models["Data Models"]
            MockService["Mock Data Service"]
        end
        
        PresentationLayer --> LogicLayer
        LogicLayer --> DataLayer
    end
    
    subgraph ExternalSystems["External Systems"]
        direction TB
        Firebase["Firebase Backend"]
        AuthService["Auth Service"]
        Notify["Notification Service"]
        CloudFunc["Cloud Functions"]
    end
    
    DataLayer --> ExternalSystems
    
    %% Relationships & Data Flow
    AuthUI -- "Login/Signup" --> Providers
    OrderUI -- "Create Shift" --> Validation
    Validation --> Providers
    Providers -- "Update State" --> State
    State -- "Notify UI" --> PresentationLayer
    Repositories -- "Fetch Data" --> MockService
    Repositories -. "Future Connection" .-> Firebase
    
    classDef layer fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
    classDef module fill:#fff9c4,stroke:#fbc02d,stroke-width:1px,color:#000
    classDef system fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
    
    class PresentationLayer,LogicLayer,DataLayer layer
    class AuthUI,DashUI,OrderUI,WorkUI,ReportUI,AdminUI module
    class ExternalSystems system
```
