recomendations for front ia
This commit is contained in:
José Salazar
253
frontend-web/dataconnect-naming-and-enum-findings.md
Normal file
253
frontend-web/dataconnect-naming-and-enum-findings.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user