# 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