Krow-workspace/frontend-web/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.