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

301
internal/launchpad/assets/documents/legacy/client-mobile-application/architecture.md
View File

@@ -1,220 +1,133 @@
# Krow Mobile Client App Architecture Document
# Application Overview: Krow Client Mobile App
## A. Introduction
## 1. Executive Summary
The **Krow Client App** is a mobile workforce management tool designed for business owners and managers. Think of it as a "control center" that allows businesses to easily hire, manage, and pay temporary staff for events or shifts.
This document provides a comprehensive overview of the Krow mobile client application's architecture. The Krow app is a Flutter-based mobile application designed to connect staff with work opportunities. It includes features for event management, invoicing, staff rating, and profile management.
Instead of calling agencies or managing spreadsheets, a business user opens this app to:
* Define a job (Event/Shift).
* Request specific roles (e.g., Waiter, Security).
* Monitor staff check-ins and attendance.
* Rate staff performance.
* Handle payments and invoices.
The core purpose of the app is to provide a seamless experience for staff to find, manage, and get paid for work, while allowing clients to manage their events and staff effectively.
## 2. High-Level Architecture
The application follows a **Modern Mobile Architecture** designed for reliability and speed. It acts as a "smart interface" that connects the user to the central Krow platform.
## B. Full Architecture Overview
* **The Frontend (This App):** Handles everything the user sees and touches. It validates inputs (like ensuring a shift end time is after the start time) and displays data beautifully.
* **The Bridge (API Layer):** The app talks to the Krow Cloud Server using **GraphQL**. This allows the app to ask for exactly the data it needs—no more, no less—making it fast even on slower connections.
* **The Backend (The Brain):** All heavy processing (matching staff to jobs, processing payments) happens on the secure server, not on the phone.
The Krow app is built using a layered architecture that separates concerns and promotes modularity. The main layers are the **Presentation Layer**, the **Domain Layer**, and the **Data Layer**, organized into feature-based modules.
## 3. Major Components & Modules
### Key Modules and Layers
The application codebase is structured into two main directories: **Features** (Business Capabilities) and **Core** (Shared Utilities & Foundations).
* **Features:** The `lib/features` directory contains the main features of the app, such as `sign_in`, `events`, `profile`, etc. Each feature directory is further divided into `presentation` and `domain` layers.
* **Presentation Layer:** This layer is responsible for the UI and user interaction. It contains the screens (widgets) and the BLoCs (Business Logic Components) that manage the state of the UI.
* **Domain Layer:** This layer contains the core business logic of the application. It includes the BLoCs, which are responsible for orchestrating the flow of data between the UI and the data layer, and the business objects (entities).
* **Data Layer:** This layer is responsible for all data-related operations. It includes the repositories that fetch data from the backend and the data sources themselves (e.g., GraphQL API, local cache).
* **Core:** The `lib/core` directory contains shared code that is used across multiple features, such as the API client, dependency injection setup, routing, and common widgets.
### A. Features (`lib/features/`)
These modules contain the specific business logic and UI for each distinct part of the application:
### Integration Points
* **assigned_staff_screen**: Manages the view where clients can see staff members assigned to their shifts.
* **clock_manual**: Handles the functionality for manually logging staff work hours (Clock-In/Clock-Out) if automated methods fail or are not used.
* **create_event**: The workflow and forms for creating new events and defining shift requirements.
* **events**: The dashboard and list views for managing existing events (upcoming, active, and past).
* **home**: The main landing screen after login, providing a summary and quick access to key actions.
* **hubs**: Manages the creation and configuration of "Hubs" (locations) and "Departments".
* **invoice**: Handles the display and management of billing, invoices, and payment history.
* **notificatins**: Manages the in-app notification center (alerts, updates, and messages).
* **profile**: User settings, personal information, and business profile management.
* **rate_staff**: The interface for clients to provide ratings and feedback on staff performance after a shift.
* **sign_in**: Handles the authentication flow, including login screens and credential validation.
* **splash**: The initial launch screen that handles app initialization and auth checks.
* **UI to Domain:** The UI (widgets) dispatches events to the BLoCs in the domain layer based on user interactions.
* **Domain to Data:** The BLoCs in the domain layer call methods on the repositories in the data layer to fetch or update data.
* **Data to Backend:** The repositories in the data layer use the `ApiClient` to make GraphQL calls to the backend.
## 4. Component Responsibilities
* **User Interface (UI):** The "Face" of the app. It displays buttons, lists, and forms. It is "dumb" in that it doesn't make decisions; it just shows what it's told.
* **State Management (BLoC):** The "Brain" of the app. When a user taps "Create Event," this component checks if the form is valid, formats the data, and decides what loading spinner to show.
* **Data Repository:** The "Librarian." It decides where to get information. Does the app already have the list of staff saved on the phone? Or does it need to fetch a fresh list from the server?
## C. Backend Architecture
## 5. External System Communication
The app does not live in isolation; it talks to several outside services:
The backend of the Krow app is a hybrid system that leverages both a **GraphQL server** and **Firebase services**.
* **The Krow Backend (GraphQL):** The primary source of truth for all data (Events, Staff profiles, Shifts).
* **Firebase Auth:** Handles secure login (passwords, email verification) so the Krow team doesn't have to build security from scratch.
* **Firebase Remote Config:** Allows the Krow team to change app settings (like feature flags or text) without forcing users to update the app.
* **NFC Services:** Interacts with physical NFC tags, likely for scanning staff badges or verifying presence at a location.
* **Geolocation Services:** Uses the phone's GPS to verify that actions (like creating a hub) are happening at the correct physical address.
## 6. Architectural Patterns
The app uses a **Feature-First, Clean Architecture** approach combined with **BLoC (Business Logic Component)**.
* **Feature-First:** The code is organized by *business capability* (e.g., "Invoices", "Events") rather than technical type. This means if we need to change how Invoices work, we go to the "Invoice" folder, and everything is there.
* **Clean Architecture:** The app is built in layers like an onion. The inner layers (Business Logic) don't know anything about the outer layers (UI). This makes the app highly testable and stable.
* **BLoC:** This pattern strictly separates "Events" (user clicks) from "States" (what the screen shows). It ensures that a glitch in the UI doesn't crash the business logic.
## 7. Key Design Decisions & Impact
### A. GraphQL over REST
* **Decision:** The app asks for specific data trees (e.g., "Give me Event X, its Shifts, and only the Names of assigned staff").
* **Why it matters:** This reduces data usage and loading times. The app doesn't download unnecessary info, making it feel snappier.
### B. Offline Capability (Hive)
* **Decision:** The app uses a local database (`hive`) to store some data on the phone.
* **Why it matters:** If the manager loses internet briefly, the app doesn't go blank. It can show cached data until the connection is restored.
### C. Dependency Injection (`injectable`)
* **Decision:** The app uses a system to "plug in" different tools automatically.
* **Why it matters:** It makes the app easy to update. If we want to swap the Geolocation provider, we change it in one place, and the whole app updates automatically.
## 8. Overview Diagram
```mermaid
flowchart TD
subgraph "Client"
A[Flutter App]
end
%% 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
subgraph "Backend"
B[GraphQL Server (e.g., Node.js)]
C[Firebase]
end
subgraph User_Device [Client Mobile App]
direction TB
subgraph "Firebase Services"
C1[Firebase Auth]
C2[Firebase Firestore]
C3[Firebase Storage]
end
A -- "GraphQL Queries/Mutations" --> B
A -- "Authentication" --> C1
B -- "Data Operations" --> C2
B -- "File Operations" --> C3
C1 -- "User Tokens" --> A
C2 -- "Data" --> B
C3 -- "Files" --> B
B -- "Data/Files" --> A
```
### GraphQL
The GraphQL server acts as an intermediary between the Flutter app and the Firebase services. It exposes a set of queries and mutations that the app can use to interact with the backend. This provides a single, unified API for the app to consume, simplifying data fetching and manipulation.
### Firebase Integration
* **Firebase Auth:** Firebase Auth is used for user authentication. The Flutter app interacts directly with Firebase Auth to handle user sign-in, sign-up, and password reset flows. Once authenticated, the app retrieves a Firebase ID token, which is then used to authenticate with the GraphQL server.
* **Firebase Firestore:** Firestore is the primary database for the application. The GraphQL server is responsible for all interactions with Firestore, including fetching, creating, updating, and deleting data.
* **Firebase Storage:** Firebase Storage is used for storing user-generated content, such as profile pictures. The GraphQL server handles file uploads and retrieves file URLs that are then sent to the app.
### End-to-End Communication Flow
1. The Flutter app authenticates the user with Firebase Auth.
2. The app receives a Firebase ID token.
3. For all subsequent API requests, the app sends the Firebase ID token in the authorization header of the GraphQL request.
4. The GraphQL server verifies the token and then executes the requested query or mutation.
5. The GraphQL server interacts with Firestore or Firebase Storage to fulfill the request.
6. The GraphQL server returns the requested data to the app.
## D. API Layer
The API layer is responsible for all communication with the backend. It is built around the `graphql_flutter` package and a custom `ApiClient`.
```mermaid
flowchart TD
subgraph "GraphQL API"
direction LR
subgraph "Queries"
Q1[getEvents]
Q2[getEventDetails]
Q3[getInvoices]
Q4[getInvoiceDetails]
Q5[getNotifications]
Q6[getNotificationDetails]
Q7[getProfile]
Q8[getAssignedStaff]
subgraph Features [Feature Modules]
direction TB
Auth[Sign In & Profile]:::frontend
Hubs[Hubs & Business Mgmt]:::frontend
Events[Event & Shift Mgmt]:::frontend
Staff[Staff Interaction & Rating]:::frontend
Finance[Invoices & Payments]:::frontend
end
subgraph "Mutations"
M1[createEvent]
M2[updateProfile]
M3[rateStaff]
M4[clockIn]
M5[clockOut]
M6[uploadProfilePicture]
subgraph Core_Logic [Business Logic Layer]
direction TB
BLoC[State Management BLoC]:::logic
Validation[Input Validation]:::logic
end
subgraph Data_Layer [Data & Storage]
direction TB
Repos[Repositories]:::data
LocalDB[(Local Storage - Hive)]:::data
API_Client[GraphQL Client]:::data
end
end
subgraph "Firebase"
direction LR
subgraph "Firestore Collections"
FS1[events]
FS2[invoices]
FS3[notifications]
FS4[users]
end
subgraph "Firebase Storage"
FB1[Profile Pictures]
end
subgraph External_Services [External Cloud Ecosystem]
direction TB
Krow_Backend[Krow Backend Server]:::external
Firebase[Firebase Auth & Config]:::external
Maps_NFC[Geolocation & NFC Services]:::external
end
Q1 --> FS1
Q2 --> FS1
Q3 --> FS2
Q4 --> FS2
Q5 --> FS3
Q6 --> FS3
Q7 --> FS4
Q8 --> FS1
Q8 --> FS4
%% Connections
Auth --> BLoC
Hubs --> BLoC
Events --> BLoC
Staff --> BLoC
Finance --> BLoC
M1 --> FS1
M2 --> FS4
M3 --> FS1
M3 --> FS4
M4 --> FS1
M5 --> FS1
M6 --> FB1
```
BLoC --> Validation
BLoC <--> Repos
### API Handling
Repos <--> LocalDB
Repos <--> API_Client
* **Error Handling:** The `ApiClient` uses the `ErrorPolicy.all` policy to catch all GraphQL errors. The BLoCs are responsible for catching these errors and updating the UI state accordingly.
* **Caching:** The `GraphQLCache` with `HiveStore` is used to cache GraphQL query results. The `fetchPolicy` is set to `cacheAndNetwork` to provide a fast user experience while keeping the data up-to-date.
* **Parsing:** The app uses the `json_serializable` package to parse the JSON responses from the GraphQL server into Dart objects.
## E. State Management
The Krow app uses the **BLoC (Business Logic Component)** pattern for state management, powered by the `flutter_bloc` package.
### Why BLoC?
* **Separation of Concerns:** BLoC separates the business logic from the UI, making the code more organized, testable, and maintainable.
* **Testability:** BLoCs are easy to test in isolation from the UI.
* **Reactivity:** BLoC uses streams to manage state, which makes it easy to update the UI in response to state changes.
### State Flow
1. The UI dispatches an event to the BLoC.
2. The BLoC receives the event and interacts with the data layer (repositories) to fetch or update data.
3. The data layer returns data or a success/failure status to the BLoC.
4. The BLoC updates its state based on the result from the data layer.
5. The UI rebuilds itself in response to the new state.
### Integration with the API Layer
The BLoCs do not interact directly with the `ApiClient`. Instead, they go through a repository layer, which abstracts the data source. This makes it possible to switch out the backend without having to change the BLoCs.
## F. Use-Case Flows
The following diagrams illustrate the flow for some of the major use cases in the app.
```mermaid
flowchart TD
subgraph "Sign-In Flow"
A1[User enters credentials] --> B1{SignInBloc};
B1 --> C1[Firebase Auth: signInWithEmailAndPassword];
C1 -- Success --> D1[Navigate to Home];
C1 -- Failure --> E1[Show error message];
end
subgraph "Password Reset Flow"
A2[User requests password reset] --> B2{SignInBloc};
B2 --> C2[Firebase Auth: sendPasswordResetEmail];
C2 -- Email Sent --> D2[User clicks deep link];
D2 --> E2[UI with new password fields];
E2 --> F2{SignInBloc};
F2 --> G2[Firebase Auth: confirmPasswordReset];
G2 -- Success --> H2[Show success message];
G2 -- Failure --> I2[Show error message];
end
subgraph "Event Listing Flow"
A3[User navigates to Events screen] --> B3{EventsBloc};
B3 --> C3[GraphQL Query: getEvents];
C3 --> D3[Firestore: events collection];
D3 -- Returns event data --> C3;
C3 -- Returns data --> B3;
B3 --> E3[Display list of events];
end
subgraph "Create Event Flow"
A4[User submits new event form] --> B4{CreateEventBloc};
B4 --> C4[GraphQL Mutation: createEvent];
C4 --> D4[Firestore: events collection];
D4 -- Success --> C4;
C4 -- Returns success --> B4;
B4 --> E4[Navigate to event details];
end
subgraph "Profile Viewing Flow"
A5[User navigates to Profile screen] --> B5{ProfileBloc};
B5 --> C5[GraphQL Query: getProfile];
C5 --> D5[Firestore: users collection];
D5 -- Returns profile data --> C5;
C5 -- Returns data --> B5;
B5 --> E5[Display profile information];
end
```
API_Client <-->|GraphQL| Krow_Backend
Repos <-->|Auth & Config| Firebase
Repos <-->|Location & Scan| Maps_NFC
```