doc[architecture]: propose hybrid UI strategy – TanStack SPA for admin, EJS for static pages, shared Supabase service

ARCHITECTURE_DECISION.md

@@ -0,0 +1,69 @@
+# 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/`