69 lines
No EOL
2.8 KiB
Markdown
69 lines
No EOL
2.8 KiB
Markdown
# 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/` |