feat: Add comprehensive documentation for Krow Platform architecture, including system bible, web application use cases, and mobile agent development rules
- Introduced the Krow Platform System Bible detailing the executive summary, system vision, ecosystem overview, architecture, application responsibilities, use cases, and security model. - Created a detailed use case overview for the Krow Web Application, outlining workflows for Admin, Client, and Vendor roles. - Established non-negotiable agent development rules for mobile applications, emphasizing file structure, naming conventions, logic placement, localization, and error handling. - Defined architecture principles for the Krow mobile platform, focusing on clean architecture, dependency direction, and session management. - Documented design system usage guidelines to ensure UI consistency and adherence to design tokens across applications.
This commit is contained in:
Achintha Isuru
152
docs/ARCHITECTURE/architecture.md
Normal file
152
docs/ARCHITECTURE/architecture.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Krow Platform: System Architecture Overview
|
||||
|
||||
## 1. Executive Summary: The Business Purpose
|
||||
The **Krow Platform** is an end-to-end workforce management ecosystem designed to bridge the gap between businesses that need staff ("Clients") and the temporary workers who fill those roles ("Staff").
|
||||
|
||||
Traditionally, this process involves phone calls, paper timesheets, and manual payroll. Krow digitizes the entire lifecycle:
|
||||
1. **Finding Work:** Clients post shifts instantly; workers claim them via mobile.
|
||||
2. **Doing Work:** GPS-verified clock-ins and digital timesheets ensure accuracy.
|
||||
3. **Managing Business:** A web dashboard provides analytics, billing, and compliance oversight.
|
||||
|
||||
The system's goal is to reduce administrative friction, ensure legal compliance, and optimize labor costs through automation and real-time data.
|
||||
|
||||
## 2. The Application Ecosystem
|
||||
The platform consists of three distinct applications, each tailored to a specific user group:
|
||||
|
||||
### A. Client Mobile App (The "Requester")
|
||||
* **User:** Business Owners, Venue Managers.
|
||||
* **Role:** The demand generator. It allows clients to request staff on the fly, track who is arriving, and approve hours worked.
|
||||
* **Key Value:** Speed and visibility. A manager can fill a sudden "no-show" gap in seconds from their phone.
|
||||
|
||||
### B. Staff Mobile App (The "Worker")
|
||||
* **User:** Temporary Staff (Servers, Cooks, Bartenders).
|
||||
* **Role:** The supply pool. It acts as their personal agency, handling job discovery, schedule management, and instant payouts.
|
||||
* **Key Value:** Flexibility and financial security. Workers choose when they work and get paid faster.
|
||||
|
||||
### C. Krow Web Application (The "HQ")
|
||||
* **User:** Administrators, HR, Finance, and Client Executives.
|
||||
* **Role:** The command center. It handles the heavy lifting—complex invoicing, vendor management, compliance audits, and strategic data analysis.
|
||||
* **Key Value:** Control and insight. It turns operational data into cost-saving strategies.
|
||||
|
||||
## 3. How the Applications Interact
|
||||
The three applications do not "talk" directly to each other (e.g., the staff app doesn't send a message directly to the client app). Instead, they all communicate with a central **Shared Backend System** (The "Brain").
|
||||
|
||||
* **Scenario: Filling a Shift**
|
||||
1. **Client App:** Manager posts a shift for "Friday, 6 PM".
|
||||
2. **Backend:** Receives the request, validates it, and notifies eligible workers.
|
||||
3. **Staff App:** Worker sees the notification and taps "Accept".
|
||||
4. **Backend:** Confirms the match, updates the schedule, and alerts the client.
|
||||
5. **Web App:** Admin sees the shift status change from "Open" to "Filled" on the live dashboard.
|
||||
|
||||
## 4. Shared Services & Infrastructure
|
||||
To function as a cohesive unit, the ecosystem relies on several shared foundational services:
|
||||
|
||||
* **Central Database:** The "Single Source of Truth." Whether a worker updates their profile photo on mobile or an admin updates it on the web, the change is saved in one place (Firebase/Firestore) and reflects everywhere instantly.
|
||||
* **Authentication Service:** A unified login system. While users have different roles (Client vs. Staff), the security mechanism verifying their identity is shared.
|
||||
* **Notification Engine:** A centralized service that knows how to reach users—sending push notifications to phones (Mobile Apps) and emails to desktops (Web App).
|
||||
* **Payment Gateway:** A shared financial pipe. It collects money from clients (Credit Card/ACH) and disburses it to workers (Direct Deposit/Instant Pay).
|
||||
|
||||
## 5. Data Ownership & Boundaries
|
||||
To maintain privacy and organization, data is strictly compartmentalized:
|
||||
|
||||
* **Worker Data:** Owned by the worker but accessible to the platform. Clients can only see limited details (Name, Rating, Skills) of workers assigned to *their* specific shifts. They cannot see a worker's full financial history or assignments with other clients.
|
||||
* **Client Data:** Owned by the business. Workers see only what is necessary to do the job (Location, Dress Code, Supervisor Name). They cannot see the client's internal billing or strategic reports.
|
||||
* **Platform Data:** owned by Krow (Admins). This includes the aggregate data used for "Smart Strategies" and market analysis—e.g., "Average hourly rate for a Bartender in downtown."
|
||||
|
||||
## 6. Security & Access Control
|
||||
The system operates on a **Role-Based Access Control (RBAC)** model:
|
||||
|
||||
* **Authentication (Who are you?):** Strict verification using email/password or phone/OTP (One-Time Password).
|
||||
* **Authorization (What can you do?):**
|
||||
* **Staff:** Can *read* job details but *write* only to their own timesheets and profile.
|
||||
* **Clients:** Can *write* new orders and *read* reports for their own venues only.
|
||||
* **Admins:** Have "Super User" privileges to view and modify data across the entire system to resolve disputes or manage configurations.
|
||||
|
||||
## 7. Inter-Application Dependencies
|
||||
While the apps are installed separately, they are operationally dependent:
|
||||
|
||||
* **Dependency A:** The **Client App** cannot function without the **Staff App** users. An order posted by a client is useless if no workers exist to claim it.
|
||||
* **Dependency B:** The **Staff App** relies on the **Web App** for financial processing. A worker can "clock out," but they don't get paid until the backend logic (managed via Web App rules) processes the invoice.
|
||||
* **Dependency C:** All apps depend on the **Backend API**. If the central server goes down, no app can fetch data, effectively pausing the entire operation.
|
||||
|
||||
---
|
||||
|
||||
# System Overview Diagram
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Users [Users]
|
||||
ClientUser((Client Manager))
|
||||
StaffUser((Temporary Worker))
|
||||
AdminUser((Admin / Ops))
|
||||
end
|
||||
|
||||
subgraph FrontEnd [Application Ecosystem]
|
||||
direction TB
|
||||
ClientApp[Client Mobile App]
|
||||
StaffApp[Staff Mobile App]
|
||||
WebApp[Web Management Console]
|
||||
end
|
||||
|
||||
subgraph Backend [Shared Backend Services]
|
||||
direction TB
|
||||
APIGateway[API Gateway]
|
||||
|
||||
subgraph CoreServices [Core Business Logic]
|
||||
AuthService[Authentication Service]
|
||||
OrderService[Order & Shift Service]
|
||||
WorkerService[Worker Profile Service]
|
||||
FinanceService[Billing & Payroll Service]
|
||||
NotificationEngine[Notification Engine]
|
||||
AnalyticsEngine[Analytics & AI Engine]
|
||||
end
|
||||
|
||||
Database[("Central Database (Firebase/Firestore)")]
|
||||
end
|
||||
|
||||
subgraph External [External Integrations]
|
||||
PaymentProvider["Payment Gateway (Stripe/Bank)"]
|
||||
MapService[Maps & Geolocation]
|
||||
SMSGateway[SMS / OTP Service]
|
||||
end
|
||||
|
||||
%% User Interactions
|
||||
ClientUser -- Uses --> ClientApp
|
||||
StaffUser -- Uses --> StaffApp
|
||||
AdminUser -- Uses --> WebApp
|
||||
|
||||
%% App to Backend Communication
|
||||
ClientApp -- "Auth, Orders, Timesheets" --> APIGateway
|
||||
StaffApp -- "Auth, Job Claims, Clock-In" --> APIGateway
|
||||
WebApp -- "Auth, Admin, Reports" --> APIGateway
|
||||
|
||||
%% Internal Backend Flow
|
||||
APIGateway --> CoreServices
|
||||
CoreServices --> Database
|
||||
|
||||
%% Specific Service Interactions
|
||||
AuthService -- "Verifies Identity" --> Database
|
||||
OrderService -- "Matches Shifts" --> Database
|
||||
WorkerService -- "Stores Profiles" --> Database
|
||||
FinanceService -- "Processes Invoices" --> Database
|
||||
AnalyticsEngine -- "Reads Data" --> Database
|
||||
|
||||
%% External Connections
|
||||
AuthService -- "Sends OTP" --> SMSGateway
|
||||
StaffApp -- "Verifies Location" --> MapService
|
||||
FinanceService -- "Processes Payouts" --> PaymentProvider
|
||||
NotificationEngine -- "Push Alerts" --> ClientApp
|
||||
NotificationEngine -- "Push Alerts" --> StaffApp
|
||||
|
||||
%% Styling
|
||||
classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
|
||||
classDef app fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
|
||||
classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
|
||||
classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;
|
||||
classDef db fill:#e0e0e0,stroke:#616161,stroke-width:2px;
|
||||
|
||||
class ClientUser,StaffUser,AdminUser user;
|
||||
class ClientApp,StaffApp,WebApp app;
|
||||
class APIGateway,AuthService,OrderService,WorkerService,FinanceService,NotificationEngine,AnalyticsEngine backend;
|
||||
class PaymentProvider,MapService,SMSGateway external;
|
||||
class Database db;
|
||||
```
|
||||
Reference in New Issue
Block a user