Krow-workspace/docs/03-backend-api-specification.md

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://..." }