mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-26 18:42:49 +00:00
97 lines
5.5 KiB
Markdown
97 lines
5.5 KiB
Markdown
# 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.
|