iamcoolvivek007/freightdesk
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
freightdesk/ARCHITECTURE_DECISION.md
FreightDesk 8e67cb98ae
Some checks are pending
FreightDesk CI/CD / Lint & Test (push) Waiting to run
Details
FreightDesk CI/CD / Build Docker Image (push) Blocked by required conditions
Details
FreightDesk CI/CD / Deploy to Coolify (push) Blocked by required conditions
Details
[OWL] REST API layer + Portal user management 
REST API (/api):
- Full CRUD for loads, shippers, vehicles, payments
- Dashboard stats endpoint (/api/stats)
- Pagination, filtering, sorting on all list endpoints
- Role-based access control on write operations
- Soft delete support

Portal User Management (/portal-users):
- Admin UI to create shipper/driver portal accounts
- Link portal users to existing shippers/drivers
- Enable/disable accounts
- Reset passwords
- Lists all portal accounts with status

Architecture decision documented: keeping EJS+React CDN widgets as primary
2026-06-08 00:49:23 +00:00

2.1 KiB
Raw Blame History

FreightDesk — Final Architecture Decision

Date: 2026-06-07 Status: Active Discussion Participants: OWL (owl-alpha), Hermes (default)

Decision

Keep EJS server-rendered + React CDN widgets as the primary architecture.

Rationale

Factor Assessment
Project scope Single freight agent, simple CRUD, one VPS. Not a multi-tenant SaaS.
Time to complete EJS+widgets is 90% done. SPA would take weeks of parallel work.
Deployment simplicity One codebase, one build, one Coolify deploy.
Security Server-side sessions (HttpOnly cookies) > client-side Supabase keys in browser
Feature completeness EJS version has audit, portal, CI/CD, tests, observability. SPA branch deletes these.
Code quality EJS code is reviewed and tested. React code has bugs (documented in ARCHITECTURE.md).
Maintenance Both agents can work on same EJS views without merge conflicts.
Future migration Can migrate to SPA later if needed. EJS views can coexist with React widgets during transition.

What We Keep from Hermes' Suggestions

  1. Shared service layer — Good idea. Create services/ modules that both frontends can consume.
  2. REST API layer — Build JSON API endpoints alongside EJS views. Makes future SPA migration possible.
  3. Client portal — Shipper/driver portal done in EJS with server-side auth. No need for React here.
  4. Audit logging — Cherry-picked from Hermes' branch, already on master (migration 004).

What We Build Next

  1. API layer — REST endpoints for loads, shippers, vehicles, payments (JSON)
  2. Email notifications — Load status updates via email
  3. Portal user management — Admin UI to create shipper/driver portal accounts
  4. Invoice PDF polish — Better templates, batch invoice generation
  5. Dashboard charts — Recharts via CDN for visual analytics
  6. WhatsApp parser improvements — Better regex, support more message formats
  7. Mobile responsiveness — Ensure all views work well on phone screens
  8. i18n — Hindi + Malayalam language support