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

4
internal/launchpad/assets/documents/documents-config.json
View File

@@ -7,6 +7,10 @@
"title": "Architecture Document & Migration Plan", "title": "Architecture Document & Migration Plan",
"path": "./assets/documents/legacy/client-mobile-application/architecture.md" "path": "./assets/documents/legacy/client-mobile-application/architecture.md"
}, },
{
"title": "Architecture Document & Migration Plan",
"path": "./assets/documents/legacy/web-application/architecture.md"
},
{ {
"title": "Dataconnect guide", "title": "Dataconnect guide",
"path": "./assets/documents/dataconnect/backend_manual.md" "path": "./assets/documents/dataconnect/backend_manual.md"

305
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. ### A. Features (`lib/features/`)
* **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. These modules contain the specific business logic and UI for each distinct part of the application:
* **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.
### 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. ## 4. Component Responsibilities
* **Domain to Data:** The BLoCs in the domain layer call methods on the repositories in the data layer to fetch or update data. * **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.
* **Data to Backend:** The repositories in the data layer use the `ApiClient` to make GraphQL calls to the backend. * **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 ```mermaid
flowchart TD flowchart TD
subgraph "Client" %% Define Styles
A[Flutter App] 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 User_Device [Client Mobile App]
direction TB
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 end
subgraph "Backend" subgraph Core_Logic [Business Logic Layer]
B[GraphQL Server (e.g., Node.js)] direction TB
C[Firebase] BLoC[State Management BLoC]:::logic
Validation[Input Validation]:::logic
end end
subgraph "Firebase Services" subgraph Data_Layer [Data & Storage]
C1[Firebase Auth] direction TB
C2[Firebase Firestore] Repos[Repositories]:::data
C3[Firebase Storage] LocalDB[(Local Storage - Hive)]:::data
API_Client[GraphQL Client]:::data
end
end end
A -- "GraphQL Queries/Mutations" --> B subgraph External_Services [External Cloud Ecosystem]
A -- "Authentication" --> C1 direction TB
Krow_Backend[Krow Backend Server]:::external
Firebase[Firebase Auth & Config]:::external
Maps_NFC[Geolocation & NFC Services]:::external
end
B -- "Data Operations" --> C2 %% Connections
B -- "File Operations" --> C3 Auth --> BLoC
Hubs --> BLoC
Events --> BLoC
Staff --> BLoC
Finance --> BLoC
C1 -- "User Tokens" --> A BLoC --> Validation
C2 -- "Data" --> B BLoC <--> Repos
C3 -- "Files" --> B
B -- "Data/Files" --> A Repos <--> LocalDB
``` Repos <--> API_Client
### GraphQL API_Client <-->|GraphQL| Krow_Backend
Repos <-->|Auth & Config| Firebase
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. Repos <-->|Location & Scan| Maps_NFC
### 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]
end
subgraph "Mutations"
M1[createEvent]
M2[updateProfile]
M3[rateStaff]
M4[clockIn]
M5[clockOut]
M6[uploadProfilePicture]
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
end
Q1 --> FS1
Q2 --> FS1
Q3 --> FS2
Q4 --> FS2
Q5 --> FS3
Q6 --> FS3
Q7 --> FS4
Q8 --> FS1
Q8 --> FS4
M1 --> FS1
M2 --> FS4
M3 --> FS1
M3 --> FS4
M4 --> FS1
M5 --> FS1
M6 --> FB1
```
### API Handling
* **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
``` ```

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. ## 6. Architectural Patterns
- **Domain → Data:** The use case calls a method on a repository interface. The app adheres to **Clean Architecture** with **BLoC**, ensuring long-term maintainability.
- **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.
## 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:** ### B. Strict Compliance Checks (`check_list`)
- **Firebase Auth:** Used for user authentication, primarily with phone number verification. * **Decision:** Forcing a checklist flow before a shift can start.
- **Firebase Firestore:** The main database for storing application data, such as user profiles, shifts, and earnings. * **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.
- **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.
### 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. ## 8. Overview Diagram
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. ```mermaid
3. **Response Flow:** The data flows back from Firebase to the GraphQL server, which then sends it back to the Flutter app. 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. API_Client <-->|GraphQL| Krow_Backend
Repos <-->|Auth & Config| Firebase
- **State Flow:** Repos <-->|Location| Geo_Maps
1. **UI Event:** The UI dispatches an event to the Bloc. QR_NFC -.->|Scan| Hardware
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.

133
internal/launchpad/assets/documents/legacy/web-application/architecture.md Normal file
View File

@@ -0,0 +1,133 @@
# Application Overview: Krow Web Platform (Backend)
## 1. Executive Summary
The **Krow Web Platform** is the central "brain" and "command center" of the entire Krow ecosystem. While the mobile apps are the tools used in the field, this web application is the engine that powers them.
It serves two primary functions:
1. **The Engine:** It processes all data from the mobile apps—saving new events, finding available staff, handling payments, and verifying check-ins.
2. **The Control Tower (Admin Panel):** It provides a powerful website where Krow administrators can oversee the entire business, manage users, resolve disputes, and configure system-wide settings.
## 2. High-Level Architecture
The application follows a **Monolithic Web Architecture** using the **Laravel** framework. This is a battle-tested, robust structure ideal for building complex, data-heavy business platforms.
* **The API Server (The Voice):** It listens for requests from the mobile apps (using **GraphQL**). When a phone asks "Show me my shifts," this server understands the question, fetches the answer, and sends it back.
* **The Database (The Memory):** A centralized vault where all information (User profiles, Shift details, Invoices) is safely stored.
* **The Admin Interface (The Dashboard):** A secure website (built with **Laravel Nova**) that allows internal staff to view and edit this data directly without writing code.
## 3. Major Components & Modules
The system is divided into logical "domains" representing different parts of the business.
### A. Core Business Logic (`app/Models`, `app/Actions`)
* **Purpose:** The rules of the business.
* **Key Functions:** Defining what an "Event" is, how a "Shift" relates to a "Position," and ensuring that a Staff member cannot be in two places at once.
### B. API Layer (`app/GraphQL`)
* **Purpose:** The communication hub for mobile apps.
* **Key Functions:**
* **Client API:** specialized endpoints for business owners to create jobs.
* **Staff API:** specialized endpoints for workers to find jobs.
* **Authentication:** Verifying who is asking for data.
### C. Administration Panel (`app/Nova`)
* **Purpose:** Internal management tool.
* **Key Functions:**
* **User Management:** Approving new staff, verifying documents.
* **Content Management:** Managing skills lists, certificate types, and system tags.
* **Audit Logs:** Viewing history of who did what.
### D. Financial Engine (`app/Models/Payroll`, `app/Models/Invoice`)
* **Purpose:** Money management.
* **Key Functions:** Calculating staff pay based on hours worked, generating invoices for clients, and tracking payment status.
### E. Notification System (`app/Notifications`)
* **Purpose:** Keeping everyone in the loop.
* **Key Functions:** Sending emails, SMS, or push notifications when shifts are accepted, cancelled, or when payments are processed.
## 4. Component Responsibilities
* **Controllers/Resolvers:** These receive a request (e.g., "Create Shift"), validate it (e.g., "Is the date in the future?"), and pass it to the Logic layer.
* **Service Classes:** These perform specific complex tasks, like "Calculate total cost for this event including tax and service fees."
* **Eloquent Models:** These represent the data tables. The `Staff` model knows how to talk to the `staff` table in the database.
* **Nova Resources:** These define how data looks in the Admin Panel. A `StaffResource` defines that a staff member has a name, photo, and rating, and tells the admin panel how to display them.
## 5. External System Communication
* **Firebase:** Uses Firebase Authentication for secure user identity and Firebase Cloud Messaging for push notifications.
* **Database (MySQL/PostgreSQL):** The primary storage for all application data.
* **Storage (AWS S3 / DO Spaces):** Stores user uploaded files like profile photos and certificates.
* **Payment Gateway (Stripe/Similar):** (Implied) Handles the actual processing of credit card transactions and payouts.
* **Maps/Geolocation APIs:** Used to validate addresses and calculate distances between staff and venues.
## 6. Architectural Patterns
* **MVC (Model-View-Controller):** The traditional Laravel pattern, adapted here where "View" is mostly replaced by the GraphQL API or the Nova Admin panel.
* **Action-Based Domain Logic:** Complex business operations (like "Assign Staff to Shift") are often encapsulated in single "Action" classes rather than hidden inside massive models.
* **GraphQL Schema-First:** The API is defined by a typed schema (`.graphql` files), ensuring a strict contract between the frontend and backend.
## 7. Key Design Decisions & Impact
### A. GraphQL (Lighthouse)
* **Decision:** Using GraphQL instead of traditional REST API endpoints.
* **Why it matters:** Allows the mobile apps to be very efficient. They can ask for deep, related data (Event -> Shifts -> Staff -> Ratings) in a single network request, making the apps faster.
### B. Laravel Nova
* **Decision:** Using a pre-built administration package instead of building a custom admin panel from scratch.
* **Why it matters:** Drastically reduced development time. It provides a professional, secure, and feature-rich dashboard out of the box, allowing the team to focus on the unique app features.
### C. Role-Based Access Control (Spatie Permissions)
* **Decision:** Implementing a granular permission system.
* **Why it matters:** Security. It ensures that a "Client" can never see "Admin" data, and a "Staff" member can only see shifts relevant to them.
## 8. Overview Diagram
```mermaid
flowchart TD
%% Define Styles
classDef interface 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 Server_Application [Krow Web Platform]
direction TB
subgraph Interfaces [Access Layers]
direction TB
Admin_Panel[Admin Panel (Laravel Nova)]:::interface
GraphQL_API[GraphQL API (Lighthouse)]:::interface
end
subgraph Domain_Logic [Core Business Engine]
direction TB
Models[Data Models]:::logic
Actions[Business Actions & Rules]:::logic
Notifications[Notification System]:::logic
Payroll[Payroll & Invoicing Engine]:::logic
end
subgraph Data_Storage [Persistence Layer]
direction TB
MySQL[(Main Database)]:::data
Storage[File Storage (S3/DO Spaces)]:::data
end
end
subgraph External_World [External Ecosystem]
direction TB
Mobile_Apps[Mobile Apps (Client & Staff)]:::external
Firebase[Firebase (Auth & Push)]:::external
Maps_API[Maps & Geolocation]:::external
end
%% Connections
Mobile_Apps <-->|GraphQL Requests| GraphQL_API
Admin_Panel --> Actions
GraphQL_API --> Actions
Actions --> Models
Actions --> Payroll
Actions --> Notifications
Models <--> MySQL
Models <--> Storage
Notifications -->|Send Push/Email| Firebase
Actions -->|Validate Location| Maps_API
```