diff --git a/internal/launchpad/assets/documents/dataconnect/backend_manual.md b/internal/launchpad/assets/documents/dataconnect/backend_manual.md new file mode 100644 index 00000000..a256a882 --- /dev/null +++ b/internal/launchpad/assets/documents/dataconnect/backend_manual.md @@ -0,0 +1,294 @@ +# Krow Workforce – Backend Manual +Firebase Data Connect + Cloud SQL (PostgreSQL) + +--- + +## 1. Backend Overview + +This project uses Firebase Data Connect with Cloud SQL (PostgreSQL) as the main backend system. + +The architecture is based on: + +- GraphQL Schemas → Define database tables +- Connectors (Queries & Mutations) → Data access layer +- Cloud SQL → Real database +- Auto-generated SDK → Used by Web & Mobile apps +- Makefile → Automates backend workflows + +The goal is to keep the backend scalable, structured, and aligned with Web and Mobile applications. + +--- + +## 2. Project Structure + +``` +dataconnect/ +│ +├── dataconnect.yaml +├── schema/ +│ ├── Staff.gql +│ ├── Vendor.gql +│ ├── Business.gql +│ └── ... +│ +├── connector/ +│ ├── staff/ +│ │ ├── queries.gql +│ │ └── mutations.gql +│ ├── invoice/ +│ └── ... +│ +├── connector/connector.yaml +│ +docs/backend-diagrams/ +│ ├── business_uml_diagram.mmd +│ ├── staff_uml_diagram.mmd +│ ├── team_uml_diagram.mmd +│ ├── user_uml_diagram.mmd +│ └── vendor_uml_diagram_simplify.mmd +``` + +--- + +## 3. dataconnect.yaml (Main Configuration) + +```yaml +specVersion: "v1" +serviceId: "krow-workforce-db" +location: "us-central1" + +schema: + source: "./schema" + datasource: + postgresql: + database: "krow_db" + cloudSql: + instanceId: "krow-sql" + +connectorDirs: ["./connector"] +``` + +### Purpose + +| Field | Description | +|------|------------| +| serviceId | Data Connect service name | +| schema.source | Where GraphQL schemas live | +| datasource | Cloud SQL connection | +| connectorDirs | Where queries/mutations are | + +--- + +## 4. Database Schemas + +All database schemas are located in: + +``` +dataconnect/schema/ +``` + +Each `.gql` file represents a table: + +- Staff.gql +- Invoice.gql +- ShiftRole.gql +- Application.gql +- etc. + +Schemas define: + +- Fields +- Enums +- Relationships (`@ref`) +- Composite keys (`key: []`) + +--- + +## 5. Queries & Mutations (Connectors) + +Located in: + +``` +dataconnect/connector// +``` + +Example: + +``` +dataconnect/connector/staff/queries.gql +dataconnect/connector/staff/mutations.gql +``` + +Each folder represents one entity. + +This layer defines: + +- listStaff +- getStaffById +- createStaff +- updateStaff +- deleteStaff +- etc. + +--- + +## 6. connector.yaml (SDK Generator) + +```yaml +connectorId: example +generate: + dartSdk: + - outputDir: ../../mobile/staff/staff_app_mvp/lib/dataconnect_generated + package: dataconnect_generated/generated.dart + - outputDir: ../../mobile/client/client_app_mvp/lib/dataconnect_generated + package: dataconnect_generated/generated.dart +``` + +This file generates the SDK for: + +- Staff Mobile App +- Client Mobile App + +--- + +## 7. What is the SDK? + +The SDK is generated using: + +```bash +firebase dataconnect:sdk:generate +``` + +It allows the apps to: + +- Call queries/mutations +- Use strong typing +- Avoid manual GraphQL +- Reduce runtime errors + +Example in Flutter: + +```dart +client.listStaff(); +client.createInvoice(); +``` + +--- + +## 8. Makefile – Automation Commands + +### Main Commands + +| Command | Purpose | +|--------|---------| +| dataconnect-enable-apis | Enable required APIs | +| dataconnect-init | Initialize Data Connect | +| dataconnect-deploy | Deploy schemas | +| dataconnect-sql-migrate | Apply DB migrations | +| dataconnect-generate-sdk | Generate SDK | +| dataconnect-sync | Full backend update | +| dataconnect-test | Test without breaking | +| dataconnect-seed | Insert seed data | +| dataconnect-bootstrap-db | Create Cloud SQL | + +--- + +## 9. Correct Backend Workflow + +### Production Flow + +```bash +make dataconnect-sync +``` + +Steps: + +1. Deploy schema +2. Run SQL migrations +3. Generate SDK + +--- + +### Safe Test Flow + +```bash +make dataconnect-test +``` + +This runs: + +- Deploy dry-run +- SQL diff +- Shows errors without changing DB + +--- + +## 10. Seed Data + +Current command: + +```make +dataconnect-seed: + @firebase dataconnect:execute seeds/seed_min.graphql --project=$(FIREBASE_ALIAS) +``` + +Purpose: + +- Validate schema +- Detect missing tables +- Prevent bad inserts + +--- + +## 11. UML Diagrams + +Located in: + +``` +docs/backend-diagrams/ +``` + +Divided by role: + +| File | Scope | +|------|-------| +| user_uml_diagram.mmd | User | +| staff_uml_diagram.mmd | Staff | +| vendor_uml_diagram_simplify.mmd | Vendor | +| business_uml_diagram.mmd | Business | +| team_uml_diagram.mmd | Teams | + +Used with Mermaid to visualize relationships. + +--- + +## 12. Core Business Workflow + +```text +Order + → Shift + → ShiftRole + → Application + → Workforce + → Assignment + → Invoice + → RecentPayment +``` + +This represents the full work & payment lifecycle. + +--- + +## 13. Final Notes + +This backend is designed to: + +- Scale efficiently +- Maintain data consistency +- Align Web & Mobile models +- Support reporting and billing +- Avoid duplicated data + +--- + +END OF MANUAL diff --git a/internal/launchpad/assets/documents/documents-config.json b/internal/launchpad/assets/documents/documents-config.json index e86d355e..f325a702 100644 --- a/internal/launchpad/assets/documents/documents-config.json +++ b/internal/launchpad/assets/documents/documents-config.json @@ -6,5 +6,9 @@ { "title": "Architecture Document & Migration Plan", "path": "./assets/documents/legacy/client-mobile-application/architecture.md" + }, + { + "title": "Dataconnect guide", + "path": "./assets/documents/dataconnect/backend_manual.md" } ]