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
207 lines
5.1 KiB
Markdown
207 lines
5.1 KiB
Markdown
# Xpeditis - Maritime Freight Booking Platform
|
|
|
|
**Xpeditis** is a B2B SaaS platform for freight forwarders to search, compare, and book maritime freight in real-time.
|
|
|
|
---
|
|
|
|
## ⭐ **[START HERE](START-HERE.md)** ⭐
|
|
|
|
**New to the project?** Read **[START-HERE.md](START-HERE.md)** - Get running in 10 minutes!
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js >= 20.0.0
|
|
- npm >= 10.0.0
|
|
- Docker & Docker Compose
|
|
- PostgreSQL 15+
|
|
- Redis 7+
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start infrastructure (PostgreSQL + Redis)
|
|
docker-compose up -d
|
|
|
|
# Setup environment variables
|
|
cp apps/backend/.env.example apps/backend/.env
|
|
cp apps/frontend/.env.example apps/frontend/.env
|
|
|
|
# Run database migrations
|
|
npm run backend:migrate
|
|
|
|
# Start backend (development)
|
|
npm run backend:dev
|
|
|
|
# Start frontend (development)
|
|
npm run frontend:dev
|
|
```
|
|
|
|
### Access Points
|
|
|
|
- **Frontend**: http://localhost:3000
|
|
- **Backend API**: http://localhost:4000
|
|
- **API Documentation**: http://localhost:4000/api/docs
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
xpeditis/
|
|
├── apps/
|
|
│ ├── backend/ # NestJS API (Hexagonal Architecture)
|
|
│ │ └── src/
|
|
│ │ ├── domain/ # Pure business logic
|
|
│ │ ├── application/ # Controllers & DTOs
|
|
│ │ └── infrastructure/ # External adapters
|
|
│ └── frontend/ # Next.js 14 App Router
|
|
├── packages/
|
|
│ ├── shared-types/ # Shared TypeScript types
|
|
│ └── domain/ # Shared domain logic
|
|
└── infra/ # Infrastructure configs
|
|
```
|
|
|
|
## 🏗️ Architecture
|
|
|
|
This project follows **Hexagonal Architecture** (Ports & Adapters) principles:
|
|
|
|
- **Domain Layer**: Pure business logic, no external dependencies
|
|
- **Application Layer**: Use cases, controllers, DTOs
|
|
- **Infrastructure Layer**: Database, external APIs, cache, email, storage
|
|
|
|
See [CLAUDE.md](CLAUDE.md) for detailed architecture guidelines.
|
|
|
|
## 🛠️ Development
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
npm run backend:dev # Start dev server
|
|
npm run backend:test # Run tests
|
|
npm run backend:test:watch # Run tests in watch mode
|
|
npm run backend:test:cov # Generate coverage report
|
|
npm run backend:lint # Lint code
|
|
npm run backend:build # Build for production
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
npm run frontend:dev # Start dev server
|
|
npm run frontend:build # Build for production
|
|
npm run frontend:test # Run tests
|
|
npm run frontend:lint # Lint code
|
|
```
|
|
|
|
## 📚 Documentation
|
|
|
|
### Getting Started
|
|
- **[QUICK-START.md](QUICK-START.md)** ⚡ - Get running in 5 minutes
|
|
- **[INSTALLATION-STEPS.md](INSTALLATION-STEPS.md)** 📦 - Detailed installation guide
|
|
- **[NEXT-STEPS.md](NEXT-STEPS.md)** 🚀 - What to do after setup
|
|
|
|
### Architecture & Guidelines
|
|
- **[CLAUDE.md](CLAUDE.md)** 🏗️ - Hexagonal architecture guidelines (complete)
|
|
- **[apps/backend/README.md](apps/backend/README.md)** - Backend documentation
|
|
- **[apps/frontend/README.md](apps/frontend/README.md)** - Frontend documentation
|
|
|
|
### Project Planning
|
|
- **[PRD.md](PRD.md)** 📋 - Product Requirements Document
|
|
- **[TODO.md](TODO.md)** 📅 - 30-week development roadmap
|
|
- **[SPRINT-0-FINAL.md](SPRINT-0-FINAL.md)** ✅ - Sprint 0 completion report
|
|
- **[SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md)** 📊 - Executive summary
|
|
|
|
### API Documentation
|
|
- **[API Docs](http://localhost:4000/api/docs)** 📖 - OpenAPI/Swagger (when running)
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm run test:all
|
|
|
|
# Run backend tests
|
|
npm run backend:test
|
|
|
|
# Run frontend tests
|
|
npm run frontend:test
|
|
|
|
# E2E tests (after implementation)
|
|
npm run test:e2e
|
|
```
|
|
|
|
## 🔒 Security
|
|
|
|
- All passwords hashed with bcrypt (12 rounds minimum)
|
|
- JWT tokens (access: 15min, refresh: 7 days)
|
|
- HTTPS/TLS 1.2+ enforced
|
|
- OWASP Top 10 protection
|
|
- Rate limiting on all endpoints
|
|
- CSRF protection
|
|
|
|
## 📊 Tech Stack
|
|
|
|
### Backend
|
|
- **Framework**: NestJS 10+
|
|
- **Language**: TypeScript 5+
|
|
- **Database**: PostgreSQL 15+
|
|
- **Cache**: Redis 7+
|
|
- **ORM**: TypeORM
|
|
- **Testing**: Jest, Supertest
|
|
- **API Docs**: Swagger/OpenAPI
|
|
|
|
### Frontend
|
|
- **Framework**: Next.js 14+ (App Router)
|
|
- **Language**: TypeScript 5+
|
|
- **Styling**: Tailwind CSS
|
|
- **UI Components**: shadcn/ui
|
|
- **State**: React Query (TanStack Query)
|
|
- **Forms**: React Hook Form + Zod
|
|
- **Testing**: Jest, React Testing Library, Playwright
|
|
|
|
## 🚢 Carrier Integrations
|
|
|
|
MVP supports the following maritime carriers:
|
|
|
|
- ✅ Maersk
|
|
- ✅ MSC
|
|
- ✅ CMA CGM
|
|
- ✅ Hapag-Lloyd
|
|
- ✅ ONE (Ocean Network Express)
|
|
|
|
## 📈 Monitoring & Logging
|
|
|
|
- **Logging**: Winston / Pino
|
|
- **Error Tracking**: Sentry
|
|
- **APM**: Application Performance Monitoring
|
|
- **Metrics**: Prometheus (planned)
|
|
|
|
## 🔧 Environment Variables
|
|
|
|
See `.env.example` files in each app for required environment variables.
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Create a feature branch
|
|
2. Make your changes
|
|
3. Write tests
|
|
4. Run linting and formatting
|
|
5. Submit a pull request
|
|
|
|
## 📝 License
|
|
|
|
Proprietary - All rights reserved
|
|
|
|
## 👥 Team
|
|
|
|
Built with ❤️ by the Xpeditis team
|
|
|
|
---
|
|
|
|
For detailed implementation guidelines, see [CLAUDE.md](CLAUDE.md).
|