feat: Add Milestone 3 documentation including feature testing plan, demo notes, and demo flow details
- Introduced comprehensive testing plan for Milestone 3 in m3-client-note.md - Documented feedback and suggestions from demo sessions in m3-notes.md - Created detailed demo flow for Milestone 3 in m3.md, outlining user interactions and expected outcomes - Added planning tasks for Milestone 4 in m4-planning.md, covering backend and frontend development tasks, research, and business tasks
This commit is contained in:
Achintha Isuru
@@ -1,294 +0,0 @@
|
||||
# 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
|
||||
File diff suppressed because it is too large
Load Diff
@@ -65,10 +65,10 @@
|
||||
},
|
||||
{
|
||||
"title": "Dataconnect guide",
|
||||
"path": "./assets/documents/dataconnect/backend_manual.md"
|
||||
"path": "docs/DATACONNECT_GUIDES/DOCUMENTS/backend_manual.md"
|
||||
},
|
||||
{
|
||||
"title": "Schema Dataconnect guide",
|
||||
"path": "./assets/documents/dataconnect/schema_dataconnect_guide.md"
|
||||
"path": "docs/DATACONNECT_GUIDES/DOCUMENTS/schema_dataconnect_guide.md"
|
||||
}
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user