diff --git a/frontend-web/dataconnect-naming-and-enum-findings.md b/frontend-web/dataconnect-naming-and-enum-findings.md new file mode 100644 index 00000000..d2c11760 --- /dev/null +++ b/frontend-web/dataconnect-naming-and-enum-findings.md @@ -0,0 +1,253 @@ +# 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.