Krow-workspace/docs/DATACONNECT_GUIDES/DOCUMENTS/backend_manual.md

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)

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)

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:

firebase dataconnect:sdk:generate

It allows the apps to:

• Call queries/mutations
• Use strong typing
• Avoid manual GraphQL
• Reduce runtime errors

Example in Flutter:

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

make dataconnect-sync

Steps:

1. Deploy schema
2. Run SQL migrations
3. Generate SDK

---

Safe Test Flow

make dataconnect-test

This runs:

• Deploy dry-run
• SQL diff
• Shows errors without changing DB

---

10. Seed Data

Current command:

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

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