e863399bb2
Some checks failed
CI / Lint & Format Check (push) Failing after 1m11s
CI / Test Backend (push) Failing after 1m32s
CI / Build Backend (push) Has been skipped
Security Audit / npm audit (push) Failing after 5s
Security Audit / Dependency Review (push) Has been skipped
CI / Test Frontend (push) Failing after 29s
CI / Build Frontend (push) Has been skipped
261 lines
6.2 KiB
Markdown
261 lines
6.2 KiB
Markdown
# Xpeditis Backend API
|
|
|
|
NestJS-based API for the Xpeditis maritime freight booking platform, built with **Hexagonal Architecture**.
|
|
|
|
## 🏗️ Architecture
|
|
|
|
This backend follows **Hexagonal Architecture** (Ports & Adapters pattern):
|
|
|
|
```
|
|
src/
|
|
├── domain/ # 🔵 Pure business logic (NO external dependencies)
|
|
│ ├── entities/ # Business entities
|
|
│ ├── value-objects/ # Value objects (Email, PortCode, etc.)
|
|
│ ├── services/ # Domain services
|
|
│ ├── ports/
|
|
│ │ ├── in/ # API Ports (use cases exposed by domain)
|
|
│ │ └── out/ # SPI Ports (interfaces required by domain)
|
|
│ └── exceptions/ # Business exceptions
|
|
│
|
|
├── application/ # 🟢 Controllers & DTOs
|
|
│ ├── controllers/ # REST controllers
|
|
│ ├── dto/ # Data Transfer Objects
|
|
│ ├── mappers/ # DTO ↔ Domain mappers
|
|
│ └── config/ # Application configuration
|
|
│
|
|
└── infrastructure/ # 🟡 External integrations
|
|
├── persistence/ # TypeORM repositories
|
|
├── cache/ # Redis cache adapter
|
|
├── carriers/ # Maersk, MSC, CMA CGM connectors
|
|
├── email/ # Email service adapter
|
|
├── storage/ # S3 storage adapter
|
|
└── config/ # Infrastructure configuration
|
|
```
|
|
|
|
### Key Principles
|
|
|
|
1. **Domain is isolated**: No imports of NestJS, TypeORM, or any framework in domain layer
|
|
2. **Dependencies point inward**: Infrastructure → Application → Domain
|
|
3. **Testable**: Domain can be tested without any framework
|
|
4. **Flexible**: Change database, framework, or external services without touching domain
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 20+
|
|
- PostgreSQL 15+
|
|
- Redis 7+
|
|
- Docker (optional, for local development)
|
|
|
|
### Install Dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Setup Environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
### Start Development Server
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Server runs on: **http://localhost:4000**
|
|
|
|
API Documentation: **http://localhost:4000/api/docs**
|
|
|
|
## 📝 Available Scripts
|
|
|
|
### Development
|
|
|
|
- `npm run dev` - Start development server with hot reload
|
|
- `npm run start` - Start server
|
|
- `npm run start:debug` - Start with debugging
|
|
- `npm run build` - Build for production
|
|
- `npm run start:prod` - Start production server
|
|
|
|
### Testing
|
|
|
|
- `npm test` - Run unit tests
|
|
- `npm run test:watch` - Run tests in watch mode
|
|
- `npm run test:cov` - Run tests with coverage
|
|
- `npm run test:e2e` - Run end-to-end tests
|
|
- `npm run test:debug` - Debug tests
|
|
|
|
### Code Quality
|
|
|
|
- `npm run lint` - Lint code
|
|
- `npm run format` - Format code with Prettier
|
|
|
|
### Database
|
|
|
|
- `npm run migration:generate -- src/infrastructure/persistence/migrations/MigrationName` - Generate migration
|
|
- `npm run migration:run` - Run migrations
|
|
- `npm run migration:revert` - Revert last migration
|
|
|
|
## 🔑 Environment Variables
|
|
|
|
See `.env.example` for all available variables.
|
|
|
|
**Required**:
|
|
- `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_NAME`
|
|
- `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`
|
|
- `JWT_SECRET`
|
|
|
|
**Optional** (for production):
|
|
- OAuth credentials (Google, Microsoft)
|
|
- Carrier API keys (Maersk, MSC, CMA CGM, etc.)
|
|
- AWS S3 credentials
|
|
- Email service credentials
|
|
- Sentry DSN
|
|
|
|
## 📚 API Documentation
|
|
|
|
Swagger/OpenAPI documentation is available at `/api/docs` when the server is running.
|
|
|
|
**Endpoints**:
|
|
|
|
### Health
|
|
- `GET /api/v1/health` - Health check
|
|
- `GET /api/v1/health/ready` - Readiness check
|
|
- `GET /api/v1/health/live` - Liveness check
|
|
|
|
### (More endpoints will be added in Phase 1)
|
|
|
|
## 🧪 Testing
|
|
|
|
### Unit Tests
|
|
|
|
Test domain logic without any external dependencies:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
**Example** (`domain/services/booking.service.spec.ts`):
|
|
```typescript
|
|
describe('BookingService', () => {
|
|
it('should create booking with valid rate quote', () => {
|
|
const service = new BookingService(mockRepository);
|
|
const result = service.createBooking(validInput);
|
|
expect(result.bookingNumber).toMatch(/^WCM-\d{4}-[A-Z0-9]{6}$/);
|
|
});
|
|
});
|
|
```
|
|
|
|
### Integration Tests
|
|
|
|
Test infrastructure adapters with real dependencies:
|
|
|
|
```bash
|
|
npm run test:e2e
|
|
```
|
|
|
|
### Coverage
|
|
|
|
```bash
|
|
npm run test:cov
|
|
```
|
|
|
|
**Targets**:
|
|
- Domain: 90%+
|
|
- Application: 80%+
|
|
- Infrastructure: 70%+
|
|
|
|
## 🏛️ Hexagonal Architecture Guidelines
|
|
|
|
### ✅ DO
|
|
|
|
- **Domain layer**:
|
|
- Pure TypeScript classes
|
|
- Define interfaces (ports)
|
|
- Implement business logic
|
|
- Throw domain exceptions
|
|
|
|
- **Application layer**:
|
|
- Import from `@domain/*` only
|
|
- Validate DTOs
|
|
- Map DTOs ↔ Domain entities
|
|
- Handle HTTP-specific concerns
|
|
|
|
- **Infrastructure layer**:
|
|
- Import from `@domain/*` only
|
|
- Implement port interfaces
|
|
- Handle framework-specific code
|
|
- Map ORM entities ↔ Domain entities
|
|
|
|
### ❌ DON'T
|
|
|
|
- Import NestJS decorators in domain
|
|
- Import TypeORM in domain
|
|
- Put business logic in controllers
|
|
- Put business logic in repositories
|
|
- Use `any` type
|
|
- Skip tests
|
|
|
|
## 🔒 Security
|
|
|
|
- Passwords hashed with bcrypt (12 rounds)
|
|
- JWT tokens (access: 15min, refresh: 7 days)
|
|
- Helmet.js for security headers
|
|
- CORS configured
|
|
- Rate limiting enabled
|
|
- Input validation with class-validator
|
|
- SQL injection prevention (TypeORM)
|
|
- XSS protection
|
|
|
|
## 📊 Logging
|
|
|
|
Using Pino logger with structured JSON logs.
|
|
|
|
**Log levels**:
|
|
- Development: `debug`
|
|
- Production: `info`
|
|
|
|
**Pretty print** in development with `pino-pretty`.
|
|
|
|
## 🚢 Carrier Integrations
|
|
|
|
MVP supports these carriers:
|
|
- Maersk
|
|
- MSC
|
|
- CMA CGM
|
|
- Hapag-Lloyd
|
|
- ONE (Ocean Network Express)
|
|
|
|
Each connector implements `CarrierConnectorPort` with:
|
|
- Circuit breaker (5s timeout)
|
|
- Retry logic
|
|
- Rate limiting
|
|
- Error normalization
|
|
|
|
## 📖 Further Reading
|
|
|
|
- [CLAUDE.md](../../CLAUDE.md) - Complete architecture guidelines
|
|
- [TODO.md](../../TODO.md) - Development roadmap
|
|
- [SPRINT-0-FINAL.md](../../SPRINT-0-FINAL.md) - Sprint 0 completion
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Follow hexagonal architecture principles
|
|
2. Write tests (domain: 90%+, application: 80%+)
|
|
3. Use TypeScript strict mode
|
|
4. Format with Prettier
|
|
5. Lint with ESLint
|
|
6. Document API with Swagger decorators
|
|
|
|
## 📝 License
|
|
|
|
Proprietary - All rights reserved
|
|
|
|
---
|
|
|
|
Built with ❤️ using NestJS and Hexagonal Architecture
|