edr-platform/docs/MAP.md

Repo map — start here

Routing table for "where does X live". Read this before a repo-wide grep. Paths are from the repo root. The rules and traps are in ../CLAUDE.md; this file only answers where.

Pick your stack first

If you are working on…	Code lives in	Stack
Freight API / business logic	apps/edr-freight-api/src	NestJS + TypeORM
Freight customer UI	apps/edr-freight-web/portal	React + Vite + Mantine v9
Freight staff UI	apps/edr-freight-web/backoffice	React + Vite + Mantine v9
Passenger API	apps/edr-passenger-api	NestJS + Prisma
Passenger UI	apps/edr-passenger-web/*	Next.js
Payments (intents, webhooks)	apps/edr-payment-api	NestJS + TypeORM
Gateway integrations	packages/payment-providers	—
A shared type or enum	packages/types/src	rebuild after editing
A shared React component	packages/ui-common/src	—
A Nest decorator/filter/base class	packages/api-common/src	—

Freight API entry points

File	What it is
src/main.ts	Boot, port (PORT, falls back to 3001), global pipes
src/app.module.ts	Every module is registered here — the index of the API
src/config/database.config.ts	Connection, pooler search_path handling, iamEntities list
src/data-source.ts	Standalone DataSource used by migrations only (no autoLoadEntities)
src/migrations/	TypeORM migrations (39 files; check for timestamp clashes)
src/seed/freight-permissions.registry.ts	Every freight permission; declare before use
src/scripts/	One-off and seed:* scripts — several write real rows

Freight modules by domain

All under apps/edr-freight-api/src/modules/.

Domain	Modules
Booking & commercial	bookings contracts contract-templates consignments cargoes companies user-trade-access transit-agents shipping-lines
Warehouse & yard	warehouses facilities container-management
Rail operations	trains train-schedules train-scheduling train-sets wagons wagon-types locomotives routes scheduling scheduling-reschedule interchange-documents
Road / first & last mile	first-mile last-mile last-mile-requests drivers vehicles truck-types fleet-history fuel maintenance gps-tracking tracking
Money	billing payment exchange-settings
Identity & access	auth otp verifayda audit
Documents & files	files file-upload-settings signatures stamp-settings logo-settings minio
Comms	notifications notification-inbox support-chat support-content
Ops & admin	backoffice overview reports dropdown-settings rule-engine compliance procurement incidents import-operations eims ai health

Each module follows module → controller → service → repository, with entities/ and dto/ alongside.

Freight web

Pages live in src/pages/, roughly mirroring the API domains.

• portal (customer): bookings contracts consignments billing payments tracking accounts customers shipping-line support settings, plus MyPortalPage/, MySignaturePage.tsx, EDRFreightLandingPage.tsx.
• backoffice (staff): bookings contracts contract_templates consignments customers billing invoices documents fleet dashboard admin configuration auth ai, plus many single-file pages (AuditLogsPage.tsx, ActivityLogPage.tsx, BulkUploadPage.tsx, ContentManagementPage.tsx, …).

Shared components and theme come from @edr/ui-common — check there before writing one.

Tests

Suite	Location	Run with
Unit / spec	beside the code, *.spec.ts	pnpm --filter @edr/freight-api test
Freight e2e (Cypress, containerized)	e2e/freight	pnpm e2e:freight:ci
Passenger e2e	e2e/ + e2e/run.sh	pnpm test:e2e:passenger
UI e2e (Playwright)	e2e-ui/	pnpm test:e2e:ui
Integration	integration/	pnpm it:up, pnpm it:test

The freight e2e stack has no host Xvfb — use ci (containerized), not run/open. Its compose project name is fixed (edr-freight-e2e), so only one can run on this machine at a time.

Documents

Doc	Covers	Trust
../CLAUDE.md	The contract: rules, traps, definition of done	Current — fix in the same PR if wrong
docs/TESTING.md	Test strategy	—
docs/e2e-test-matrix.md, docs/ui-e2e-test-matrix.md	Coverage matrices	—
docs/ISSUES.md, docs/SOLUTIONS.md	Running log of problems and fixes	Historical
docs/uploads.md	File upload handling	—
docs/qa/edr-freight-qa-test-plan.md	QA test plan	—
../DEPLOYMENT.md	Deploy process	—
../ITMLS_DB_Design.md, ../orgstructure.md	Design notes	Historical
../E2E_TEST_REPORT.md, ../checkpoint.md	Point-in-time snapshots	Stale by design — dated artifacts, not references

Root-level *.sql and *.dump files are ad-hoc data snapshots, not part of the schema. Migrations are the only source of truth for schema.