Add comprehensive architecture, use case, and system documentation for Krow platform
- Introduced architecture overview for the Staff Mobile Application, detailing its high-level structure, major components, and data flow. - Created use case documentation for the Staff Mobile Application, outlining user interactions and workflows. - Developed a system bible for the Krow Platform, covering system vision, architecture, use cases, and security models. - Added architecture overview for the Krow Web Application, including its component structure and external system interactions. - Documented use cases for the Krow Web Application, detailing workflows for different user roles and shared functional modules.
This commit is contained in:
Achintha Isuru
235
internal/launchpad/assets/documents/legacy/system-bible.md
Normal file
235
internal/launchpad/assets/documents/legacy/system-bible.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# Krow Legacy Ecosystem: System Bible
|
||||
|
||||
**Status:** Official System Constitution
|
||||
**Version:** 1.0.0
|
||||
**Date:** 2026-02-06
|
||||
**Scope:** Krow Legacy Ecosystem (Client App, Staff App, Web Platform)
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
The **Krow Legacy Ecosystem** is a comprehensive digital marketplace designed to revolutionize the temporary staffing industry. It eliminates the friction of traditional agencies by directly connecting **businesses** (restaurants, event organizers) with **temporary workers** (wait staff, security, chefs) through a unified, automated platform.
|
||||
|
||||
**Why It Exists:**
|
||||
The traditional staffing model is slow, opaque, and manual (spreadsheets, phone calls). This ecosystem digitizes the entire lifecycle—from finding staff and verifying their skills to tracking attendance and processing payments—creating a transparent, efficient market for flexible work.
|
||||
|
||||
**Who It Serves:**
|
||||
1. **Business Owners ("Clients"):** Who need on-demand, vetted staff without the administrative burden.
|
||||
2. **Workers ("Staff"):** Who seek flexible shifts, instant access to job opportunities, and reliable payment.
|
||||
3. **Operations Teams:** Who manage the marketplace, ensuring quality, compliance, and dispute resolution.
|
||||
|
||||
**Value Proposition:**
|
||||
"A trusted, transparent, and real-time workforce marketplace where businesses get reliability and workers get flexibility, powered by a single source of truth."
|
||||
|
||||
---
|
||||
|
||||
## 2. System Vision & Product Principles
|
||||
|
||||
### Core Goals
|
||||
1. **Frictionless Connection:** Reduce the time to fill a shift from days to minutes.
|
||||
2. **Trust through Transparency:** Both sides (Client and Staff) must have total visibility into profiles, ratings, and attendance.
|
||||
3. **Operational Excellence:** Automate low-value tasks (invoicing, timesheets) so humans can focus on high-value tasks (quality assurance, service).
|
||||
|
||||
### Product Principles
|
||||
* **Mobile-First for Users:** The primary interaction point for Clients and Staff is their phone. The experience must be fast, intuitive, and resilient to poor network conditions.
|
||||
* **Centralized Truth:** Business logic lives on the Server, not the Client. Mobile apps are "smart viewers" but never the final authority.
|
||||
* **Compliance is Mandatory:** The system must strictly enforce legal and operational requirements (e.g., "No uniform, no work").
|
||||
* **Offline Resilience:** Staff must be able to perform critical actions (Clock In/Out) even in basements or fields with no signal.
|
||||
|
||||
### What We Solve vs. What We Don't
|
||||
* **WE SOLVE:** Shift discovery, booking, attendance verification, invoicing, and payout calculation.
|
||||
* **WE DO NOT SOLVE:** Direct employment contracts (staff are independent contractors or agency employees), specialized tax advice, or instant banking transfers (we facilitate, we don't hold funds).
|
||||
|
||||
---
|
||||
|
||||
## 3. Ecosystem Overview
|
||||
|
||||
The ecosystem is composed of three distinct applications that function as a single organic unit.
|
||||
|
||||
| Application | Name | Primary User | Platform | Core Responsibility |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **1. Client App** | `pineDev_krow-mobile-client-app` | Business Owners | Mobile (Flutter) | **Demand Generation.** Posting shifts, managing venues, verifying staff presence. |
|
||||
| **2. Staff App** | `pineDev_krow-mobile-staff-app` | Temporary Workers | Mobile (Flutter) | **Supply Fulfilment.** Finding work, proving compliance, executing shifts. |
|
||||
| **3. Web Platform** | `pineDev_legendary-web-app` | Admin / System | Web (Laravel) | **The Brain.** Marketplace orchestration, data storage, financial processing, admin control. |
|
||||
|
||||
**Conceptual Fit:**
|
||||
Imagine a ride-sharing service. The **Client App** is the passenger requesting a ride. The **Staff App** is the driver accepting the ride. The **Web Platform** is the dispatch center managing the map, prices, and safety.
|
||||
|
||||
---
|
||||
|
||||
## 4. System Architecture Overview
|
||||
|
||||
The system follows a **Hub-and-Spoke** architecture. The Web Platform is the central Hub; the mobile applications are the Spokes.
|
||||
|
||||
### Architecture Style
|
||||
* **Monolithic Backend / Smart Mobile Clients:** We utilize a robust, monolithic backend (Laravel) to ensure data integrity and simplified deployment, coupled with rich mobile clients (Flutter) that handle UI/UX complexity.
|
||||
* **GraphQL Communication:** All apps communicate via a strictly typed GraphQL API. This decoupling allows mobile apps to evolve their UI without constantly requiring backend changes.
|
||||
|
||||
### System Boundaries
|
||||
* **Network Boundary:** The Mobile Apps communicate over the public internet to the Web Platform's API Gateway.
|
||||
* **Security Boundary:** Authentication (Firebase) happens at the edge. No request passes to the core logic without a valid identity token.
|
||||
* **Data Boundary:** Mobile apps cache data but own nothing. The Database behind the Web Platform is the only permanent record.
|
||||
|
||||
### Architecture Diagram
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
%% 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 App<br/>(Business)"]:::clientApp
|
||||
StaffApp["Staff App<br/>(Workers)"]:::staffApp
|
||||
end
|
||||
|
||||
subgraph Core_Platform["Krow Web Platform"]
|
||||
direction TB
|
||||
AdminPanel["Admin Dashboard<br/>(Laravel Nova)"]:::backend
|
||||
APIServer["GraphQL API<br/>(Laravel Lighthouse)"]:::backend
|
||||
Database[("Central Database<br/>(PostgreSQL)")]:::db
|
||||
end
|
||||
|
||||
subgraph External_Services["Cloud Services"]
|
||||
direction TB
|
||||
Firebase["Firebase<br/>(Auth/Push)"]:::external
|
||||
Maps["Google Maps<br/>(Location)"]:::external
|
||||
end
|
||||
|
||||
%% Communication Flows
|
||||
ClientApp <-->|GraphQL| APIServer
|
||||
StaffApp <-->|GraphQL| APIServer
|
||||
AdminPanel <-->|Internal| APIServer
|
||||
APIServer <-->|SQL| Database
|
||||
Mobile_Apps -.->|Auth| Firebase
|
||||
Mobile_Apps -.->|Location| Maps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Application Responsibility Matrix
|
||||
|
||||
This matrix prevents "logic creep" where business rules accidentally migrate into the mobile apps.
|
||||
|
||||
| Feature Domain | Client App | Staff App | Web Platform (Backend) |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **User Accounts** | Sign In / Profile Edit | Sign In / Profile Edit | **MASTER RECORD.** Validation, Ban/Approve. |
|
||||
| **Events/Shifts** | **CREATE / EDIT.** Define needs. | **READ / ACCEPT.** Browse & Book. | **VALIDATE.** Ensure availability, match skills. |
|
||||
| **Staff Selection** | View assigned staff. | N/A | Match algorithms, Notification triggers. |
|
||||
| **Attendance** | View status, Manual Override. | **EXECUTE.** QR Scan / Check-in. | **VERIFY.** Validate Time & Geolocation. |
|
||||
| **Payments** | View Invoices, Pay. | View Earnings. | **CALCULATE.** Rates * Hours + Tax + Fees. |
|
||||
| **Notifications** | Receive alerts. | Receive alerts. | **DISPATCH.** Decide who gets alerted and when. |
|
||||
| **Compliance** | N/A | Upload Docs, Complete Checklists. | **AUDIT.** Verify docs, enforce expiry rules. |
|
||||
|
||||
**Crucial Rule:** Mobile Apps **DISPLAY** and **REQUEST**. The Web Platform **DECIDES** and **COMMITS**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Use Cases (Core Canon)
|
||||
|
||||
These are the officially recognized system workflows.
|
||||
|
||||
### Group A: Onboarding & Identity
|
||||
* **UC-01: Staff Registration & Verification** (Staff App -> Web Platform)
|
||||
* Staff signs up, uploads docs. Web Platform holds status as "Pending" until Admin approves.
|
||||
* **UC-02: Client Business Setup** (Client App -> Web Platform)
|
||||
* Client creates account, defines venues (Hubs). Web Platform validates addresses via Maps.
|
||||
|
||||
### Group B: The Marketplace Loop
|
||||
* **UC-03: Shift Creation** (Client App -> Web Platform)
|
||||
* Client defines role, time, rate. Web Platform publishes to eligible staff.
|
||||
* **UC-04: Shift Discovery & Booking** (Staff App -> Web Platform)
|
||||
* Staff sees job, accepts it. Web Platform locks the slot and confirms booking.
|
||||
|
||||
### Group C: Operational Execution
|
||||
* **UC-05: Pre-Shift Compliance** (Staff App -> Web Platform)
|
||||
* Staff confirms uniform/tools. App blocks clock-in until done.
|
||||
* **UC-06: Attendance (Clock In/Out)** (Staff App -> Client App -> Web Platform)
|
||||
* Staff scans Client QR. Platform records timestamp & location. Updates Client view instantly.
|
||||
* **UC-07: Live Monitoring** (Client App -> Web Platform)
|
||||
* Client sees who is on-site, late, or missing.
|
||||
|
||||
### Group D: Finance & Closeout
|
||||
* **UC-08: Ratings & Feedback** (Client App -> Web Platform)
|
||||
* Client rates staff performance. Platform updates Staff reputation score.
|
||||
* **UC-09: Payroll Calculation** (Web Platform Internal)
|
||||
* System calculates final pay based on verified hours.
|
||||
* **UC-10: Invoicing** (Web Platform -> Client App)
|
||||
* System generates PDF invoice. Client views/downloads in app.
|
||||
|
||||
---
|
||||
|
||||
## 7. Cross-Application Interaction Rules
|
||||
|
||||
1. **No Direct P2P:** The Client App and Staff App **NEVER** talk directly to each other. They communicate exclusively through the Web Platform.
|
||||
* *Why?* Security and audit trails.
|
||||
2. **QR/NFC Exception:** The only "direct" interaction is the physical scanning of a QR code or NFC tag. This creates a data packet sent to the server, not a direct network connection between phones.
|
||||
3. **Push, Don't Poll:** Apps should not constantly ask "Is there an update?". The Platform sends Push Notifications to trigger a data refresh.
|
||||
4. **Graceful Degradation:** If the Web Platform is unreachable, mobile apps must allow read-only access to cached data (e.g., "My Schedule") but disable write actions (e.g., "Accept Shift").
|
||||
|
||||
---
|
||||
|
||||
## 8. Data Ownership & Source of Truth
|
||||
|
||||
| Data Domain | Source of Truth | Read Access | Write Access |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Staff Profile** | Web Database | Staff App (Own), Client App (Assigned), Admin | Staff (Draft), Admin (Approve) |
|
||||
| **Events/Shifts** | Web Database | Client App (Own), Staff App (Public) | Client (Create), Admin (Override) |
|
||||
| **Timesheets** | Web Database | Client & Staff (View) | System (Automated), Admin (Correction) |
|
||||
| **Financials** | Web Database | Client (Invoices), Staff (Earnings) | System (Calculated Only) |
|
||||
| **Chat/Msgs** | Web Database | Relevant Users | Sender |
|
||||
|
||||
**Principle:** "If it isn't in the Web Database, it didn't happen." Local storage on phones is temporary cache only.
|
||||
|
||||
---
|
||||
|
||||
## 9. Security & Access Model
|
||||
|
||||
### Authentication
|
||||
* **Provider:** Firebase Authentication.
|
||||
* **Philosophy:** "Trust but Verify." We trust Firebase to say *who* someone is (Identity). We trust our own database to say *what* they can do (Permissions).
|
||||
|
||||
### Authorization (RBAC)
|
||||
* **Role: Client:** Can only see *their* Hubs, *their* Events, and Staff *assigned* to them.
|
||||
* **Role: Staff:** Can only see *public* shifts they qualify for, and *their own* financial data.
|
||||
* **Role: Admin:** Has god-mode access via the Web Panel, audited by logs.
|
||||
|
||||
### Trust Boundaries
|
||||
* **Mobile Apps are Untrusted:** We assume the mobile app could be hacked or modified. Therefore, the API validates EVERY request. (e.g., A hacked Staff App sending "I worked 24 hours" will be rejected by server logic).
|
||||
|
||||
---
|
||||
|
||||
## 10. Non-Negotiables & Guardrails
|
||||
|
||||
1. **No Business Logic in UI:** Flutter widgets must never calculate pay, taxes, or availability. They only display values provided by the API.
|
||||
2. **Strict Typing:** GraphQL schemas must be strictly typed. No `JSON` blobs unless absolutely necessary.
|
||||
3. **English Only:** Code, comments, and database columns must be in English. Localization happens at the UI layer only.
|
||||
4. **Immutable Financials:** Once a shift is "Paid," its record can never be modified, only reversed via a new "Correction" transaction.
|
||||
5. **Location Required:** Clock-in actions MUST include GPS coordinates. If GPS is missing, the action is flagged for review.
|
||||
|
||||
---
|
||||
|
||||
## 11. Known Constraints & Assumptions
|
||||
|
||||
* **Assumption:** Clients and Staff have smartphones with working cameras (for QR) and GPS.
|
||||
* **Assumption:** Internet connectivity is available for Shift Creation and Booking. (Only Clock-in supports temporary offline mode).
|
||||
* **Constraint:** The system currently handles a single currency per deployment.
|
||||
* **Constraint:** Notifications are "best effort" via Firebase; they are not guaranteed to arrive instantly.
|
||||
|
||||
---
|
||||
|
||||
## 12. Glossary
|
||||
|
||||
* **Hub:** A physical location or venue owned by a Client (e.g., "Downtown Stadium").
|
||||
* **Shift:** A specific time block requiring a worker (e.g., "Friday 18:00-22:00").
|
||||
* **Position:** A specific role required for a shift (e.g., "Head Waiter").
|
||||
* **Clock-In:** The digital act of starting work, verified by location and time.
|
||||
* **Admin Panel:** The web interface for Krow operations staff.
|
||||
* **Marketplace:** The collection of all open, unassigned shifts visible to staff.
|
||||
* **BLoC:** (Business Logic Component) The code pattern used in the mobile apps to manage state.
|
||||
* **GraphQL:** The data query language used for API communication.
|
||||
Reference in New Issue
Block a user