edr-platform/README.md

# EDR Passenger API

NestJS REST API for the Ethio-Djibouti Railway passenger platform. Handles booking lifecycle, seat inventory, payments (Telebirr, CBE Birr, eBirr, Card, Wallet), loyalty, live tracking, notifications, and support.

## Tech Stack

- **Runtime**: Node.js 20, TypeScript
- **Framework**: NestJS 11
- **Database**: PostgreSQL via Prisma ORM
- **Auth**: JWT (Passport)
- **Docs**: Swagger / OpenAPI (`/api-docs`)
- **Package manager**: pnpm 9

## Prerequisites

- Node.js >= 20
- pnpm >= 9 (`npm i -g pnpm`)
- PostgreSQL 15+

## Quick Start

```bash
# 1. Install dependencies (from monorepo root)
pnpm install

# 2. Copy and fill environment variables
cp apps/edr-passenger-api/.env.example apps/edr-passenger-api/.env

# 3. Generate Prisma client
pnpm --filter @edr/passenger-api run prisma:generate

# 4. Run database migrations
pnpm --filter @edr/passenger-api run prisma:migrate

# 5. Seed the database
pnpm --filter @edr/passenger-api run prisma:seed

# 6. Start in development mode
pnpm --filter @edr/passenger-api run dev
```

API runs at **http://localhost:4000**
Swagger UI at **http://localhost:4000/api-docs**

## Environment Variables

| Variable              | Description                          | Default                          |
| --------------------- | ------------------------------------ | -------------------------------- |
| `PORT`                | HTTP port                            | `4000`                           |
| `DATABASE_URL`        | PostgreSQL connection string         | —                                |
| `JWT_SECRET`          | JWT signing secret                   | —                                |
| `JWT_EXPIRES_IN`      | JWT expiry                           | `7d`                             |
| `FRONTEND_URL`        | Allowed CORS origin (web app)        | `http://localhost:3000`          |
| `PORTAL_URL`          | Allowed CORS origin (portal)         | `http://localhost:3001`          |
| `SENDGRID_API_KEY`    | SendGrid key for email notifications | _(optional — logs if absent)_    |
| `SENDGRID_FROM_EMAIL` | Sender email address                 | `noreply@edr-platform.com`       |

## API Modules

| Tag            | Base path         | Description                              |
| -------------- | ----------------- | ---------------------------------------- |
| Auth           | `/auth`           | Register, login, JWT                     |
| Stations       | `/stations`       | Station directory                        |
| Fleet          | `/fleet`          | Train services, coaches, seat batches    |
| Schedule       | `/schedule`       | Trips, fare rules, status updates        |
| Search         | `/search`         | Trip search, fare quotes                 |
| Seats          | `/seats`          | Seat maps, holds, releases               |
| Booking        | `/bookings`       | Create, retrieve, cancel bookings        |
| Payment        | `/payments`       | Initiate payment, refunds, methods       |
| Tickets        | `/tickets`        | QR ticket generation and validation      |
| Passenger      | `/passengers`     | Profiles, traveler profiles, saved routes|
| Notifications  | `/notifications`  | In-app notifications                     |
| Loyalty        | `/loyalty`        | Points, tiers, rewards                   |
| Wallet         | `/wallet`         | Balance, top-up, ledger                  |
| Promotions     | `/promos`         | Active promos, promo code validation     |
| Live Tracking  | `/live`           | Real-time trip status, crowd signals     |
| Support        | `/support`        | FAQ, chat conversations                  |
| Dashboard      | `/dashboard`      | Home screen aggregate                    |

## Seed Credentials

After running `prisma:seed`:

| Role      | Email                    | Password      |
| --------- | ------------------------ | ------------- |
| Passenger | `kelemu@email.com`       | `password123` |
| Admin     | `admin@edr-platform.com` | `admin123`    |

## Docker

```bash
# Build image (run from monorepo root)
docker build -f apps/edr-passenger-api/Dockerfile -t edr-passenger-api .

# Run
docker run -p 4000:4000 --env-file apps/edr-passenger-api/.env edr-passenger-api
```

## Scripts

| Command                | Description                    |
| ---------------------- | ------------------------------ |
| `pnpm dev`             | Start with hot-reload          |
| `pnpm build`           | Compile to `dist/`             |
| `pnpm start`           | Run compiled output            |
| `pnpm test`            | Run unit tests                 |
| `pnpm lint`            | ESLint                         |
| `pnpm type-check`      | TypeScript type check          |
| `pnpm prisma:generate` | Regenerate Prisma client       |
| `pnpm prisma:migrate`  | Run pending migrations         |
| `pnpm prisma:seed`     | Seed the database              |

## Project Structure

```
src/
├── common/           # PrismaService, JwtGuard, JwtStrategy, filters, interceptors
├── config/           # app.config.ts, database.config.ts
└── modules/
    ├── auth/
    ├── stations/
    ├── fleet/
    ├── schedules/
    ├── search/
    ├── seats/
    ├── bookings/
    ├── payments/
    ├── tickets/
    ├── passengers/
    ├── notifications/
    ├── loyalty/
    ├── wallet/
    ├── promos/
    ├── live/
    ├── support/
    └── dashboard/
prisma/
├── schema.prisma
├── seed.ts
└── migrations/
```