Crispy CRM Data Provider Architecture

Apply these rules when modifying the data provider layer (src/atomic-crm/providers/supabase).

Quick Reference

1. Migration Strategy (Strangler Fig)

Goal: Incrementally replace unifiedDataProvider.ts without breaking the app.

Rules

• Maintain unifiedDataProvider.ts: Only apply bug fixes. No new logic.
• Isolate New Resources: All new resources use Composed Handler Pattern in handlers/.
• Shrink the Monolith: unifiedDataProvider.ts should only decrease in size.

Decision Tree

Is this a NEW resource?
  YES → Create handler in src/providers/supabase/handlers/
  NO → Is this a CRITICAL bug fix?
    YES → Patch minimally in unifiedDataProvider.ts
    NO → Is this ASSIGNED migration work?
      YES → Create handler, migrate, delete from monolith
      NO → Do not modify unifiedDataProvider.ts

See migration-strategy.md for details.

2. View vs. Table Duality

Problem: React Admin expects one "resource" but we have Views (read) and Tables (write).

Rules

• Read from Views: getList, getOne query SQL Views (e.g., contacts_summary)
• Write to Tables: create, update go to Base Tables (e.g., contacts)
• Strip Computed Fields: Remove view-only fields before writing

Example

// READ - Use the View
const getList = async () => {
  const { data } = await supabase.from('contacts_summary').select('*');
  return { data, total: data.length };
};

// WRITE - Use the Table
const create = async (params) => {
  const cleaned = stripComputedFields(params.data);
  const { data } = await supabase.from('contacts').insert(cleaned);
  return { data };
};

See view-table-duality.md for implementation.

3. Validation Boundaries

Principle: Validate at the API boundary, NOT in forms.

Rules

• Handler Validates: Use Zod schemas from src/atomic-crm/validation/
• Fail Fast: Throw HttpError immediately on validation failure
• Form Trust: Forms may display errors but don't enforce validation

Error Response Format

throw new HttpError(400, "Validation Error", {
  errors: {
    email: "Invalid email format",
    first_name: "Required"
  }
});

See error-handling.md for mapping patterns.

4. Service Layer Encapsulation

Principle: Data Provider translates; Services orchestrate.

Rules

• Provider = Translator: Convert React Admin params → Supabase params
• Service = Orchestrator: Handle multi-step operations, business logic
• No Raw Calls: Complex logic belongs in Services, not Handlers

When to Use Services

• Multi-table operations (e.g., "Create Opportunity + Link Products")
• Business rule enforcement (e.g., "Only 5 opportunities per contact")
• Cross-cutting concerns (e.g., audit logging)

Example

// Handler - Simple translation
const create = async (params) => {
  return opportunitiesService.createWithProducts(params.data);
};

// Service - Business logic
class OpportunitiesService {
  async createWithProducts(data) {
    const opportunity = await this.createOpportunity(data);
    await this.linkProducts(opportunity.id, data.product_ids);
    await this.logActivity(opportunity.id, 'created');
    return opportunity;
  }
}

5. Data Safety & Simplicity

Soft Deletes (Always)

// CORRECT
await supabase.from('contacts').update({ deleted_at: new Date() }).eq('id', id);

// WRONG - Never hard delete unless explicitly told
await supabase.from('contacts').delete().eq('id', id);

Explicit Composition (No Magic)

// CORRECT - Explicit composition order
export const createTasksHandler = () => {
  return withErrorLogging(           // 3. Outer: Catch errors
    withLifecycleCallbacks(          // 2. Middle: Transform
      withValidation(baseHandler),   // 1. Inner: Validate first
      tasksCallbacks
    )
  );
};

// WRONG - Auto-CRUD factory
export const tasksHandler = createAutoHandler('tasks'); // Hidden magic

See handler-patterns.md for composition examples.

Code Review Checklist

Before committing data provider changes, verify:

• New logic in handlers/ (not unifiedDataProvider.ts)?
• Writes target Base Table (not View)?
• Zod validation at Handler boundary?
• Business logic in Service layer?
• Errors mapped to React Admin format?
• Soft delete used (not hard delete)?
• Handler composition is explicit?

Anti-Patterns (BLOCK)

Reference Files

For detailed implementation guidance:

• migration-strategy.md - Strangler Fig details
• handler-patterns.md - Handler composition templates
• view-table-duality.md - Read/Write separation
• error-handling.md - Zod → React Admin error mapping

Skill Status: COMPLETE Line Count: < 200 (following 500-line rule) Progressive Disclosure: Reference files for implementation details