Krow-workspace/dataconnect-naming-and-enum-findings.md

# DataConnect – Inconsistencies between the Base44 frontend and the backend (Firebase Data Connect + PostgreSQL)
**Author:** José Salazar  
**Date:** Dec 2025

---

## 📌 Purpose of this document

Document all findings during the integration of the new backend  
(**Firebase Data Connect + PostgreSQL**) with the frontend generated by **Base44 AI**.

This document summarizes:

- Issues found
- camelCase vs snake_case inconsistencies
- Enum inconsistencies (uppercase/lowercase and dashes)
- Differences between what DataConnect returns vs what the frontend expects
- Recommended fixes
- Suggestions for Base44 AI to update its model
- Impact on queries, mutations, and the generated SDK

---

## 1️⃣ Enums – Different formats between Front and Backend

### Observation

In the frontend, enum values are in mixed formats, for example:

- UPPERCASE: SKILLED
- camelCase: fullTime

In the backend (DataConnect schema), enums are defined only in UPPERCASE, for example:

- FULL_TIME  
- CROSS_TRAINED  
- NOT_REQUIRED  
- PENDING  

DataConnect only accepts these exact values.

### Problem

When the frontend sends:

- "crossTrained" instead of CROSS_TRAINED  
- "fluent" instead of FLUENT  

### Impact

- Mutations can fail or return enum validation errors.
- Filters using enums return no results.
- Behavior changes depending on how Base44 AI generated the object.

### Recommendation

- Define a single standard: **ALL enums must be UPPERCASE** on the frontend and backend.
- Before sending to the backend, normalize enum values to uppercase.

### Suggestion for Base44 AI

- Adjust models so they always generate enums in UPPERCASE.

---

## 2️⃣ Enums with dashes (“-”) – Not valid in GraphQL

### Observation

In the legacy frontend, some enum values contain dashes, for example:

- CUSTOMER-SERVICE
- CROSS-TRAINED
- PART-TIME

But in GraphQL enums only allow letters, numbers, and underscores.  
The backend had to define them as:

- CUSTOMER_SERVICE  
- CROSS_TRAINED  
- PART_TIME  

### Problem

When the frontend sends "CUSTOMER-SERVICE" or "CROSS-TRAINED":

- The backend expects CUSTOMER_SERVICE or CROSS_TRAINED.
- There is no match between the frontend value and the DataConnect enum.

### Impact

- Enum filters return nothing.
- Mutations fail when trying to save invalid enum values.
- Compatibility between the Base44 model and the DataConnect schema breaks.

### Recommendation

- Standardize all enums to UPPERCASE SNAKE_CASE (e.g., CUSTOMER_SERVICE).
- Never use dashes “-” in enum values.

### Suggestion for Base44 AI

- Update models so enum values are always generated as  
  UPPERCASE_WITH_UNDERSCORE (e.g., CUSTOMER_SERVICE), without dashes.

---

## 3️⃣ Field names – Front in snake_case vs DataConnect in camelCase

### Observation

The original Base44 frontend uses snake_case field names, for example:

- contact_number
- vendor_id
- background_check_status
- hub_location

In DataConnect the schema is camelCase, and although you can map to the actual PostgreSQL column using @col, the GraphQL type remains camelCase, for example:

- contactNumber (mapped to "contact_number" in Postgres)
- vendorId (mapped to "vendor_id")
- backgroundCheckStatus (mapped to "background_check_status")
- hubLocation (mapped to "hub_location")

Meaning:

- In the database (PostgreSQL) names remain snake_case.
- In DataConnect and the SDK they are exposed as camelCase.

### Problem

The frontend still expects/reads fields like contact_number, but the SDK returns contactNumber.  
A similar issue happens when the frontend sends payloads in snake_case:

- The GraphQL schema does not recognize contact_number.
- It only accepts contactNumber.

### Impact

- UI fails to show data because it reads keys that don’t exist (snake_case).
- Mutations fail or ignore fields due to mismatched names.
- Filters with snake_case are invalid in GraphQL.

### Recommendation

- Agree that **all communication with DataConnect (frontend + SDK) uses camelCase**.
- Keep snake_case only at PostgreSQL level using @col, for example:

      employeeName: String @col(name: "employee_name")

Thus:

- Frontend / SDK / GraphQL → camelCase (employeeName)
- PostgreSQL → snake_case (employee_name)

### Suggestion for Base44 AI

- Adjust generated frontend code so it uses camelCase when consuming the new backend.
- If Supabase or another backend is still used, document all mappings clearly.

---

## 4️⃣ Fields used by the frontend but not listed in API Spec v3

### Observation

During integration we found that Base44 frontend uses fields not defined in the official document:

Reference file:  
docs/03-backend-api-specification-v3.md

Examples in the Staff entity:

The frontend sends and displays fields like:

- notes
- rate

But these fields were not defined in the original v3 specification for Staff.

### Problem

- The frontend assumes these fields exist because the old database had them.
- The DataConnect schema does not include them.
- Sending these values in mutations causes validation errors.

### Impact

- Inconsistency between what the UI shows/edits and what is actually persisted.
- Risk of losing data the user believes is being saved.
- Hard to maintain a 1:1 mapping between the previous Base44 model and the new backend.

### Recommendation

- Validate which fields should truly exist for each entity (e.g., Staff).
- Align these three items:
  1. API Spec v3  
  2. DataConnect Schema  
  3. Base44 Frontend  

- If a field is no longer needed, remove it from the frontend.
- If important, add it formally to the API Spec and to the DataConnect schema.

---

## 5️⃣ DataConnect vs Front – Observed behavior

1. DataConnect:
   - Always exposes fields in camelCase.
   - Enforces enum restrictions exactly as defined (UPPERCASE, no dashes).
   - Allows mapping to Postgres column names using @col, but GraphQL names remain camelCase.

2. Base44 Frontend:
   - Uses snake_case in many areas.
   - Uses enums in mixed formats (uppercase, camelCase, with dashes).
   - Contains extra fields not included in API Spec v3.

---

## 6️⃣ Suggested fixes (personal criteria)

1. Enums  
   - Standardize to UPPERCASE_SNAKE_CASE for all enum values.  
   - Apply a normalization layer in the frontend to convert any format into the official one before hitting the backend.

2. Field names  
   - Migrate the frontend to camelCase for any interaction with DataConnect.  
   - Keep snake_case only at the database layer using @col.

3. Extra fields  
   - Review all fields the frontend sends and compare with API Spec v3.  
   - Remove or add fields depending on what becomes the “source of truth” (Spec v3).

4. Documentation  
   - Keep this file updated as the Base44 → DataConnect migration reference.  
   - Add valid payload examples for each entity (Staff, Vendor, Invoice, etc.).

---

## 7️⃣ Summary

- Always generate:
  - Enums: UPPERCASE_SNAKE_CASE (e.g., FULL_TIME, CUSTOMER_SERVICE).
  - Fields: camelCase (e.g., contactNumber, hubLocation, backgroundCheckStatus).

- Avoid:
  - Dashes “-” in enum values.
  - Spaces in enum values.

---

This document captures the current findings and serves as a guide to fully align the Base44 frontend with the backend based on Firebase Data Connect + PostgreSQL.