Engineering record — internal detail. The manual is authoritative for product behaviour.
System architecture & stack
What the platform is built from today: frameworks, datastore, auth, storage, jobs, AI, testing and the design contract.
Product shape
A multi-tenant logistics finance application. One workspace (organisation) owns customers, vendors, warehouses, products, containers, trips and the full double-entry ledger. Role and department decide which modules a member sees, and the same predicate drives both sidebar visibility and server route authorisation.
The surface splits into three worlds: a public marketing and documentation site, an authentication surface, and the dashboard (finance, port, fleet, inventory, analytics, administration, superadmin).
Stack
| Layer | Choice | Version |
|---|---|---|
| Framework | Next.js (App Router) | 16.2.7 |
| UI runtime | React | 19.2.4 |
| Styling | Tailwind CSS v4 + shadcn/Radix + tw-animate-css | ^4 |
| Database | Neon Postgres (serverless driver) | @neondatabase/serverless ^1.1.0 |
| ORM | Drizzle ORM + drizzle-zod, drizzle-kit migrations | 0.45.x / kit 0.31.10 |
| Auth | Better Auth + @better-auth/infra | 1.6.27 |
| Object storage | Cloudflare R2 via AWS SDK v3 + presigner | ^3.1098.0 |
| Background jobs | Trigger.dev | ^4.5.9 |
| Rate limiting | Upstash Redis + @upstash/ratelimit | ^2.0.8 |
| AI | Vercel AI SDK with OpenAI and Anthropic providers | ai ^7.0.17 |
| Resend + React Email | ^6.16.0 | |
| Documents | @react-pdf/renderer, pdf-parse, tesseract.js OCR, ExcelJS | — |
| Forms and validation | react-hook-form + zod | zod ^4.3.6 |
| Client state | Zustand + TanStack Query and Table | — |
| Charts | Recharts | ^3.8.1 |
| Testing | Vitest (unit), Playwright (e2e) | — |
| Messaging | Telegram bot webhook at /api/telegram/webhook | — |
Watch
Documentation drift to resolve
AGENTS.md still names Supabase and @supabase/ssr as the database and auth stack. The dependency manifest and the migration records say otherwise: the datastore is Neon and auth is Better Auth. AGENTS.md should be corrected so agents do not reintroduce Supabase patterns.
Architectural invariants
- One tenant boundary: every query is organisation-scoped, and cross-org references are rejected at the action layer.
- The ledger is append-only: posted entries are never edited, only reversed.
- Every automatic posting is idempotent with respect to its business event.
- The AI layer is read-only for data and can propose, never commit; all commits pass through a human approval action that writes an audit entry.
- Money conversion always uses a stored rate; a missing rate is an error, never a silent 1.0.
Design contract
DESIGN.md is the authoritative frontend specification — the split-flap concourse board world. Any task that creates, modifies or restyles a component, page or interaction must read it first. It governs tokens, type scale, section grammar, motion and the explicit list of patterns not to reintroduce.