# Decision Summary: Adopt Full TanStack SPA for FreightDesk SaaS
**Date:** 2026-06-08  
**Authors:** Hermes Agent (current analysis)  
**Scope:** Selection of front-end architecture for FreightDesk (real-time freight marketplace) supporting 1000+ users, 800 drivers, live tracking, bidding, negotiation, and pay팎.

## Context
- The app serves as a central freight marketplace connecting shippers, drivers, and agents.
- Real-time interactions required: bids, payments, vehicle status, negotiation.
- **Scale:** >1000 users, >800 drivers, multiple concurrent shippers.

## Why Full TanStack SPA Is Required
1. **Real-Time UX Is Non-Negotiable**
   - Bidding and negotiation cannot rely on page reloads.
   - Optimistic UI updates essential for user trust.
   - WebSocket + WebSocket queue handling required.

2. **Scalability & Maintenance**
   - Manual refresh/polling cannot handle 1000+ concurrent users.
   - SPA architecture decouples UI state from server rendering.
   - Reduces server load, enabling horizontal scaling.

3. **Future-Proofing for Automation**
   - Automation (AI-driven pricing) will need direct API calls and event-driven flows.
   - TanStack’s composable components make incremental feature integration easy.
   - Shared state layer enables future integration with mobile apps (React Native).

4. **Competitive Advantage**
   - Modern SaaS experiences demand client-side rendered interfaces.
   - Users expect instant feedback (no “loading” indicators).
   - TanStack ecosystem (Query, Router) offers advanced data handling and routing.

## Trade‑offs & Mitigations
| Trade‑off | Mitigation |
|----------|------------|
| Longer initial setup | Immediate CI/CD pipeline for build steps |
| Steeper learning curve | Additional onboarding time, but pays off quickly |
| Build step dependency | Implemented via CI/CD; mandatory for CI/CD plans |

## Conclusion
Given the real‑time, multi‑user nature of FreightDesk’s operation, **adopting a full TanStack SPA architecture is the optimal technical and business decision**. It enables real-time interactions, scalability, and maintainability for future growth.

**Recommended next steps:**
1. Continue migrating components to React (Loads, Shippers, Vehicles).
2. Implement real-time bid & negotiation flow via WebSocket.
3. Deploy CI pipeline for automated builds.
4. Integrate with supabase realtime channels for event-driven updates.
5. Eventually replace remaining EJS pages with SPA components.

**Commit `AGENT_DECISION.md` to track this decision.**

---

**Final submit: commit to repository to make decision visible to other agents.**