554dc9f9e3
This commit establishes the new monorepo architecture for the KROW Workforce platform. Key changes include: - Reorganized project into `frontend-web`, `mobile-apps`, `firebase`, `scripts`, and `secrets` directories. - Updated `Makefile` to support the new monorepo layout and automate Base44 export integration. - Fixed `scripts/prepare-export.js` for ES module compatibility and global component import resolution. - Created and updated `CONTRIBUTING.md` for developer onboarding. - Restructured, renamed, and translated all `docs/` files for clarity and consistency. - Implemented an interactive internal launchpad with diagram viewing capabilities. - Configured base Firebase project files (`firebase.json`, security rules). - Updated `README.md` to reflect the new project structure and documentation overview.
132 lines
7.6 KiB
Markdown
132 lines
7.6 KiB
Markdown
# KROW Workforce API Specification (GCP Migration)
|
|
|
|
**Version:** 2.0
|
|
**Date:** 2025-11-11
|
|
**Objective:** This document defines the backend API to be built on the Firebase/GCP ecosystem, replacing the Base44 backend. It is based on the comprehensive Base44 API documentation (v2.0) and will guide the development of the new backend using Firebase Data Connect and Cloud Functions.
|
|
|
|
---
|
|
|
|
## General Conventions
|
|
|
|
- **API Layer:** The backend will be composed of two main parts:
|
|
- **Firebase Data Connect:** A GraphQL API for all data-centric (CRUD) operations.
|
|
- **Cloud Functions:** A set of RESTful endpoints for all service-centric operations (e.g., sending emails, processing files).
|
|
- **Authentication:** Every request must include an `Authorization: Bearer <Firebase-Auth-Token>` header, managed and validated by Firebase.
|
|
- **Data Format:** All requests and responses will be in `application/json` format.
|
|
- **Error Responses:** Errors will use standard HTTP status codes (400, 401, 403, 404, 500) and include a JSON response body of the form `{ "error": "Problem description" }`.
|
|
- **Common Fields:** Each entity will have the following fields, automatically managed by the backend:
|
|
- `id`: `string` (UUID, Primary Key)
|
|
- `created_date`: `string` (ISO 8601 Timestamp)
|
|
- `updated_date`: `string` (ISO 8601 Timestamp)
|
|
- `created_by`: `string` (Email of the creating user)
|
|
|
|
---
|
|
|
|
## 1. Authentication (Firebase Auth)
|
|
|
|
Authentication will be handled entirely by Firebase Authentication. The client applications (web and mobile) are responsible for the sign-up and sign-in flows using the Firebase SDK. The backend will use the provided auth token to identify the user for all subsequent requests.
|
|
|
|
### `User` Entity (Managed by Firebase Auth & Data Connect)
|
|
|
|
| Field | Type | Description |
|
|
| ----------- | -------- | ----------------------------------------- |
|
|
| `id` | `string` | Firebase User ID (UID) |
|
|
| `email` | `string` | User's email (non-modifiable) |
|
|
| `full_name` | `string` | Full name |
|
|
| `user_role` | `string` | Custom application role (`admin`, `procurement`, `client`...) |
|
|
| `...other` | `any` | Other custom fields can be added. |
|
|
|
|
---
|
|
|
|
## 2. Data API (Firebase Data Connect)
|
|
|
|
All entities below will be managed via a GraphQL API powered by Firebase Data Connect. For each entity, standard `query` (list, get by ID) and `mutation` (create, update, delete) operations will be defined in the `firebase/dataconnect/` directory.
|
|
|
|
### 2.1. Event
|
|
|
|
**Description:** Manages events and workforce orders.
|
|
|
|
| Field | Type | Description |
|
|
| ----------------------- | --------- | ------------------------------------------------ |
|
|
| `event_name` | `string` | Name of the event (required) |
|
|
| `is_recurring` | `boolean` | Indicates if the event is recurring |
|
|
| `recurrence_type` | `string` | `single`, `date_range`, `scatter` |
|
|
| `business_id` | `string` | ID of the client (`Business`) |
|
|
| `vendor_id` | `string` | ID of the provider (`Vendor`) |
|
|
| `status` | `string` | `Draft`, `Active`, `Pending`, `Assigned`, `Confirmed`, `Completed`, `Canceled` |
|
|
| `date` | `string` | Event date (ISO 8601) |
|
|
| `shifts` | `jsonb` | Array of `Shift` objects |
|
|
| `total` | `number` | Total cost |
|
|
| `requested` | `number` | Total number of staff requested |
|
|
| `assigned_staff` | `jsonb` | Array of assigned staff objects |
|
|
|
|
### 2.2. Staff
|
|
|
|
**Description:** Manages staff members.
|
|
|
|
| Field | Type | Description |
|
|
| ------------------------- | --------- | ----------------------------------------- |
|
|
| `employee_name` | `string` | Full name (required) |
|
|
| `vendor_id` | `string` | ID of the provider (`Vendor`) |
|
|
| `email` | `string` | Email address |
|
|
| `position` | `string` | Primary job position/skill |
|
|
| `employment_type` | `string` | `Full Time`, `Part Time`, `On call`, etc. |
|
|
| `rating` | `number` | Performance rating (0-5) |
|
|
| `reliability_score` | `number` | Reliability score (0-100) |
|
|
| `background_check_status` | `string` | `pending`, `cleared`, `failed`, `expired` |
|
|
| `certifications` | `jsonb` | List of certifications |
|
|
|
|
### 2.3. Vendor
|
|
|
|
**Description:** Manages providers and their onboarding.
|
|
|
|
| Field | Type | Description |
|
|
| ----------------------- | --------- | ----------------------------------------- |
|
|
| `vendor_number` | `string` | Vendor number (e.g., `VN-####`) |
|
|
| `legal_name` | `string` | Legal company name (required) |
|
|
| `primary_contact_email` | `string` | Primary contact email (required) |
|
|
| `approval_status` | `string` | `pending`, `approved`, `suspended`, `terminated` |
|
|
| `is_active` | `boolean` | Active status |
|
|
| `w9_document` | `string` | URL or URI of the W9 document |
|
|
| `coi_document` | `string` | URL or URI of the Certificate of Insurance|
|
|
|
|
---
|
|
|
|
*Note: For brevity, only the most critical entities have been detailed. The same structure (Schema defined in GraphQL) must be applied for all other entities: `VendorRate`, `Invoice`, `Business`, `Certification`, `Team`, `Conversation`, `Message`, `ActivityLog`, `Enterprise`, `Sector`, `Partner`, `Order`, and `Shift`, based on the `07-reference-base44-api-export.md` document.*
|
|
|
|
---
|
|
|
|
## 3. Services API (Cloud Functions)
|
|
|
|
These endpoints are not for CRUD operations but for specific, service-oriented tasks. They will be implemented as individual HTTP-triggered Cloud Functions.
|
|
|
|
### `POST /sendEmail`
|
|
- **Description:** Sends an email.
|
|
- **Original SDK:** `base44.integrations.Core.SendEmail(params)`
|
|
- **Body:** `{ "to": "...", "subject": "...", "body": "..." }`
|
|
- **Response (200 OK):** `{ "status": "sent" }`
|
|
|
|
### `POST /invokeLLM`
|
|
- **Description:** Calls a large language model (Vertex AI).
|
|
- **Original SDK:** `base44.integrations.Core.InvokeLLM(params)`
|
|
- **Body:** `{ "prompt": "...", "response_json_schema": {...}, "file_urls": [...] }`
|
|
- **Response (200 OK):** `{ "result": "..." }`
|
|
|
|
### `POST /uploadFile`
|
|
- **Description:** Handles the upload of public files to Google Cloud Storage and returns a public URL.
|
|
- **Original SDK:** `base44.integrations.Core.UploadFile({ file })`
|
|
- **Request:** `multipart/form-data`.
|
|
- **Response (200 OK):** `{ "file_url": "https://..." }`
|
|
|
|
### `POST /uploadPrivateFile`
|
|
- **Description:** Handles the upload of private files to Google Cloud Storage and returns a secure URI.
|
|
- **Original SDK:** `base44.integrations.Core.UploadPrivateFile({ file })`
|
|
- **Request:** `multipart/form-data`.
|
|
- **Response (200 OK):** `{ "file_uri": "gs://..." }`
|
|
|
|
### `POST /createSignedUrl`
|
|
- **Description:** Creates a temporary access URL for a private file.
|
|
- **Original SDK:** `base44.integrations.Core.CreateFileSignedUrl(params)`
|
|
- **Body:** `{ "file_uri": "...", "expires_in": 3600 }`
|
|
- **Response (200 OK):** `{ "signed_url": "https://..." }`
|