Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: update architecture documents for client and staff mobile apps, and add web platform overview

Browse Source
This commit is contained in:
Achintha Isuru
2026-02-06 14:55:28 -05:00
parent 964b872ee1
commit 4e952f5529
4 changed files with 353 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
internal/launchpad/assets/documents/legacy/staff-mobile-application/architecture.md
View File

@@ -1,87 +1,134 @@
# Krow Mobile Staff App - Architecture Document
# Application Overview: Krow Staff Mobile App
## A. Introduction
## 1. Executive Summary
The **Krow Staff App** is the mobile companion for the workforce—the people picking up shifts and performing the work. It operates as a "gig economy" platform where individuals can find flexible work, manage their schedule, and track their income.
This document outlines the architecture of the Krow Mobile Staff App, a Flutter application designed to connect staff with job opportunities. The app provides features for staff to manage their profiles, view and apply for shifts, track earnings, and complete necessary paperwork.
For a staff member (e.g., a waiter, chef, or event security), this app is their digital office. They use it to:
* Browse and apply for available shifts in their area.
* Manage their professional profile (skills, certificates, experience).
* Complete pre-shift compliance checks (uniform, equipment).
* Check in and out of job sites (using QR codes or NFC).
* Track their earnings and payment history.
The core purpose of the app is to streamline the process of finding and managing temporary work, providing a seamless experience for staff from onboarding to payment.
## 2. High-Level Architecture
Like the Client App, this application is built on a **Modern Mobile Architecture** that prioritizes offline resilience and real-time accuracy.
## B. Full Architecture Overview
* **The Frontend (The App):** A polished, user-friendly interface that guides staff through complex workflows (like onboarding or shift execution) simply.
* **The Bridge (API Layer):** Communicates with the Krow Cloud via **GraphQL**, allowing the app to fetch personalized job feeds and update work status efficiently.
* **The Backend (The Engine):** Manages the "marketplace" logic—matching staff skills to event requirements, calculating pay rates, and processing compliance rules.
The application follows a **Clean Architecture** pattern, separating concerns into three main layers: **Presentation**, **Domain**, and **Data**. This layered approach promotes a separation of concerns, making the codebase more maintainable, scalable, and testable.
## 3. Major Components & Modules
The app is structured into "Features" (functional areas) and "Core" (shared tools), ensuring a clean separation of concerns.
- **Presentation Layer:** This layer is responsible for the UI and user interaction. It consists of widgets, screens, and Blocs that manage the UI state. The Presentation Layer depends on the Domain Layer to execute business logic.
### A. Features (`lib/features/`)
These modules handle the specific tasks a staff member needs to perform:
- **Domain Layer:** This layer contains the core business logic of the application. It consists of use cases (interactors), entities (business objects), and repository interfaces. The Domain Layer is independent of the other layers.
* **auth**: Handles existing user login, ensuring secure access to personal data.
* **check_list**: A compliance tool that ensures staff are "job-ready." It likely includes steps for verifying uniform, equipment, or health and safety requirements before a shift begins.
* **earning**: The financial dashboard where staff can see their total earnings, payment history, and details for specific pay periods.
* **home**: The main landing page, likely summarizing upcoming shifts, active jobs, and quick actions.
* **profile**: Manages the user's professional identity, including their skills, certificates, bio, and account settings.
* **qr_scanner**: A critical operational tool used for "Clocking In" and "Clocking Out" at the venue, providing digital proof of presence.
* **shifts**: The core marketplace and schedule manager. It allows staff to:
* **Browse:** See available shifts ("Open Jobs").
* **Manage:** View accepted shifts ("My Schedule").
* **Execute:** See details for the current shift (address, contacts).
* **sign_up**: A dedicated onboarding flow for new users, guiding them through registration, profile creation, and initial verification.
* **splash**: The app's entry point, handling initialization, updates, and authentication checks.
* **support**: Provides access to help resources or direct support channels for resolving issues.
- **Data Layer:** This layer is responsible for data retrieval and storage. It consists of repository implementations, data sources (API clients, local database), and data transfer objects (DTOs). The Data Layer depends on the Domain Layer and implements the repository interfaces defined in it.
## 4. Component Responsibilities
* **User Interface (UI):** Focused on clarity and speed. It presents job opportunities attractively and makes the "Clock-In" process frictionless.
* **State Management (BLoC):** Handles the logic of the app. For example, when a user scans a QR code, the BLoC validates the scan, sends the timestamp to the server, and updates the UI to "Shift Started" mode.
* **Data Repository:** intelligent data handling. It knows when to fetch new jobs from the internet and when to show the saved schedule from the local database (crucial for venues with poor reception).
### Integration Points
## 5. External System Communication
* **The Krow Backend (GraphQL):** The central authority for job listings, user profiles, and time/attendance records.
* **Firebase Auth:** Secure identity management for login and signup.
* **Firebase Remote Config:** Allows dynamic updates to app behavior (e.g., maintenance mode messages).
* **Geolocation & Maps:** Verifies that the staff member is physically at the venue when clocking in and provides directions to the job site.
* **Camera/NFC:** Hardware access for scanning QR codes or interacting with NFC tags for check-ins.
- **UI → Domain:** The UI (e.g., a button press) triggers a method in a Bloc. The Bloc then calls a use case in the Domain Layer to execute the business logic.
- **Domain → Data:** The use case calls a method on a repository interface.
- **Data → External:** The repository implementation, located in the Data Layer, communicates with external data sources (GraphQL API, Firebase, local storage) to retrieve or store data.
## 6. Architectural Patterns
The app adheres to **Clean Architecture** with **BLoC**, ensuring long-term maintainability.
## C. Backend Architecture
* **Separation of Concerns:** The code that draws the "Accept Shift" button is completely separate from the code that sends the "Accept" message to the internet.
* **Reactive UI:** The interface automatically reacts to changes in state (e.g., a new job appearing) without manual refreshing.
The backend is built on a combination of a **GraphQL server** and **Firebase services**.
## 7. Key Design Decisions & Impact
- **GraphQL Server:** The primary endpoint for the Flutter app. It handles most of the business logic and data aggregation. The server is responsible for communicating with Firebase services to fulfill requests.
### A. Offline-First Approach
* **Decision:** Critical data (like "My Schedule") is cached locally.
* **Why it matters:** Event venues often have bad signal (basements, remote fields). Staff must still be able to see where they need to be and valid their start time even if the internet drops.
- **Firebase Services:**
- **Firebase Auth:** Used for user authentication, primarily with phone number verification.
- **Firebase Firestore:** The main database for storing application data, such as user profiles, shifts, and earnings.
- **Firebase Storage:** Used for storing user-generated content, such as profile avatars.
- **Firebase Cloud Messaging:** Used for sending push notifications to users.
- **Firebase Remote Config:** Used for remotely configuring app parameters.
### B. Strict Compliance Checks (`check_list`)
* **Decision:** Forcing a checklist flow before a shift can start.
* **Why it matters:** Ensures quality control for the business client. The app acts as a remote manager, ensuring the staff member confirms they have their uniform before they walk in the door.
### API Flow
### C. Feature-Based Folder Structure
* **Decision:** Grouping files by `feature` (e.g., `earning`, `shifts`) rather than by type (e.g., `screens`, `controllers`).
* **Why it matters:** Makes the codebase easy to navigate for new developers. If there is a bug with payments, you go straight to the `earning` folder.
1. **Flutter App to GraphQL:** The Flutter app sends GraphQL queries and mutations to the GraphQL server.
2. **GraphQL to Firebase:** The GraphQL server resolves these operations by interacting with Firebase services. For example, a `getShifts` query will fetch data from Firestore, and an `updateStaffPersonalInfoWithAvatar` mutation will update a document in Firestore and upload a file to Firebase Storage.
3. **Response Flow:** The data flows back from Firebase to the GraphQL server, which then sends it back to the Flutter app.
## 8. Overview Diagram
```mermaid
flowchart TD
%% Define Styles
classDef frontend fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1
classDef logic fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#bf360c
classDef data fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
## D. API Layer
subgraph User_Device [Staff Mobile App]
direction TB
The API layer is responsible for all communication with the backend.
subgraph Features [Feature Modules]
direction TB
Auth[Auth & Sign Up]:::frontend
Shifts[Shift Marketplace & Schedule]:::frontend
CheckList[Compliance & Uniform Checks]:::frontend
QR_NFC[QR Scanner & Clock-In]:::frontend
Earnings[Earnings & History]:::frontend
Profile[Profile & Skills]:::frontend
end
- **GraphQL Operations:** The app uses the `graphql_flutter` package to interact with the GraphQL server. Queries, mutations, and subscriptions are defined in `.dart` files within each feature's `data` directory.
subgraph Core_Logic [Business Logic Layer]
direction TB
BLoC[State Management BLoC]:::logic
Validation[Rules Engine]:::logic
end
- **API Error Handling:** The `ApiClient` class is responsible for handling API errors. It catches exceptions and returns a `Failure` object, which is then handled by the Bloc in the Presentation Layer to show an appropriate error message to the user.
subgraph Data_Layer [Data & Storage]
direction TB
Repos[Repositories]:::data
LocalDB[(Local Storage - Hive)]:::data
API_Client[GraphQL Client]:::data
end
end
- **Caching:** The `graphql_flutter` client provides caching capabilities. The app uses a `HiveStore` to cache GraphQL responses, reducing the number of network requests and improving performance.
subgraph External_Services [External Cloud Ecosystem]
direction TB
Krow_Backend[Krow Backend Server]:::external
Firebase[Firebase Auth & Config]:::external
Geo_Maps[Geolocation & Maps]:::external
Hardware[Camera & NFC Hardware]:::external
end
- **Parsing:** JSON responses from the API are parsed into Dart objects using the `json_serializable` package.
%% Connections
Auth --> BLoC
Shifts --> BLoC
CheckList --> BLoC
QR_NFC --> BLoC
Earnings --> BLoC
Profile --> BLoC
## E. State Management
BLoC --> Validation
BLoC <--> Repos
The application uses the **Bloc** library for state management.
Repos <--> LocalDB
Repos <--> API_Client
- **Why Bloc?** Bloc is a predictable state management library that helps to separate business logic from the UI. It enforces a unidirectional data flow, making the app's state changes predictable and easier to debug.
- **State Flow:**
1. **UI Event:** The UI dispatches an event to the Bloc.
2. **Bloc Logic:** The Bloc receives the event, executes the necessary business logic (often by calling a use case), and emits a new state.
3. **UI Update:** The UI listens to the Bloc's state changes and rebuilds itself to reflect the new state.
- **Integration with API Layer:** Blocs interact with the API layer through use cases. When a Bloc needs to fetch data from the backend, it calls a use case, which in turn calls a repository that communicates with the API.
## F. Use-Case Flows
### User Authentication
1. **UI:** The user enters their phone number.
2. **Logic:** The `AuthBloc` sends the phone number to Firebase Auth for verification.
3. **Backend:** Firebase Auth sends a verification code to the user's phone.
4. **UI:** The user enters the verification code.
5. **Logic:** The `AuthBloc` verifies the code with Firebase Auth.
6. **Backend:** Firebase Auth returns an auth token.
7. **Logic:** The app sends the auth token to the GraphQL server to get the user's profile.
8. **Response:** The GraphQL server returns the user's data, and the app navigates to the home screen.
### Shift Management
1. **UI:** The user navigates to the shifts screen.
2. **Logic:** The `ShiftsBloc` requests a list of shifts.
3. **Backend:** The use case calls the `ShiftsRepository`, which sends a `getShifts` query to the GraphQL server. The server fetches the shifts from Firestore.
4. **Response:** The GraphQL server returns the list of shifts, which is then displayed on the UI.
API_Client <-->|GraphQL| Krow_Backend
Repos <-->|Auth & Config| Firebase
Repos <-->|Location| Geo_Maps
QR_NFC -.->|Scan| Hardware
```