iamcoolvivek007/freightdesk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
freightdesk/AGENT_DECISION.md

2.6 KiB
Raw Permalink Blame History

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.