# 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:

```javascript
// 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/`