# 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`](../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.