adding dataconnect guide

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/<entity>/
+```
+
+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

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"
   }
 ]