diff --git a/CLAUDE.md b/CLAUDE.md index 9816ea6..f4e2ddc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,9 +18,13 @@ npm install cd apps/backend && npm install cd ../frontend && npm install -# Start infrastructure (PostgreSQL + Redis) +# Start infrastructure (PostgreSQL + Redis + MinIO) docker-compose up -d +# Verify all services are running +docker-compose ps +# Expected: xpeditis-postgres, xpeditis-redis, xpeditis-minio + # Run database migrations cd apps/backend npm run migration:run @@ -38,6 +42,7 @@ cd apps/frontend && npm run dev - Frontend: http://localhost:3000 - Backend API: http://localhost:4000 - API Docs (Swagger): http://localhost:4000/api/docs +- MinIO Console (local S3): http://localhost:9001 (minioadmin/minioadmin) ### Monorepo Scripts (from root) @@ -238,6 +243,8 @@ apps/frontend/ - `@/app/*` - Maps to `./app/*` - `@/types/*` - Maps to `./src/types/*` - `@/hooks/*` - Maps to `./src/hooks/*` +- `@/utils/*` - Maps to `./src/utils/*` +- `@/pages/*` - Maps to `./src/pages/*` ### Tech Stack @@ -270,6 +277,7 @@ apps/frontend/ - AWS RDS (PostgreSQL) - AWS ElastiCache (Redis) - AWS S3 (document storage) +- MinIO (local S3-compatible storage for development) ## Testing Strategy @@ -333,7 +341,8 @@ See [.github/workflows/ci.yml](.github/workflows/ci.yml) for full pipeline. - Sentry error tracking + APM (10% trace sampling) - Performance monitoring interceptor (slow request alerts) - Structured JSON logging with Pino -- WebSocket real-time carrier status updates +- WebSocket real-time notifications (NotificationsGateway) +- WebSocket carrier status updates ## Database Schema @@ -347,6 +356,10 @@ See [.github/workflows/ci.yml](.github/workflows/ci.yml) for full pipeline. - `containers` - Container details (type, VGM, seal numbers) - `shipments` - Real-time shipment tracking - `audit_logs` - Compliance audit trail +- `csv_rates` - CSV-based rate data for offline/bulk rate loading +- `csv_bookings` - CSV-based booking imports +- `notifications` - User notifications (email, in-app) +- `webhooks` - Webhook configurations for external integrations **Migrations**: Located in `apps/backend/src/infrastructure/persistence/typeorm/migrations/` @@ -393,7 +406,11 @@ See `apps/backend/.env.example` and `apps/frontend/.env.example` for all availab - `GET /api/v1/bookings` - List bookings (paginated) - `GET /api/v1/bookings/:id` - Get booking details - `GET /api/v1/carriers/:id/status` - Real-time carrier status -- `WS /carrier-status` - WebSocket for real-time updates +- `POST /api/v1/rates/csv-search` - Search rates from CSV data +- `POST /api/v1/bookings/csv-import` - Bulk import bookings from CSV +- `GET /api/v1/notifications` - Get user notifications +- `WS /notifications` - WebSocket for real-time notifications +- `WS /carrier-status` - WebSocket for carrier status updates ## Business Rules @@ -413,6 +430,50 @@ See `apps/backend/.env.example` and `apps/frontend/.env.example` for all availab - `USER` - Create and view own bookings - `VIEWER` - Read-only access +## Real-Time Features (WebSocket) + +The platform uses WebSocket connections for real-time updates: + +**Notifications Gateway** (`application/gateways/notifications.gateway.ts`): +- Real-time user notifications (booking updates, system alerts) +- JWT-authenticated WebSocket connections +- Auto-reconnect with exponential backoff +- Connect to `ws://localhost:4000/notifications` + +**Carrier Status Updates**: +- Real-time carrier API status monitoring +- Live shipment tracking updates +- Connection status: online/offline/degraded +- Connect to `ws://localhost:4000/carrier-status` + +**Frontend Integration**: +- Socket.IO client for WebSocket connections +- Context providers in `lib/providers/` +- Real-time notification dropdown component +- Auto-refresh on status changes + +## CSV Import/Export Features + +The platform supports CSV-based operations for bulk data management: + +**CSV Rate Search**: +- Upload CSV files with rate data for offline/bulk rate loading +- CSV-based carrier connectors in `infrastructure/carriers/csv-loader/` +- Stored in `csv_rates` table +- Accessible via admin dashboard at `/admin/csv-rates` + +**CSV Booking Import**: +- Bulk import bookings from CSV files +- Validation and mapping to domain entities +- Stored in `csv_bookings` table +- CSV parsing with `csv-parse` library + +**Export Features**: +- Export bookings to Excel (`.xlsx`) using `exceljs` +- Export to CSV format +- Export to PDF documents using `pdfkit` +- File downloads using `file-saver` on frontend + ## Common Development Tasks ### Adding a New Domain Entity diff --git a/apps/backend/package.json b/apps/backend/package.json index 6051eb7..e2c5fb8 100644 --- a/apps/backend/package.json +++ b/apps/backend/package.json @@ -4,7 +4,7 @@ "description": "Xpeditis Backend API - Maritime Freight Booking Platform", "private": true, "scripts": { - "build": "nest build", + "build": "nest build && tsc-alias -p tsconfig.build.json", "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"", "start": "nest start", "dev": "nest start --watch", diff --git a/apps/backend/tsconfig.build.json b/apps/backend/tsconfig.build.json new file mode 100644 index 0000000..1d7acd8 --- /dev/null +++ b/apps/backend/tsconfig.build.json @@ -0,0 +1,4 @@ +{ + "extends": "./tsconfig.json", + "exclude": ["node_modules", "test", "dist", "**/*spec.ts"] +}