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)

```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