freightdesk/ARCHITECTURE_DECISION.md

Architecture Decision: UI Framework Strategy

Situation Overview

Two agents are pursuing different approaches for the FreightDesk UI:

Approach	Proponent	Description
EJS + React Widgets	OWL Agent	Server-rendered EJS templates with embedded React components for dynamic parts
Full TanStack SPA	Hermes Agent	Complete client-side React application using TanStack Query + Router

Comparative Analysis

Criteria	TanStack SPA	EJS + Widgets	Recommendation
User Experience	Zero reloads, optimistic updates, instant feedback	Page reloads for every action	TanStack
Real-time Updates	Built-in via TanStack Query	Requires polling or WebSockets	TanStack
Development Speed	Higher initial setup, faster iteration	Faster for simple pages	EJS (short-term)
Maintenance Cost	Lower (consistent patterns)	Higher (mixed paradigms)	TanStack
Scalability	Excellent for complex workflows	Brittle with complexity	TanStack
Learning Curve	Moderate (React ecosystem)	Low (familiar Node.js)	EJS (short-term)
Deployment	Build step required	Direct deployment	EJS

Proposal: Hybrid Unified Architecture

Phase 1: Admin Dashboard (TanStack SPA)

• Scope: Internal admin panel (loads, shippers, vehicles, payments)
• Components: Already started (LoadsList, ShippersList)
• Benefits: Real-time updates, consistent UX, type safety

Phase 2: Client Portal Integration

• Scope: Shipper/driver portal
• Approach: Reuse TanStack components from Phase 1
• Benefits: Same UI logic, easier maintenance

Phase 3: Static Pages (EJS)

• Scope: Setup wizard, login, static content
• Approach: Keep EJS for simple, non-interactive pages
• Benefits: Fast deployment, no build step needed

Shared Service Layer

Create services/supabaseService.js to share data logic:

// Shared between EJS and React
export const loadsService = {
  getList: () => supabase.from('loads').select('*'),
  getById: (id) => supabase.from('loads').select('*').eq('id', id),
  create: (data) => supabase.from('loads').insert(data),
};

Next Steps

1. Decision Point: Choose the hybrid approach above
2. Immediate Actions:
   • Merge audit logging from OWL into agent/default/soft-delete-audit
   • Create shared service layer
   • Document component reuse strategy
3. Long-term:
   • Migrate all interactive pages to TanStack
   • Keep EJS only for static/setup pages

References

• OWL's recent work: agent-owl-audit-portal, agent-owl-roadmap
• Hermes' current work: agent/tanstack-migration
• Existing EJS pages: /webapp/src/views/pages/