Krow/Krow-workspace

Fork 0

Files

José Salazar dbc017fce9 adding dataconnect guide

2026-01-19 19:15:47 -05:00

4.9 KiB

Raw Blame History

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:

Deploy schema
Run SQL migrations
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