Product Architecture & Build Plan

Pillar: product-architecture | Date: March 2026
Scope: Technology stack decisions and architecture for a Node.js/Supabase/Tailwind collision repair superapp. UX and UI vision for shop environments: dark mode default, large touch targets for shop floor use, Tesla-meets-fintech aesthetic, PWA for iPad and mobile web, responsive desktop experience. Module prioritization and build order for maximum early market impact. MVP definition scoped to win a pilot with a large multi-location MSO. Technical architecture challenges specific to this domain: real-time sync across shop locations (Supabase Realtime), offline-first capability for shop floor where connectivity is unreliable, photo and document management at scale (damage photos, DVI photos, completed repair documentation), insurance EDI integration patterns, parts ordering API integrations with major suppliers. Multi-tenant and multi-location data architecture. Integration API design for coexistence with CCC/Mitchell during the adoption transition period.
Sources: 25 gathered, consolidated, synthesized.

Table of Contents

1. Technology Stack & Architecture Philosophy
2. Multi-Tenant & Multi-Location Data Architecture
3. Row Level Security Implementation
4. Real-Time Synchronization (Supabase Realtime)
5. Offline-First Architecture & PWA
6. UX/UI Design for Shop Floor
7. Photo & Document Management at Scale
8. Insurance EDI & Estimating System Integration
9. Parts Ordering API Integrations
10. MSO Pilot Requirements & MVP Prioritization
11. Superapp Architecture & Legacy System Coexistence
12. Module Build Order & Phase Plan

Section 1: Technology Stack & Architecture Philosophy

The production-validated stack for a Node.js/Supabase collision repair superapp converges on a small set of well-tested primitives. Supabase provides the unified backend infrastructure — PostgreSQL, Auth (GoTrue), auto-generated REST/GraphQL (PostgREST), WebSocket Realtime, S3-compatible Storage, and serverless Edge Functions (Deno) — under a single managed platform.^[18] The frontend targets Next.js 14+ with the App Router, TypeScript, and Tailwind CSS, deployed on Vercel with Cloudflare Workers handling edge routing.^[8]

Key finding: "Start with a Monolithic architecture (like a Next.js Full Stack app). Only transition to microservices when performance bottlenecks specifically demand separation." The superapp microservices architecture describes the target end-state, not the starting point.^[8]

Recommended Production Stack

Supabase Core Components Relevant to Collision Repair

Superapp End-State Architecture (6 Core Components)

The target architecture for a collision repair superapp requires six foundational components^[17]:

1. Microservices Architecture — Independent scaling of work orders, estimating, parts, payments, analytics modules
2. API Gateway Layer — Authentication, routing, orchestration; protocol translation between CIECA/CCC/OEC APIs and internal services
3. Mini-App Framework — Partner/third-party developer integration infrastructure
4. Unified Authentication — Single sign-on eliminating 6+ separate shop system logins
5. Data Management Layer — Polyglot persistence: Postgres (transactional), object storage (photos), Redis (sessions)
6. Integration Framework — Legacy system coexistence with CCC ONE and Mitchell during the adoption transition period

See also: Adoption & Migration

Production Best Practices (Supabase)

• Never use service_role keys in client code — server-side only^[18]
• Start normalized; denormalize only when proven performance issues^[18]
• Use Supavisor connection pooling from day one^[18]
• Monitor slow queries with pg_stat_statements^[18]
• Enable RLS only on necessary tables; use channel filters (location_id, wo_id) to minimize subscription overhead^[18]
• Automated daily backups; use supabase db push for migrations^[18]

Section 2: Multi-Tenant & Multi-Location Data Architecture

Multi-tenancy for a collision repair superapp targeting MSOs requires a two-level hierarchy: the organization (e.g., "ABC Auto Group") is the top-level tenant, and locations (individual shops) are first-class entities below it. All business data rows carry both organization_id and location_id, with RLS enforcing isolation at the database layer.^[8][1]

Key finding: Three non-negotiable domain invariants apply to every multi-tenant schema: (1) "Every row is owned by one tenant," (2) "A user can belong to multiple tenants," (3) "Tenant ID is required, indexed, and part of uniqueness constraints." Violating any one of these invariants creates cross-tenant data leaks.^[1][10]

Tenancy Model Comparison

Multi-Location Schema Design

The canonical MSO hierarchy uses three tables — organizations, locations, memberships — plus dual foreign keys on every business data table:^[8][11]

-- Organization (top-level tenant, e.g. "ABC Auto Group")
organizations: id, name, slug

-- Locations (individual shops within the organization)
locations: id, organization_id, name, address JSONB

-- Memberships (users connected to orgs, with optional location scoping)
memberships: id, user_id, organization_id, role TEXT, location_ids UUID[]
-- role values: 'owner', 'manager', 'tech', 'advisor', 'viewer'
-- location_ids: NULL = access to all locations

-- All business data tables carry both keys
work_orders: id, organization_id, location_id, ...

Hierarchical Security Model

Tenant Context Resolution Methods

Every request must resolve tenant scope before processing. Four supported mechanisms:^[1][10]

1. Subdomain routing (acme.yourapp.com)
2. Custom domain mapping (for white-labeled MSO deployments)
3. Session/JWT tenant claim (app_metadata.tenant_id) — primary mechanism for Supabase Auth
4. API keys bound to tenant (for parts supplier / insurance integrations)

Authentication Architecture (Two-Phase)

Two-phase auth flow required for multi-tenant B2B SaaS:^[1][10]

1. Phase 1: Prove identity — global user authentication (email/password, magic link)
2. Phase 2: Establish tenant context — discover memberships, select active location/org, apply tenant-specific policies

Known Supabase Auth Limitation: Supabase Auth enforces global email uniqueness — one email = one account across the entire platform. If the same email needs to belong to multiple tenants (e.g., a vendor who services multiple MSOs), an internal email mapping workaround is required.^[23]

Compliance Requirements for MSO Customers

Noisy-Neighbor Mitigation (Shared Runtime)

Shared runtime requires tenant-level fairness controls to prevent one high-volume MSO from degrading others:^[1][10]

• Per-tenant rate limiting and API quotas
• Per-tenant concurrency caps on background jobs
• Job queues partitioned and weighted by tenant
• Tenant-level kill switches — disable a single tenant without product outage

Safe Schema Migration Pattern (Expand → Backfill → Contract)

Live schema changes with zero downtime use a three-phase pattern:^[1]

1. Add nullable columns/tables (expand) — backward-compatible
2. Deploy code writing both old and new fields simultaneously
3. Backfill existing rows per-tenant in batches
4. Deploy code reading new field only
5. Remove old field (contract)

See also: Regulatory Compliance

Section 3: Row Level Security Implementation

Row Level Security attaches policies to PostgreSQL tables that function as implicit WHERE clauses on every query — enforcing tenant isolation at the database layer regardless of application code errors.^[12] For a collision repair platform where a cross-tenant data leak could expose an MSO's competitive RO data to a rival shop, database-layer enforcement is non-negotiable.

Key finding: RLS performance optimization can deliver 99.94% query speed improvements when policy columns are indexed and functions are wrapped in SELECT to cache results. Unoptimized RLS can make a production system unusably slow at scale.^[12]

RLS Performance Optimization Benchmarks

Multi-Tenant RLS Policy Pattern

Extract tenant context from JWT app_metadata via helper function, then apply uniformly across all business tables:^[8][23]

CREATE OR REPLACE FUNCTION auth.tenant_id()
RETURNS text LANGUAGE sql STABLE AS $$
  SELECT nullif(
    ((current_setting('request.jwt.claims')::jsonb ->> 'app_metadata')::jsonb ->> 'tenant_id'), ''
  )::text
$$;

-- Apply to every tenant-scoped table
CREATE POLICY tenant_isolation ON repair_orders
  USING (auth.tenant_id() = tenant_id);
CREATE POLICY tenant_insert ON repair_orders
  WITH CHECK (auth.tenant_id() = tenant_id);

Role-Based Authorization Helper Functions (LockIn Pattern)

Organization membership checks implemented as SECURITY DEFINER functions bypass RLS on the membership table itself, preventing infinite recursion:^[11]

-- Check membership
is_organization_member(org_id TEXT, user_id TEXT) RETURNS BOOLEAN

-- Check admin rights
is_organization_admin(org_id TEXT, user_id TEXT) RETURNS BOOLEAN
-- role IN ('admin', 'owner')

Required Composite Indexes for Repair Order Data

CREATE INDEX ON repair_orders (tenant_id, created_at DESC);
CREATE INDEX ON repair_orders (tenant_id, location_id, status);
CREATE INDEX idx_member_user_org ON public.memberships(user_id, organization_id);

Tenant_id must appear first in all composite indexes — all hot queries filter by tenant before any other dimension.^[23][11]

RLS Security Principles

Section 4: Real-Time Synchronization (Supabase Realtime)

Supabase Realtime is built on Elixir compiled to Erlang, using Phoenix Framework and Phoenix.PubSub with the PG2 adapter. This architecture enables millions of concurrent WebSocket connections via lightweight Erlang processes rather than OS-level threads — the same foundation that powers WhatsApp's messaging infrastructure at scale.^[3][16]

Key finding: "For offline-first scenarios, Realtime alone is insufficient — need local persistence layer + sync queue." Real-time sync and offline-first are complementary, not interchangeable — a shop floor iPad requires both.^[3]

Three Realtime Features and Collision Repair Use Cases

Multi-Region Global Cluster

Supabase Realtime runs as a globally distributed Elixir cluster:^[3][16]

• "A client connected to a Realtime node in the United States can send a message to another client connected to a node in Singapore"
• Messages route "via the shortest path possible"
• Each region maintains at least two nodes for redundancy — if one goes offline, the other reconnects and continues streaming
• Multi-location MSO implication: Location A (East Coast) and Location B (West Coast) connect to nearest regional nodes; cross-location messages route automatically with no application-level configuration

Connection Limits by Supabase Plan

Data Retention

The realtime.messages table is partitioned daily; partitions are retained 3 days before deletion — efficient cleanup without row-level deletions.^[3][16] This is sufficient for event replay on technician iPad reconnection after intermittent shop floor connectivity loss.

Channel Authorization (Added 2024)

Supabase added Broadcast and Presence Authorization in 2024, enabling RLS-style policies on channels:^[19]

• Per-location channel access control (technicians see only their location's board)
• Role-based real-time subscriptions (tech vs. manager vs. owner visibility)
• Tenant-isolated real-time streams (no cross-MSO broadcast leakage)

Critical implementation note: Use scoped channel names — shop:${shopId}:work-orders — and ensure clients subscribing to Postgres Changes have appropriate RLS policies. Without scoped channels, cross-tenant data leakage is possible even with application-level auth.^[3]

Section 5: Offline-First Architecture & PWA

Shop floor connectivity is unreliable — large metal buildings, WiFi dead zones near spray booths, technicians moving between bays. An offline-first architecture is not a feature; it is a foundational reliability requirement for any shop floor iPad application. The PWA approach delivers ~75% development cost savings vs. separate native iOS/Android apps while achieving the same offline capability.^[4]

Key finding: "Offline-first favors low latency over strict consistency" — this is acceptable for shop workflow status updates and DVI capture, but NOT for parts inventory or payment processing, which must be online-only.^[14]

Three-Layer Offline Architecture

Caching Strategies by Asset Type

IndexedDB Schema for Shop Floor

Four stores required for offline DVI and RO workflows:^[14]

• work_orders store — localId as keyPath; indexes on updated_at, server_id
• photos store — localId, work_order_id; blob storage for pending uploads
• syncQueue store — pending mutations with type, entity, clientId, changes, timestamp
• SQLite/WASM alternative (2025) — sql.js and wa-sqlite enable full relational local DB; superior for complex shop data relationships^[14]

Sync Queue / Outbox Pattern

Every user mutation must write to local IndexedDB before network transmission. Include idempotency keys to prevent duplicate effects on retry.^[20][4] The Background Sync API flushes queued writes when connectivity returns — even if the browser tab is closed.^[4]

Conflict Resolution by Data Type

Background Sync API Constraints (Chrome/Safari)

Background Fetch API (Large Photo Uploads)

For batch photo upload after connectivity return — shows persistent browser UI with user-visible progress. Continues even if the iPad screen locks. Suitable for end-of-day DVI photo sync when the tech returns to the WiFi area.^[4]

PWA Market Data

• Global PWA market: $1.46 billion (2023), projected 30.5% CAGR through 2030^[4]
• ~1 in 5 web properties using service workers as of 2025^[4]
• Development cost savings: ~75% vs. separate native iOS/Android apps^[4]

Section 6: UX/UI Design for Shop Floor

Auto body shop environments impose extreme constraints on interface design: technicians wear gloves, grease and debris impair touch accuracy, lighting ranges from direct sunlight near bay doors to dim corners near frame machines, and iPads are mounted on rolling carts or walls in both portrait and landscape orientations. Standard consumer-grade UI patterns fail in this environment.^[7][24]

Key finding: "A digital solution that will be successful cannot be designed in a boardroom without input from the users in the field — it is imperative to involve end-users early on in the design process." Field service UX redesigns that cut taps in half deliver the most measurable ROI for shop adoption.^[7]

Dark Mode: Strategic Default

82% of mobile users have adopted dark mode.^[24] For the "Tesla-meets-fintech" aesthetic targeting collision repair shops:

• Shop floors have harsh/bright lighting creating screen glare on light backgrounds^[24]
• Technicians use devices for sustained DVI sessions — dark mode reduces eye fatigue^[7]
• Dark mode signals sophistication; aligns with professional B2B positioning^[24]
• Implementation cost: ~1.1–1.2× frontend work when designed dark-first^[24]
• Critical: Retrofitting dark mode post-launch is far more expensive — dark-mode-first is mandatory from day one^[24]

Touch Target Standards

Location-Based Sizing on Screen

Touch precision varies by screen location — sizing must compensate:^[24]

• Top of screen: 11mm (42px) minimum — least precise zone
• Bottom of screen: 12mm (46px) minimum — highest error rates (thumb extension)
• Center: 7mm (27px) minimum — most user precision
• Maximum 5 items in bottom navigation bar^[24]

Priority Tap Hierarchy for Shop Floor

Industrial UX Principles (80/20 Rule)

"20% of the functionality is used 80% of the time." Critical actions must be 1–2 taps from any screen.^[7] Five principles for shop floor interfaces:

1. Glove-Friendly Targets — 64×72px for primary actions; clear raised/bordered visual affordance^[7]
2. Minimize Data Entry — VIN scanning (camera/barcode) over manual entry; pre-populate fields from estimate data^[7]
3. High Contrast & Large Typography — Minimum 16px body text, 20px+ for primary actions; avoid subtle color differentiation^[7]
4. Interaction Efficiency — Target: cut taps required for booking/status update "in nearly half"^[24]
5. Environment Analysis First — Design with technicians in the actual shop, not in a boardroom^[7]

Tablet Layout Patterns

Industrial UX Design Process (5 Steps)

1. Environment analysis — understanding users and operating conditions on the actual shop floor^[7]
2. Early mockup design — collaborating with technicians and estimators, not just managers^[7]
3. Test scenarios aligned with project milestones (check-in, DVI, status update, parts ordering)^[7]
4. Parallel development — interface logic built alongside backend systems^[7]
5. Iterative testing with real production workers — not QA engineers^[7]

Measurable UX Success Criteria

Define concrete, measurable hypotheses before development:^[7]

• "Reduce RO status update time from 3 minutes to 30 seconds"
• "Eliminate 90% of paper-based check-in forms"
• "Reduce parts ordering errors from 35% to <5%"

Section 7: Photo & Document Management at Scale

A large MSO generates 60,000–150,000 photos per month at scale (10 locations × 200–500 ROs × 30 photos average = 300GB–750GB monthly storage growth).^[9] Photo management is not a secondary feature — it is a primary workflow touchpoint for both DVI and insurance supplement documentation.

Key finding: Supabase Storage's S3-compatible architecture with PostgreSQL metadata enables a capability unique among basic cloud storage solutions: querying "all photos for RO-12345" with a single SQL join rather than manual file path parsing. This enables real-time customer portals and insurance adjuster access with standard RLS tenant isolation.^[9]

Bucket Organization Strategy

File Organization Path Structure

vehicle-photos/
  {tenant_id}/
    {location_id}/
      {repair_order_id}/
        intake/         damage_001.jpg, damage_002.jpg
        repair_progress/   day1_001.jpg
        completion/        final_001.jpg

documents/
  {tenant_id}/
    {repair_order_id}/
      estimate.pdf, supplement_1.pdf, final_invoice.pdf, authorization_signed.pdf

First path segment is always tenant_id — enables RLS storage policy using storage.foldername(name)[1].^[9]

Image Transformation Capabilities (Pro Plan)

Scale Projections for Large MSO

Cost Optimization Strategies

1. Client-side compression before upload — reduce to 1–2MB per photo before reaching Supabase^[9]
2. Use Supabase image transformations for thumbnails rather than storing separate copies^[9]
3. Lifecycle rules: archive completed RO photos to cold storage after 90 days^[9]
4. Immutable cache headers (cache-control: max-age=31536000) for completed repair photos^[9]
5. At very high volume: AWS two-bucket pattern (upload → Lambda compress → delivery) — can reduce S3 Standard storage by 90%+^[9]

DVI Workflow Integration

Complete end-to-end DVI photo flow:^[9]

1. Technician opens DVI on iPad
2. Camera capture → immediate upload to Supabase Storage (or queue in IndexedDB if offline)
3. Photo URL stored in repair_order record; triggers Realtime broadcast to production board
4. Customer/insurance portal shows photos in real-time via CDN-delivered URLs
5. Insurance adjuster can request supplement based on photos without phone call

Video Support (DVI Videos)

• Store in separate dvi-videos bucket; 25MB per-file limit is too small for videos — use signed upload URLs directly to object storage^[9]
• Transcoding pipeline (AWS Elastic Transcoder or Cloudflare Stream) for multi-resolution delivery^[9]
• HLS streaming for long-form DVI video playback on insurance portals^[9]

Section 8: Insurance EDI & Estimating System Integration

The Collision Industry Electronic Commerce Association (CIECA) develops the electronic communication standards underlying all insurer-to-shop and estimating-system-to-shop data flows. "The highly-automated processes most insurers use to assign vehicles to repair shops and to receive estimates and invoices are driven by CIECA Standards."^[5] Any new platform that cannot speak these standards is functionally locked out of DRP programs.

Key finding: "CCC and Mitchell own the estimate data format. Any new superapp needs to be a 'layer on top' during transition — import estimates from CCC/Mitchell, manage the shop workflow, then export invoices back." Full CIECA compliance is a prerequisite, not a differentiator.^[5]

CIECA Technical Formats

CCC Secure Share API

A cloud-based API network enabling "more than 22,000 collision repairers to connect to apps using the CIECA BMS data standard."^[5][13]

Mitchell RepairCenter Transactional API

Enables "near real-time" access to shop-specific job data:^[21]

CCC ONE & Mitchell Market Position

Primary Insurance Integration Use Cases (Priority Order)

See also: Regulatory Compliance

Section 9: Parts Ordering API Integrations

Parts ordering remains the most manual, error-prone workflow in collision repair. "For most shops, parts orders are still handled by phone or fax" with electronic commerce adoption below 20%.^[6] The quality problem is severe: "About 30 percent or 40 percent of parts that appear on estimates are incorrect," primarily due to incomplete information capture rather than wrong OE numbers.^[6]

Key finding: 30–40% of parts on estimates are incorrect, costing shops in wrong-order returns, delay penalties, and labor rework. A new platform that validates part numbers against VIN data before ordering can eliminate this entirely — a quantifiable ROI argument for MSO pilots.^[6]

Major Parts Ordering Platforms

Integration Architecture Pattern

Estimate created → Part line items extracted →
Query parts APIs by VIN + part description →
Show availability/pricing across OEM/aftermarket/recycled →
One-click order → Parts received confirmation →
RO updated with actual parts costs

Data required for accurate parts ordering: VIN, OEM part numbers from estimate, Year/Make/Model, part description, quantity, shop location (for delivery/pickup logistics).^[6]

Key Technical Challenges

See also: Workflow Pain Points

Section 10: MSO Pilot Requirements & MVP Prioritization

The auto collision repair management software market reached $3.723 billion in 2024, projected to grow to $25.61 billion by 2035 at a 19.16% CAGR. The cloud-based segment dominates at $2.5 billion (2024) and is projected to reach $17.5 billion (2035). The large facilities/MSO segment is the fastest-growing and highest-value category, projected at $14.61 billion by 2035.^[22]

Key finding: MSO critical pain points are operational, not technical: inability to monitor multiple locations simultaneously, customer/vehicle data fragmented by location, inconsistent technician processes across shops, and growth friction when opening new locations. The MVP must solve all four to win a pilot.^[25]

MSO Critical Pain Points

MVP Feature Prioritization (3 Phases)

MSO Pilot Timeline (Empirical Data)

Enterprise MSO Differentiation Criteria (Shop-Ware Model)

Key capabilities that distinguish MSO-class software from single-shop platforms:^[25]

• One unified customer history across all locations — no logging in/out of different systems
• Tracks unsold service recommendations and carries them between locations with links to original ROs
• Unlimited custom reports; slice by location, compare branches, regional groups; schedule email delivery
• "Every staff member's activity on every repair order and parts purchase" tracked with granular detail
• Access-based (not just role-based) permissions — individualized controls per employee

See also: Market Economics; Pricing & Business Model

Section 11: Superapp Architecture & Legacy System Coexistence

The strategic architecture challenge is not building a better SMS — it is displacing deeply entrenched incumbents (CCC ONE at 25,000+ shops; Mitchell at 650+ with Crash Champions alone) while maintaining interoperability during the transition period. The work order is the data spine that makes this possible: a single source of truth that ingests estimates from CCC/Mitchell and orchestrates every downstream workflow.^[17]

Key finding: "Start with the core RO workflow as the unified data spine, then layer each additional capability module on top. The single source of truth for the work order enables true superapp benefits — parts auto-ordered from estimate, customer texts triggered by status changes." This is the architecture pattern that converts a feature-competitive SMS into a platform.^[17]

Integration Patterns for CCC/Mitchell Coexistence

Superapp Benefits Over Point-Solution Fragmentation

Polyglot Persistence Architecture

Section 12: Module Build Order & Phase Plan

The build order is constrained by data dependencies: the work order entity is the spine that everything else references. Multi-tenant infrastructure must exist before any business logic is built, because retrofitting RLS onto existing tables is significantly more complex than enabling it from day one.^[11][1]

Key finding: The highest-risk architectural decision is the multi-tenant schema — getting organization/location/membership right before any business data exists is far cheaper than the Expand → Backfill → Contract migration pattern required to add tenant_id columns to production tables with live data.^[1]

Phase 0: Infrastructure Foundation (Weeks 1–4)

Phase 1: Core Work Order Module (Weeks 5–12)

Phase 2: DVI + Photo Module (Weeks 8–14)

Phase 3: Integrations (Weeks 12–20)

Phase 4: Financial Workflows (Weeks 18–26)

Critical Architecture Decisions Already Settled

Home