From d5e49ca148e434af1bb190cde87b246a923db04c Mon Sep 17 00:00:00 2001 From: zouantchaw <44246692+zouantchaw@users.noreply.github.com> Date: Tue, 24 Feb 2026 10:25:59 -0500 Subject: [PATCH] docs(m4): add frontend api guide and remove agent tracking files --- CHANGELOG.md | 1 + CLAUDE.md | 129 ------------ GEMINI.md | 138 ------------- docs/MILESTONES/M4/planning/m4-api-catalog.md | 14 +- .../M4/planning/m4-core-api-frontend-guide.md | 188 ++++++++++++++++++ 5 files changed, 200 insertions(+), 270 deletions(-) delete mode 100644 CLAUDE.md delete mode 100644 GEMINI.md create mode 100644 docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a4c5a013..7d977913 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,3 +13,4 @@ | 2026-02-24 | 0.1.8 | Enabled dev frontend reachability and made deploy auth mode environment-aware (`dev` public, `staging` private). | | 2026-02-24 | 0.1.9 | Switched core API from mock behavior to real GCS upload/signed URLs and real Vertex model calls in dev deployment. | | 2026-02-24 | 0.1.10 | Hardened core APIs with signed URL ownership/expiry checks, object existence checks, and per-user LLM rate limiting. | +| 2026-02-24 | 0.1.11 | Added frontend-ready core API guide and linked M4 API catalog to it as source of truth for consumption. | diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 9403874e..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,129 +0,0 @@ -# CLAUDE.md - Project Context for AI Assistants - -This file provides context for Claude Code and other AI assistants working on this codebase. - -## Project Overview - -**KROW Workforce** is a workforce management platform connecting businesses with temporary/on-demand workers. It consists of: -- **Client App**: For businesses to create orders, manage hubs, handle billing -- **Staff App**: For workers to manage availability, clock in/out, view earnings -- **Web Dashboard**: Admin portal (React/Vite - WIP) -- **Backend**: Firebase Data Connect + PostgreSQL on Cloud SQL - -## Monorepo Structure - -``` -/apps - /mobile # Flutter apps (managed by Melos) - /apps - /client # krowwithus_client - Business app - /staff # krowwithus_staff - Worker app - /design_system_viewer - /packages - /core # Base utilities - /domain # Business entities, repository interfaces - /data_connect # Data layer, Firebase Data Connect SDK - /design_system # Shared UI components - /core_localization # i18n (Slang) - /features - /client/* # Client-specific features - /staff/* # Staff-specific features - /web-dashboard # React web app (WIP) -/backend - /dataconnect # GraphQL schemas, Firebase Data Connect config - /cloud-functions # Serverless functions (placeholder) -/internal - /launchpad # Internal DevOps portal - /api-harness # API testing tool -/makefiles # Modular Make targets -/docs # Project documentation -``` - -## Key Commands - -### Mobile Development -```bash -# Install dependencies -make mobile-install - -# Run client app (specify your device ID) -make mobile-client-dev-android DEVICE= - -# Run staff app -make mobile-staff-dev-android DEVICE= - -# Find your device ID -flutter devices - -# Build APK -make mobile-client-build PLATFORM=apk -make mobile-staff-build PLATFORM=apk - -# Code generation (localization + build_runner) -cd apps/mobile && melos run gen:all -``` - -### Web Development -```bash -make install # Install web dependencies -make dev # Run web dev server -``` - -### Data Connect -```bash -make dataconnect-sync # Deploy schemas, migrate, regenerate SDK -``` - -## Architecture Patterns - -- **State Management**: BLoC pattern (flutter_bloc) -- **Navigation**: Flutter Modular -- **Architecture**: Clean Architecture (domain/data/presentation layers) -- **Feature Organization**: Each feature is a separate package -- **Value Objects**: Equatable for entity equality - -## Code Conventions - -- Features go in `/apps/mobile/packages/features/{client|staff}/` -- Shared code goes in `/apps/mobile/packages/{core|domain|data_connect}/` -- UI components go in `/apps/mobile/packages/design_system/` -- GraphQL schemas go in `/backend/dataconnect/schema/` -- Documentation language: **English** - -## Important Files - -- `apps/mobile/melos.yaml` - Melos workspace config -- `makefiles/mobile.mk` - Mobile Make targets -- `backend/dataconnect/dataconnect.yaml` - Data Connect config -- `firebase.json` - Firebase hosting/emulator config -- `BLOCKERS.md` - Known blockers and deviations - -## Branch Protection - -- `main` and `dev` branches are protected -- Always create feature branches: `feature/`, `fix/`, `chore/` -- PRs required for merging - -## Testing Mobile Apps - -1. Connect your Android device or start emulator -2. Run `flutter devices` to get device ID -3. Run `make mobile-client-dev-android DEVICE=` - -## Common Issues - -### "No devices found with name 'android'" -The Makefile defaults to device ID `android`. Override with your actual device: -```bash -make mobile-client-dev-android DEVICE=3fb285a7 -``` - -### Dependency resolution issues -```bash -cd apps/mobile && melos clean && melos bootstrap -``` - -### Code generation out of sync -```bash -cd apps/mobile && melos run gen:all -``` diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 1a9c4fe0..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,138 +0,0 @@ -# GEMINI.md - Project Context for AI Assistants - -This file provides context for Gemini and other AI assistants working on this codebase. - -## Project Overview - -**KROW Workforce** is a workforce management platform connecting businesses with temporary/on-demand workers. It consists of: -- **Client App**: For businesses to create orders, manage hubs, handle billing -- **Staff App**: For workers to manage availability, clock in/out, view earnings -- **Web Dashboard**: Admin portal (React/Vite - WIP) -- **Backend**: Firebase Data Connect + PostgreSQL on Cloud SQL - -## Monorepo Structure - -``` -/apps - /mobile # Flutter apps (managed by Melos) - /apps - /client # krowwithus_client - Business app - /staff # krowwithus_staff - Worker app - /design_system_viewer - /packages - /core # Base utilities - /domain # Business entities, repository interfaces - /data_connect # Data layer, Firebase Data Connect SDK - /design_system # Shared UI components - /core_localization # i18n (Slang) - /features - /client/* # Client-specific features - /staff/* # Staff-specific features - /web-dashboard # React web app (WIP) -/backend - /dataconnect # GraphQL schemas, Firebase Data Connect config - /cloud-functions # Serverless functions (placeholder) -/internal - /launchpad # Internal DevOps portal - /api-harness # API testing tool -/makefiles # Modular Make targets -/docs # Project documentation -/bugs # Bug reports and screenshots -``` - -## Key Commands - -### Mobile Development -```bash -# Install dependencies -make mobile-install - -# Run client app (specify your device ID) -make mobile-client-dev-android DEVICE= - -# Run staff app -make mobile-staff-dev-android DEVICE= - -# Find your device ID -flutter devices - -# Build APK -make mobile-client-build PLATFORM=apk -make mobile-staff-build PLATFORM=apk - -# Code generation (localization + build_runner) -cd apps/mobile && melos run gen:all -``` - -### Web Development -```bash -make install # Install web dependencies -make dev # Run web dev server -``` - -### Data Connect -```bash -make dataconnect-sync # Deploy schemas, migrate, regenerate SDK -``` - -## Architecture Patterns - -- **State Management**: BLoC pattern (flutter_bloc) -- **Navigation**: Flutter Modular -- **Architecture**: Clean Architecture (domain/data/presentation layers) -- **Feature Organization**: Each feature is a separate package -- **Value Objects**: Equatable for entity equality - -## Code Conventions - -- Features go in `/apps/mobile/packages/features/{client|staff}/` -- Shared code goes in `/apps/mobile/packages/{core|domain|data_connect}/` -- UI components go in `/apps/mobile/packages/design_system/` -- GraphQL schemas go in `/backend/dataconnect/schema/` -- Documentation language: **English** - -## Important Files - -- `apps/mobile/melos.yaml` - Melos workspace config -- `makefiles/mobile.mk` - Mobile Make targets -- `backend/dataconnect/dataconnect.yaml` - Data Connect config -- `firebase.json` - Firebase hosting/emulator config -- `BLOCKERS.md` - Known blockers and deviations -- `bugs/BUG-REPORT-*.md` - Bug reports with analysis - -## Branch Protection - -- `main` and `dev` branches are protected -- Always create feature branches: `feature/`, `fix/`, `chore/` -- PRs required for merging - -## Testing Mobile Apps - -1. Connect your Android device or start emulator -2. Run `flutter devices` to get device ID -3. Run `make mobile-client-dev-android DEVICE=` - -## Common Issues - -### "No devices found with name 'android'" -The Makefile defaults to device ID `android`. Override with your actual device: -```bash -make mobile-client-dev-android DEVICE=3fb285a7 -``` - -### Dependency resolution issues -```bash -cd apps/mobile && melos clean && melos bootstrap -``` - -### Code generation out of sync -```bash -cd apps/mobile && melos run gen:all -``` - -## Known Technical Debt - -See `bugs/BUG-REPORT-*.md` for detailed analysis of: -- Authentication/User sync issues -- Error handling architecture (needs AppException pattern) -- BLoC state management patterns (copyWith null handling) diff --git a/docs/MILESTONES/M4/planning/m4-api-catalog.md b/docs/MILESTONES/M4/planning/m4-api-catalog.md index c8e02353..8a4141c9 100644 --- a/docs/MILESTONES/M4/planning/m4-api-catalog.md +++ b/docs/MILESTONES/M4/planning/m4-api-catalog.md @@ -1,10 +1,18 @@ # M4 API Catalog (Implementation Contract) -Status: Draft -Date: 2026-02-24 -Owner: Technical Lead +Status: Active (Planning + Route Inventory) +Date: 2026-02-24 +Owner: Technical Lead Environment: dev +## Frontend source of truth +For frontend implementation, use: +- `docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md` + +Reason: +- this catalog is the broader M4 planning contract +- the frontend guide is the exact deployed request/response contract + ## 1) Scope and purpose This file defines the backend endpoint contract for the M4 foundation build. diff --git a/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md b/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md new file mode 100644 index 00000000..7525dfdb --- /dev/null +++ b/docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md @@ -0,0 +1,188 @@ +# M4 Core API Frontend Guide (Dev) + +Status: Active +Last updated: 2026-02-24 +Audience: Web and mobile frontend developers + +## 1) Base URLs (dev) +1. Core API: `https://krow-core-api-e3g6witsvq-uc.a.run.app` +2. Command API: `https://krow-command-api-e3g6witsvq-uc.a.run.app` + +## 2) Auth requirements +1. Send Firebase ID token on protected routes: +```http +Authorization: Bearer +``` +2. Health route is public: +- `GET /health` +3. All other routes require Firebase token. + +## 3) Standard error envelope +```json +{ + "code": "STRING_CODE", + "message": "Human readable message", + "details": {}, + "requestId": "uuid" +} +``` + +## 4) Core API endpoints + +## 4.1 Upload file +1. Route: `POST /core/upload-file` +2. Alias: `POST /uploadFile` +3. Content type: `multipart/form-data` +4. Form fields: +- `file` (required) +- `visibility` (optional: `public` or `private`, default `private`) +- `category` (optional) +5. Accepted file types: +- `application/pdf` +- `image/jpeg` +- `image/jpg` +- `image/png` +6. Max upload size: `10 MB` (default) +7. Current behavior: real upload to Cloud Storage (not mock) +8. Success `200` example: +```json +{ + "fileUri": "gs://krow-workforce-dev-private/uploads//173...", + "contentType": "application/pdf", + "size": 12345, + "bucket": "krow-workforce-dev-private", + "path": "uploads//173..._file.pdf", + "requestId": "uuid" +} +``` + +## 4.2 Create signed URL +1. Route: `POST /core/create-signed-url` +2. Alias: `POST /createSignedUrl` +3. Request body: +```json +{ + "fileUri": "gs://krow-workforce-dev-private/uploads//file.pdf", + "expiresInSeconds": 300 +} +``` +4. Security checks: +- bucket must be allowed (`krow-workforce-dev-public` or `krow-workforce-dev-private`) +- path must be owned by caller (`uploads//...`) +- object must exist +- `expiresInSeconds` must be `<= 900` +5. Success `200` example: +```json +{ + "signedUrl": "https://storage.googleapis.com/...", + "expiresAt": "2026-02-24T15:22:28.105Z", + "requestId": "uuid" +} +``` +6. Typical errors: +- `400 VALIDATION_ERROR` (bad payload or expiry too high) +- `403 FORBIDDEN` (path not owned by caller) +- `404 NOT_FOUND` (object does not exist) + +## 4.3 Invoke model +1. Route: `POST /core/invoke-llm` +2. Alias: `POST /invokeLLM` +3. Request body: +```json +{ + "prompt": "Return JSON with keys summary and risk.", + "responseJsonSchema": { + "type": "object", + "properties": { + "summary": { "type": "string" }, + "risk": { "type": "string" } + }, + "required": ["summary", "risk"] + }, + "fileUrls": [] +} +``` +4. Current behavior: real Vertex model call (not mock) +- model: `gemini-2.0-flash-001` +- timeout: `20 seconds` +5. Rate limit: +- per-user `20 requests/minute` (default) +- on limit: `429 RATE_LIMITED` +- includes `Retry-After` header +6. Success `200` example: +```json +{ + "result": { "summary": "text", "risk": "Low" }, + "model": "gemini-2.0-flash-001", + "latencyMs": 367, + "requestId": "uuid" +} +``` + +## 5) Command API endpoint currently ready for consumption + +## 5.1 Create order command (scaffold) +1. Route: `POST /commands/orders/create` +2. Required headers: +- `Authorization: Bearer ` +- `Idempotency-Key: ` +3. Current behavior: +- validates auth + idempotency +- returns accepted scaffold response +- duplicate key returns the original response payload +4. Success `200` example: +```json +{ + "accepted": true, + "route": "/commands/orders/create", + "commandId": "/commands/orders/create:173...", + "idempotencyKey": "client-key-123", + "requestId": "uuid" +} +``` + +## 6) Frontend fetch examples (web) + +## 6.1 Signed URL request +```ts +const token = await firebaseAuth.currentUser?.getIdToken(); +const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/create-signed-url', { + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + fileUri: 'gs://krow-workforce-dev-private/uploads//file.pdf', + expiresInSeconds: 300, + }), +}); +const data = await res.json(); +``` + +## 6.2 Model request +```ts +const token = await firebaseAuth.currentUser?.getIdToken(); +const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/invoke-llm', { + method: 'POST', + headers: { + Authorization: `Bearer ${token}`, + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ + prompt: 'Return JSON with status.', + responseJsonSchema: { + type: 'object', + properties: { status: { type: 'string' } }, + required: ['status'], + }, + }), +}); +const data = await res.json(); +``` + +## 7) Notes for frontend team +1. Use canonical `/core/*` routes for new work. +2. Aliases exist only for migration compatibility. +3. `requestId` in responses should be logged client-side for debugging. +4. For 429 on model route, retry with exponential backoff and respect `Retry-After`.