diff --git a/COMPLETION-REPORT.md b/COMPLETION-REPORT.md deleted file mode 100644 index cb5c1b2..0000000 --- a/COMPLETION-REPORT.md +++ /dev/null @@ -1,466 +0,0 @@ -# ✅ Sprint 0 - Rapport de Complétion Final - -## Xpeditis MVP - Project Setup & Infrastructure - -**Date de Complétion** : 7 octobre 2025 -**Statut** : ✅ **100% TERMINÉ** -**Durée** : 2 semaines (comme planifié) - ---- - -## 📊 Résumé Exécutif - -Sprint 0 a été **complété avec succès à 100%**. Tous les objectifs ont été atteints et le projet Xpeditis MVP est **prêt pour la Phase 1 de développement**. - -### Statistiques - -| Métrique | Valeur | -|----------|--------| -| **Fichiers Créés** | 60+ fichiers | -| **Documentation** | 14 fichiers Markdown (5000+ lignes) | -| **Code/Config** | 27 fichiers TypeScript/JavaScript/JSON/YAML | -| **Dépendances** | 80+ packages npm | -| **Lignes de Code** | 2000+ lignes | -| **Temps Total** | ~16 heures de travail | -| **Complétion** | 100% ✅ | - ---- - -## 📦 Livrables Créés - -### 1. Documentation (14 fichiers) - -| Fichier | Lignes | Purpose | Statut | -|---------|--------|---------|--------| -| **START-HERE.md** | 350+ | 🟢 Point d'entrée principal | ✅ | -| README.md | 200+ | Vue d'ensemble du projet | ✅ | -| CLAUDE.md | 650+ | Guide d'architecture hexagonale complet | ✅ | -| PRD.md | 350+ | Exigences produit détaillées | ✅ | -| TODO.md | 1300+ | Roadmap 30 semaines complet | ✅ | -| QUICK-START.md | 250+ | Guide de démarrage rapide | ✅ | -| INSTALLATION-STEPS.md | 400+ | Guide d'installation détaillé | ✅ | -| WINDOWS-INSTALLATION.md | 350+ | Installation spécifique Windows | ✅ | -| NEXT-STEPS.md | 550+ | Prochaines étapes détaillées | ✅ | -| SPRINT-0-FINAL.md | 550+ | Rapport complet Sprint 0 | ✅ | -| SPRINT-0-SUMMARY.md | 500+ | Résumé exécutif | ✅ | -| INDEX.md | 450+ | Index de toute la documentation | ✅ | -| READY.md | 400+ | Confirmation de préparation | ✅ | -| COMPLETION-REPORT.md | Ce fichier | Rapport final de complétion | ✅ | - -**Sous-total** : 14 fichiers, ~5000 lignes de documentation - -### 2. Backend (NestJS + Architecture Hexagonale) - -| Catégorie | Fichiers | Statut | -|-----------|----------|--------| -| **Configuration** | 7 fichiers | ✅ | -| **Code Source** | 6 fichiers | ✅ | -| **Tests** | 2 fichiers | ✅ | -| **Documentation** | 1 fichier (README.md) | ✅ | - -**Fichiers Backend** : -- ✅ package.json (50+ dépendances) -- ✅ tsconfig.json (strict mode + path aliases) -- ✅ nest-cli.json -- ✅ .eslintrc.js -- ✅ .env.example (toutes les variables) -- ✅ .gitignore -- ✅ src/main.ts (bootstrap complet) -- ✅ src/app.module.ts (module racine) -- ✅ src/application/controllers/health.controller.ts -- ✅ src/application/controllers/index.ts -- ✅ src/domain/entities/index.ts -- ✅ src/domain/ports/in/index.ts -- ✅ src/domain/ports/out/index.ts -- ✅ test/app.e2e-spec.ts -- ✅ test/jest-e2e.json -- ✅ README.md (guide backend) - -**Structure Hexagonale** : -``` -src/ -├── domain/ ✅ Logique métier pure -│ ├── entities/ -│ ├── value-objects/ -│ ├── services/ -│ ├── ports/in/ -│ ├── ports/out/ -│ └── exceptions/ -├── application/ ✅ Controllers & DTOs -│ ├── controllers/ -│ ├── dto/ -│ ├── mappers/ -│ └── config/ -└── infrastructure/ ✅ Adaptateurs externes - ├── persistence/ - ├── cache/ - ├── carriers/ - ├── email/ - ├── storage/ - └── config/ -``` - -**Sous-total** : 16 fichiers backend - -### 3. Frontend (Next.js 14 + TypeScript) - -| Catégorie | Fichiers | Statut | -|-----------|----------|--------| -| **Configuration** | 7 fichiers | ✅ | -| **Code Source** | 4 fichiers | ✅ | -| **Documentation** | 1 fichier (README.md) | ✅ | - -**Fichiers Frontend** : -- ✅ package.json (30+ dépendances) -- ✅ tsconfig.json (path aliases) -- ✅ next.config.js -- ✅ tailwind.config.ts (thème complet) -- ✅ postcss.config.js -- ✅ .eslintrc.json -- ✅ .env.example -- ✅ .gitignore -- ✅ app/layout.tsx (layout racine) -- ✅ app/page.tsx (page d'accueil) -- ✅ app/globals.css (Tailwind + variables CSS) -- ✅ lib/utils.ts (helper cn) -- ✅ README.md (guide frontend) - -**Sous-total** : 13 fichiers frontend - -### 4. Infrastructure & DevOps - -| Catégorie | Fichiers | Statut | -|-----------|----------|--------| -| **Docker** | 2 fichiers | ✅ | -| **CI/CD** | 3 fichiers | ✅ | -| **Configuration Racine** | 4 fichiers | ✅ | - -**Fichiers Infrastructure** : -- ✅ docker-compose.yml (PostgreSQL + Redis) -- ✅ infra/postgres/init.sql (script d'initialisation) -- ✅ .github/workflows/ci.yml (pipeline CI) -- ✅ .github/workflows/security.yml (audit sécurité) -- ✅ .github/pull_request_template.md -- ✅ package.json (racine, scripts simplifiés) -- ✅ .gitignore (racine) -- ✅ .prettierrc -- ✅ .prettierignore - -**Sous-total** : 9 fichiers infrastructure - ---- - -## 🎯 Objectifs Sprint 0 - Tous Atteints - -| Objectif | Statut | Notes | -|----------|--------|-------| -| **Structure Monorepo** | ✅ Complete | npm scripts sans workspaces (Windows) | -| **Backend Hexagonal** | ✅ Complete | Domain/Application/Infrastructure | -| **Frontend Next.js 14** | ✅ Complete | App Router + TypeScript | -| **Docker Infrastructure** | ✅ Complete | PostgreSQL 15 + Redis 7 | -| **TypeScript Strict** | ✅ Complete | Tous les projets | -| **Testing Infrastructure** | ✅ Complete | Jest, Supertest, Playwright | -| **CI/CD Pipelines** | ✅ Complete | GitHub Actions | -| **API Documentation** | ✅ Complete | Swagger à /api/docs | -| **Logging Structuré** | ✅ Complete | Pino avec pretty-print | -| **Sécurité** | ✅ Complete | Helmet, JWT, CORS, validation | -| **Validation Env** | ✅ Complete | Joi schema | -| **Health Endpoints** | ✅ Complete | /health, /ready, /live | -| **Documentation** | ✅ Complete | 14 fichiers, 5000+ lignes | - -**Score** : 13/13 objectifs atteints (100%) - ---- - -## 🏗️ Architecture Implémentée - -### Backend - Architecture Hexagonale - -**✅ Strict Separation of Concerns** : - -1. **Domain Layer (Core)** : - - ✅ Zero external dependencies - - ✅ Pure TypeScript classes - - ✅ Ports (interfaces) defined - - ✅ Testable without framework - - 🎯 Target: 90%+ test coverage - -2. **Application Layer** : - - ✅ Controllers with validation - - ✅ DTOs defined - - ✅ Mappers ready - - ✅ Depends only on domain - - 🎯 Target: 80%+ test coverage - -3. **Infrastructure Layer** : - - ✅ TypeORM configured - - ✅ Redis configured - - ✅ Folder structure ready - - ✅ Depends only on domain - - 🎯 Target: 70%+ test coverage - -### Frontend - Modern React Stack - -**✅ Next.js 14 Configuration** : -- ✅ App Router avec Server Components -- ✅ TypeScript strict mode -- ✅ Tailwind CSS + shadcn/ui ready -- ✅ TanStack Query configured -- ✅ react-hook-form + zod ready -- ✅ Dark mode support (CSS variables) - ---- - -## 🛠️ Stack Technique Complet - -### Backend -- **Framework** : NestJS 10.2.10 ✅ -- **Language** : TypeScript 5.3.3 ✅ -- **Database** : PostgreSQL 15 ✅ -- **Cache** : Redis 7 ✅ -- **ORM** : TypeORM 0.3.17 ✅ -- **Auth** : JWT + Passport ✅ -- **Validation** : class-validator + class-transformer ✅ -- **API Docs** : Swagger/OpenAPI ✅ -- **Logging** : Pino 8.17.1 ✅ -- **Testing** : Jest 29.7.0 + Supertest 6.3.3 ✅ -- **Security** : Helmet 7.1.0, bcrypt 5.1.1 ✅ -- **Circuit Breaker** : opossum 8.1.3 ✅ - -### Frontend -- **Framework** : Next.js 14.0.4 ✅ -- **Language** : TypeScript 5.3.3 ✅ -- **Styling** : Tailwind CSS 3.3.6 ✅ -- **UI Components** : Radix UI ✅ -- **State** : TanStack Query 5.14.2 ✅ -- **Forms** : react-hook-form 7.49.2 ✅ -- **Validation** : zod 3.22.4 ✅ -- **HTTP** : axios 1.6.2 ✅ -- **Icons** : lucide-react 0.294.0 ✅ -- **Testing** : Jest 29.7.0 + Playwright 1.40.1 ✅ - -### Infrastructure -- **Database** : PostgreSQL 15-alpine (Docker) ✅ -- **Cache** : Redis 7-alpine (Docker) ✅ -- **CI/CD** : GitHub Actions ✅ -- **Version Control** : Git ✅ - ---- - -## 📋 Features Implémentées - -### Backend Features - -1. **✅ Health Check System** - - `/health` - Overall system health - - `/ready` - Readiness for traffic - - `/live` - Liveness check - -2. **✅ Logging System** - - Structured JSON logs (Pino) - - Pretty print en développement - - Request/response logging - - Log levels configurables - -3. **✅ Configuration Management** - - Validation des variables d'environnement (Joi) - - Configuration type-safe - - Support multi-environnements - -4. **✅ Security Foundations** - - Helmet.js security headers - - CORS configuration - - Rate limiting preparé - - JWT authentication ready - - Password hashing (bcrypt) - - Input validation (class-validator) - -5. **✅ API Documentation** - - Swagger UI à `/api/docs` - - Spécification OpenAPI - - Schémas request/response - - Documentation d'authentification - -6. **✅ Testing Infrastructure** - - Jest configuré - - Supertest configuré - - E2E tests ready - - Path aliases for tests - -### Frontend Features - -1. **✅ Modern React Setup** - - Next.js 14 App Router - - Server et client components - - TypeScript strict mode - - Path aliases configurés - -2. **✅ UI Framework** - - Tailwind CSS avec thème personnalisé - - shadcn/ui components ready - - Dark mode support (variables CSS) - - Responsive design utilities - -3. **✅ State Management** - - TanStack Query configuré - - React hooks ready - - Form state avec react-hook-form - -4. **✅ Utilities** - - Helper `cn()` pour className merging - - API client type-safe ready - - Validation Zod ready - ---- - -## 🚀 Prêt pour Phase 1 - -### Checklist de Préparation - -- [x] Code et configuration complets -- [x] Documentation exhaustive -- [x] Architecture hexagonale validée -- [x] Testing infrastructure prête -- [x] CI/CD pipelines configurés -- [x] Docker infrastructure opérationnelle -- [x] Sécurité de base implémentée -- [x] Guide de démarrage créé -- [x] Tous les objectifs Sprint 0 atteints - -### Prochaine Phase : Phase 1 (6-8 semaines) - -**Sprint 1-2** : Domain Layer (Semaines 1-2) -- Créer les entités métier -- Créer les value objects -- Définir les ports API et SPI -- Implémenter les services métier -- Tests unitaires (90%+) - -**Sprint 3-4** : Infrastructure Layer (Semaines 3-4) -- Schéma de base de données -- Repositories TypeORM -- Redis cache adapter -- Connecteur Maersk - -**Sprint 5-6** : Application Layer (Semaines 5-6) -- API rate search -- Controllers & DTOs -- Documentation OpenAPI -- Tests E2E - -**Sprint 7-8** : Frontend UI (Semaines 7-8) -- Interface de recherche -- Affichage des résultats -- Filtres et tri -- Tests frontend - ---- - -## 📚 Documentation Organisée - -### Guide de Navigation - -**🟢 Pour Démarrer** (obligatoire) : -1. [START-HERE.md](START-HERE.md) - Point d'entrée principal -2. [QUICK-START.md](QUICK-START.md) - Démarrage rapide -3. [CLAUDE.md](CLAUDE.md) - Architecture (À LIRE ABSOLUMENT) -4. [NEXT-STEPS.md](NEXT-STEPS.md) - Quoi faire ensuite - -**🟡 Pour Installation** : -- [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Détaillé -- [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md) - Spécifique Windows - -**🔵 Pour Développement** : -- [CLAUDE.md](CLAUDE.md) - Règles d'architecture -- [apps/backend/README.md](apps/backend/README.md) - Backend -- [apps/frontend/README.md](apps/frontend/README.md) - Frontend -- [TODO.md](TODO.md) - Roadmap détaillée - -**🟠 Pour Référence** : -- [PRD.md](PRD.md) - Exigences produit -- [INDEX.md](INDEX.md) - Index complet -- [READY.md](READY.md) - Confirmation -- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Rapport complet -- [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - Résumé - ---- - -## 💻 Installation et Démarrage - -### Installation Rapide - -```bash -# 1. Installer les dépendances -npm run install:all - -# 2. Démarrer Docker -docker-compose up -d - -# 3. Configurer l'environnement -cp apps/backend/.env.example apps/backend/.env -cp apps/frontend/.env.example apps/frontend/.env - -# 4. Démarrer (2 terminals) -npm run backend:dev # Terminal 1 -npm run frontend:dev # Terminal 2 -``` - -### Vérification - -- ✅ http://localhost:4000/api/v1/health -- ✅ http://localhost:4000/api/docs -- ✅ http://localhost:3000 - ---- - -## 🎊 Conclusion - -### Succès Sprint 0 - -**Tout planifié a été livré** : -- ✅ 100% des objectifs atteints -- ✅ 60+ fichiers créés -- ✅ 5000+ lignes de documentation -- ✅ Architecture hexagonale complète -- ✅ Infrastructure production-ready -- ✅ CI/CD automatisé -- ✅ Sécurité de base - -### État du Projet - -**Sprint 0** : 🟢 **TERMINÉ** (100%) -**Qualité** : 🟢 **EXCELLENTE** -**Documentation** : 🟢 **COMPLÈTE** -**Prêt pour Phase 1** : 🟢 **OUI** - -### Prochaine Étape - -**Commencer Phase 1 - Core Search & Carrier Integration** - -1. Lire [START-HERE.md](START-HERE.md) -2. Lire [CLAUDE.md](CLAUDE.md) (OBLIGATOIRE) -3. Lire [NEXT-STEPS.md](NEXT-STEPS.md) -4. Commencer Sprint 1-2 (Domain Layer) - ---- - -## 🏆 Félicitations ! - -**Le projet Xpeditis MVP dispose maintenant d'une fondation solide et production-ready.** - -Tous les éléments sont en place pour un développement réussi : -- Architecture propre et maintenable -- Documentation exhaustive -- Tests automatisés -- CI/CD configuré -- Sécurité intégrée - -**Bonne chance pour la Phase 1 ! 🚀** - ---- - -*Rapport de Complétion Sprint 0* -*Xpeditis MVP - Maritime Freight Booking Platform* -*7 octobre 2025* - -**Statut Final** : ✅ **SPRINT 0 COMPLET À 100%** diff --git a/INDEX.md b/INDEX.md deleted file mode 100644 index 25651bf..0000000 --- a/INDEX.md +++ /dev/null @@ -1,348 +0,0 @@ -# 📑 Xpeditis Documentation Index - -Complete guide to all documentation files in the Xpeditis project. - ---- - -## 🚀 Getting Started (Read First) - -Start here if you're new to the project: - -1. **[README.md](README.md)** - Project overview and quick start -2. **[QUICK-START.md](QUICK-START.md)** ⚡ - Get running in 5 minutes -3. **[INSTALLATION-STEPS.md](INSTALLATION-STEPS.md)** - Detailed installation guide -4. **[NEXT-STEPS.md](NEXT-STEPS.md)** - What to do after setup - ---- - -## 📊 Project Status & Planning - -### Sprint 0 (Complete ✅) - -- **[SPRINT-0-FINAL.md](SPRINT-0-FINAL.md)** - Complete Sprint 0 report - - All deliverables - - Architecture details - - How to use - - Success criteria - -- **[SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md)** - Executive summary - - Objectives achieved - - Metrics - - Key features - - Next steps - -- **[SPRINT-0-COMPLETE.md](SPRINT-0-COMPLETE.md)** - Technical completion checklist - - Week-by-week breakdown - - Files created - - Remaining tasks - -### Project Roadmap - -- **[TODO.md](TODO.md)** 📅 - 30-week MVP development roadmap - - Sprint-by-sprint breakdown - - Detailed tasks with checkboxes - - Phase 1-4 planning - - Go-to-market strategy - -- **[PRD.md](PRD.md)** 📋 - Product Requirements Document - - Business context - - Functional specifications - - Technical requirements - - Success metrics - ---- - -## 🏗️ Architecture & Development Guidelines - -### Core Architecture - -- **[CLAUDE.md](CLAUDE.md)** 🏗️ - **START HERE FOR ARCHITECTURE** - - Complete hexagonal architecture guide - - Domain/Application/Infrastructure layers - - Ports & Adapters pattern - - Naming conventions - - Testing strategy - - Common pitfalls - - Complete examples (476 lines) - -### Component-Specific Documentation - -- **[apps/backend/README.md](apps/backend/README.md)** - Backend (NestJS + Hexagonal) - - Architecture details - - Available scripts - - API endpoints - - Testing guide - - Hexagonal architecture DOs and DON'Ts - -- **[apps/frontend/README.md](apps/frontend/README.md)** - Frontend (Next.js 14) - - Tech stack - - Project structure - - API integration - - Forms & validation - - Testing guide - ---- - -## 🛠️ Technical Documentation - -### Configuration Files - -**Root Level**: -- `package.json` - Workspace configuration -- `.gitignore` - Git ignore rules -- `.prettierrc` - Code formatting -- `docker-compose.yml` - PostgreSQL + Redis -- `tsconfig.json` - TypeScript configuration (per app) - -**Backend** (`apps/backend/`): -- `package.json` - Backend dependencies -- `tsconfig.json` - TypeScript strict mode + path aliases -- `nest-cli.json` - NestJS CLI configuration -- `.eslintrc.js` - ESLint rules -- `.env.example` - Environment variables template - -**Frontend** (`apps/frontend/`): -- `package.json` - Frontend dependencies -- `tsconfig.json` - TypeScript configuration -- `next.config.js` - Next.js configuration -- `tailwind.config.ts` - Tailwind CSS theme -- `postcss.config.js` - PostCSS configuration -- `.env.example` - Environment variables template - -### CI/CD - -**GitHub Actions** (`.github/workflows/`): -- `ci.yml` - Continuous Integration - - Lint & format check - - Unit tests (backend + frontend) - - E2E tests - - Build verification - -- `security.yml` - Security Audit - - npm audit - - Dependency review - -**Templates**: -- `.github/pull_request_template.md` - PR template with hexagonal architecture checklist - ---- - -## 📚 Documentation by Use Case - -### I want to... - -**...get started quickly** -1. [QUICK-START.md](QUICK-START.md) - 5-minute setup -2. [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Detailed steps -3. [NEXT-STEPS.md](NEXT-STEPS.md) - Begin development - -**...understand the architecture** -1. [CLAUDE.md](CLAUDE.md) - Complete hexagonal architecture guide -2. [apps/backend/README.md](apps/backend/README.md) - Backend specifics -3. [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - See what's implemented - -**...know what to build next** -1. [TODO.md](TODO.md) - Full roadmap -2. [NEXT-STEPS.md](NEXT-STEPS.md) - Immediate next tasks -3. [PRD.md](PRD.md) - Business requirements - -**...understand the business context** -1. [PRD.md](PRD.md) - Product requirements -2. [README.md](README.md) - Project overview -3. [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - Executive summary - -**...fix an installation issue** -1. [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Troubleshooting section -2. [QUICK-START.md](QUICK-START.md) - Common issues -3. [README.md](README.md) - Basic setup - -**...write code following best practices** -1. [CLAUDE.md](CLAUDE.md) - Architecture guidelines (READ THIS FIRST) -2. [apps/backend/README.md](apps/backend/README.md) - Backend DOs and DON'Ts -3. [TODO.md](TODO.md) - Task specifications and acceptance criteria - -**...run tests** -1. [apps/backend/README.md](apps/backend/README.md) - Testing section -2. [apps/frontend/README.md](apps/frontend/README.md) - Testing section -3. [CLAUDE.md](CLAUDE.md) - Testing strategy - -**...deploy to production** -1. [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Security checklist -2. [apps/backend/.env.example](apps/backend/.env.example) - All required variables -3. `.github/workflows/ci.yml` - CI/CD pipeline - ---- - -## 📖 Documentation by Role - -### For Developers - -**Must Read**: -1. [CLAUDE.md](CLAUDE.md) - Architecture principles -2. [apps/backend/README.md](apps/backend/README.md) OR [apps/frontend/README.md](apps/frontend/README.md) -3. [TODO.md](TODO.md) - Current sprint tasks - -**Reference**: -- [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Setup issues -- [PRD.md](PRD.md) - Business context - -### For Architects - -**Must Read**: -1. [CLAUDE.md](CLAUDE.md) - Complete architecture -2. [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Implementation details -3. [PRD.md](PRD.md) - Technical requirements - -**Reference**: -- [TODO.md](TODO.md) - Technical roadmap -- [apps/backend/README.md](apps/backend/README.md) - Backend architecture - -### For Project Managers - -**Must Read**: -1. [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - Status overview -2. [TODO.md](TODO.md) - Complete roadmap -3. [PRD.md](PRD.md) - Requirements & KPIs - -**Reference**: -- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Detailed completion report -- [README.md](README.md) - Project overview - -### For DevOps - -**Must Read**: -1. [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Setup guide -2. [docker-compose.yml](docker-compose.yml) - Infrastructure -3. `.github/workflows/` - CI/CD pipelines - -**Reference**: -- [apps/backend/.env.example](apps/backend/.env.example) - Environment variables -- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Security checklist - ---- - -## 🗂️ Complete File List - -### Documentation (11 files) - -| File | Purpose | Length | -|------|---------|--------| -| [README.md](README.md) | Project overview | Medium | -| [CLAUDE.md](CLAUDE.md) | Architecture guide | Long (476 lines) | -| [PRD.md](PRD.md) | Product requirements | Long (352 lines) | -| [TODO.md](TODO.md) | 30-week roadmap | Very Long (1000+ lines) | -| [QUICK-START.md](QUICK-START.md) | 5-minute setup | Short | -| [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) | Detailed setup | Medium | -| [NEXT-STEPS.md](NEXT-STEPS.md) | What's next | Medium | -| [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) | Sprint 0 report | Long | -| [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) | Executive summary | Medium | -| [SPRINT-0-COMPLETE.md](SPRINT-0-COMPLETE.md) | Technical checklist | Short | -| [INDEX.md](INDEX.md) | This file | Medium | - -### App-Specific (2 files) - -| File | Purpose | -|------|---------| -| [apps/backend/README.md](apps/backend/README.md) | Backend guide | -| [apps/frontend/README.md](apps/frontend/README.md) | Frontend guide | - -### Configuration (10+ files) - -Root, backend, and frontend configuration files (package.json, tsconfig.json, etc.) - ---- - -## 📊 Documentation Statistics - -- **Total Documentation Files**: 13 -- **Total Lines**: ~4,000+ -- **Coverage**: Setup, Architecture, Development, Testing, Deployment -- **Last Updated**: October 7, 2025 - ---- - -## 🎯 Recommended Reading Path - -### For New Team Members (Day 1) - -**Morning** (2 hours): -1. [README.md](README.md) - 10 min -2. [QUICK-START.md](QUICK-START.md) - 30 min (includes setup) -3. [CLAUDE.md](CLAUDE.md) - 60 min (comprehensive architecture) -4. [PRD.md](PRD.md) - 20 min (business context) - -**Afternoon** (2 hours): -5. [apps/backend/README.md](apps/backend/README.md) OR [apps/frontend/README.md](apps/frontend/README.md) - 30 min -6. [TODO.md](TODO.md) - Current sprint section - 30 min -7. [NEXT-STEPS.md](NEXT-STEPS.md) - 30 min -8. Start coding! 🚀 - -### For Code Review (30 minutes) - -1. [CLAUDE.md](CLAUDE.md) - Hexagonal architecture section -2. [apps/backend/README.md](apps/backend/README.md) - DOs and DON'Ts -3. [TODO.md](TODO.md) - Acceptance criteria for the feature - -### For Sprint Planning (1 hour) - -1. [TODO.md](TODO.md) - Next sprint tasks -2. [PRD.md](PRD.md) - Requirements for the module -3. [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - Current status - ---- - -## 🔍 Quick Reference - -### Common Questions - -**Q: How do I get started?** -A: [QUICK-START.md](QUICK-START.md) - -**Q: What is hexagonal architecture?** -A: [CLAUDE.md](CLAUDE.md) - Complete guide with examples - -**Q: What should I build next?** -A: [NEXT-STEPS.md](NEXT-STEPS.md) then [TODO.md](TODO.md) - -**Q: How do I run tests?** -A: [apps/backend/README.md](apps/backend/README.md) or [apps/frontend/README.md](apps/frontend/README.md) - -**Q: Where are the business requirements?** -A: [PRD.md](PRD.md) - -**Q: What's the project status?** -A: [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - -**Q: Installation failed, what do I do?** -A: [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Troubleshooting section - -**Q: Can I change the database/framework?** -A: Yes! That's the point of hexagonal architecture. See [CLAUDE.md](CLAUDE.md) - ---- - -## 📞 Getting Help - -If you can't find what you need: - -1. **Check this index** - Use Ctrl+F to search -2. **Read CLAUDE.md** - Covers 90% of architecture questions -3. **Check TODO.md** - Has detailed task specifications -4. **Open an issue** - If documentation is unclear or missing - ---- - -## 🎉 Happy Reading! - -All documentation is up-to-date as of Sprint 0 completion. - -**Quick Links**: -- 🚀 [Get Started](QUICK-START.md) -- 🏗️ [Architecture](CLAUDE.md) -- 📅 [Roadmap](TODO.md) -- 📋 [Requirements](PRD.md) - ---- - -*Xpeditis MVP - Maritime Freight Booking Platform* -*Documentation Index - October 7, 2025* diff --git a/INSTALLATION-COMPLETE.md b/INSTALLATION-COMPLETE.md deleted file mode 100644 index d12e306..0000000 --- a/INSTALLATION-COMPLETE.md +++ /dev/null @@ -1,334 +0,0 @@ -# ✅ Installation Complete - Xpeditis - -Sprint 0 setup is now complete with all dependencies installed and verified! - ---- - -## 📦 What Has Been Installed - -### Backend Dependencies ✅ -- **Location**: `apps/backend/node_modules` -- **Packages**: 873 packages (871 + nestjs-pino) -- **Key frameworks**: - - NestJS 10.2.10 (framework core) - - TypeORM 0.3.17 (database ORM) - - PostgreSQL driver (pg 8.11.3) - - Redis client (ioredis 5.3.2) - - nestjs-pino 8.x (structured logging) - - Passport + JWT (authentication) - - Helmet 7.1.0 (security) - - Swagger/OpenAPI (API documentation) - -### Frontend Dependencies ✅ -- **Location**: `apps/frontend/node_modules` -- **Packages**: 737 packages -- **Key frameworks**: - - Next.js 14.0.4 (React framework) - - React 18.2.0 - - TanStack Query 5.14.2 (data fetching) - - Tailwind CSS 3.3.6 (styling) - - shadcn/ui (component library) - - react-hook-form + zod (forms & validation) - - Playwright (E2E testing) - -### Environment Files ✅ -- `apps/backend/.env` (created from .env.example) -- `apps/frontend/.env` (created from .env.example) - ---- - -## ✅ Build Verification - -### Backend Build: SUCCESS ✅ -```bash -cd apps/backend -npm run build -# ✅ Compilation successful - 0 errors -``` - -The backend compiles successfully and can start in development mode. TypeScript compilation is working correctly with the hexagonal architecture setup. - -### Frontend Build: KNOWN ISSUE ⚠️ -```bash -cd apps/frontend -npm run build -# ⚠️ EISDIR error on Windows (symlink issue) -``` - -**Status**: This is a known Windows/Next.js symlink limitation. - -**Workaround**: Use development mode for daily work: -```bash -npm run dev # Works perfectly ✅ -``` - -For production builds, see [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md#frontend-build-fail---eisdir-illegal-operation-on-directory-readlink). - ---- - -## 🚀 Next Steps - Getting Started - -### 1. Start Docker Infrastructure (Required) - -The backend needs PostgreSQL and Redis running: - -```bash -docker-compose up -d -``` - -**Expected output**: -``` -✅ Container xpeditis-postgres Started -✅ Container xpeditis-redis Started -``` - -**Verify containers are running**: -```bash -docker ps -``` - -You should see: -- `xpeditis-postgres` on port 5432 -- `xpeditis-redis` on port 6379 - -**Note**: Docker was not found during setup. Please install Docker Desktop for Windows: -- [Download Docker Desktop](https://www.docker.com/products/docker-desktop/) - -### 2. Start Backend Development Server - -```bash -cd apps/backend -npm run dev -``` - -**Expected output**: -``` -[Nest] Starting Nest application... -[Nest] AppModule dependencies initialized -[Nest] Nest application successfully started -Application is running on: http://localhost:4000 -``` - -**Verify backend is running**: -- Health check: -- API docs: - -### 3. Start Frontend Development Server - -In a new terminal: - -```bash -cd apps/frontend -npm run dev -``` - -**Expected output**: -``` -▲ Next.js 14.0.4 -- Local: http://localhost:3000 -- Ready in 2.5s -``` - -**Verify frontend is running**: -- Open - ---- - -## 📋 Installation Checklist - -- ✅ Node.js v22.20.0 installed -- ✅ npm 10.9.3 installed -- ✅ Backend dependencies installed (873 packages) -- ✅ Frontend dependencies installed (737 packages) -- ✅ Environment files created -- ✅ Backend builds successfully -- ✅ Frontend dev mode works -- ⚠️ Docker not yet installed (required for database) -- ⏳ Backend server not started (waiting for Docker) -- ⏳ Frontend server not started - ---- - -## 🔍 Current Project Status - -### Sprint 0: 100% COMPLETE ✅ - -All Sprint 0 deliverables are in place: - -1. **Project Structure** ✅ - - Monorepo layout with apps/ and packages/ - - Backend with hexagonal architecture - - Frontend with Next.js 14 App Router - -2. **Configuration Files** ✅ - - TypeScript config with path aliases - - ESLint + Prettier - - Docker Compose - - Environment templates - -3. **Documentation** ✅ - - 14 comprehensive documentation files - - Architecture guidelines ([CLAUDE.md](CLAUDE.md)) - - Installation guides - - Development roadmap ([TODO.md](TODO.md)) - -4. **Dependencies** ✅ - - All npm packages installed - - Build verification complete - -5. **CI/CD** ✅ - - GitHub Actions workflows configured - - Test, build, and lint pipelines ready - -### What's Missing (User Action Required) - -1. **Docker Desktop** - Not yet installed - - Required for PostgreSQL and Redis - - Download: - -2. **First Run** - Servers not started yet - - Waiting for Docker to be installed - - Then follow "Next Steps" above - ---- - -## 🐛 Known Issues & Workarounds - -### 1. Frontend Production Build (EISDIR Error) - -**Issue**: `npm run build` fails with symlink error on Windows - -**Workaround**: Use `npm run dev` for development (works perfectly) - -**Full details**: [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md#frontend-build-fail---eisdir-illegal-operation-on-directory-readlink) - -### 2. npm Workspaces Disabled - -**Issue**: npm workspaces don't work well on Windows - -**Solution**: Dependencies installed separately in each app - -**Scripts modified**: Root package.json uses `cd` commands instead of workspace commands - -### 3. Docker Not Found - -**Issue**: Docker command not available during setup - -**Solution**: Install Docker Desktop, then start infrastructure: -```bash -docker-compose up -d -``` - ---- - -## 🎯 Ready to Code! - -Once Docker is installed, you're ready to start development: - -### Start Full Stack - -**Terminal 1** - Infrastructure: -```bash -docker-compose up -d -``` - -**Terminal 2** - Backend: -```bash -cd apps/backend -npm run dev -``` - -**Terminal 3** - Frontend: -```bash -cd apps/frontend -npm run dev -``` - -### Verify Everything Works - -- ✅ PostgreSQL: `docker exec -it xpeditis-postgres psql -U xpeditis -d xpeditis_dev` -- ✅ Redis: `docker exec -it xpeditis-redis redis-cli -a xpeditis_redis_password ping` -- ✅ Backend: -- ✅ API Docs: -- ✅ Frontend: - ---- - -## 📚 Documentation Index - -Quick links to all documentation: - -- **[START-HERE.md](START-HERE.md)** - 10-minute quickstart guide -- **[CLAUDE.md](CLAUDE.md)** - Architecture guidelines for development -- **[TODO.md](TODO.md)** - Complete development roadmap (30 weeks) -- **[WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md)** - Windows-specific setup guide -- **[INDEX.md](INDEX.md)** - Complete documentation index -- **[NEXT-STEPS.md](NEXT-STEPS.md)** - What to do after installation - -### Technical Documentation - -- **Backend**: [apps/backend/README.md](apps/backend/README.md) -- **Frontend**: [apps/frontend/README.md](apps/frontend/README.md) -- **PRD**: [PRD.md](PRD.md) - Product requirements (French) - ---- - -## 🎉 What's Next? - -### Immediate (Today) - -1. Install Docker Desktop -2. Start infrastructure: `docker-compose up -d` -3. Start backend: `cd apps/backend && npm run dev` -4. Start frontend: `cd apps/frontend && npm run dev` -5. Verify all endpoints work - -### Phase 1 - Domain Layer (Next Sprint) - -Start implementing the core business logic according to [TODO.md](TODO.md): - -1. **Domain Entities** (Week 1-2) - - Organization, User, RateQuote, Booking, Container - - Value Objects (Email, BookingNumber, PortCode) - - Domain Services - -2. **Repository Ports** (Week 2) - - Define interfaces for data persistence - - Cache port, Email port, Storage port - -3. **Use Cases** (Week 2) - - SearchRates port - - CreateBooking port - - ManageUser port - -See [NEXT-STEPS.md](NEXT-STEPS.md) for detailed Phase 1 tasks. - ---- - -## 📞 Need Help? - -If you encounter any issues: - -1. **Check documentation**: - - [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md) - Windows-specific issues - - [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Detailed setup steps - -2. **Common issues**: - - Backend won't start → Check Docker containers running - - Frontend build fails → Use `npm run dev` instead - - EISDIR errors → See Windows installation guide - -3. **Verify setup**: - ```bash - node --version # Should be v20+ - npm --version # Should be v10+ - docker --version # Should be installed - ``` - ---- - -**Installation Status**: ✅ Complete and Ready for Development - -**Next Action**: Install Docker Desktop, then start infrastructure and servers - -*Xpeditis - Maritime Freight Booking Platform* diff --git a/INSTALLATION-STEPS.md b/INSTALLATION-STEPS.md deleted file mode 100644 index ca457dc..0000000 --- a/INSTALLATION-STEPS.md +++ /dev/null @@ -1,464 +0,0 @@ -# 📦 Installation Steps - Xpeditis - -Complete step-by-step installation guide for the Xpeditis platform. - ---- - -## Current Status - -✅ **Sprint 0 Complete** - All infrastructure files created -⏳ **Dependencies** - Need to be installed -⏳ **Services** - Need to be started - ---- - -## Installation Instructions - -### Step 1: Install Dependencies - -The project uses npm workspaces. Run this command from the root directory: - -```bash -npm install -``` - -**What this does**: -- Installs root dependencies (prettier, typescript) -- Installs backend dependencies (~50 packages including NestJS, TypeORM, Redis, etc.) -- Installs frontend dependencies (~30 packages including Next.js, React, Tailwind, etc.) -- Links workspace packages - -**Expected Output**: -- This will take 2-3 minutes -- You may see deprecation warnings (these are normal) -- On Windows, you might see `EISDIR` symlink warnings (these can be ignored - dependencies are still installed) - -**Verification**: -```bash -# Check that node_modules exists -ls node_modules - -# Check backend dependencies -ls apps/backend/node_modules - -# Check frontend dependencies -ls apps/frontend/node_modules -``` - ---- - -### Step 2: Start Docker Infrastructure - -Start PostgreSQL and Redis: - -```bash -docker-compose up -d -``` - -**What this does**: -- Pulls PostgreSQL 15 Alpine image (if not cached) -- Pulls Redis 7 Alpine image (if not cached) -- Starts PostgreSQL on port 5432 -- Starts Redis on port 6379 -- Runs database initialization script -- Creates persistent volumes - -**Verification**: -```bash -# Check containers are running -docker-compose ps - -# Expected output: -# NAME STATUS PORTS -# xpeditis-postgres Up (healthy) 0.0.0.0:5432->5432/tcp -# xpeditis-redis Up (healthy) 0.0.0.0:6379->6379/tcp - -# Check logs -docker-compose logs - -# Test PostgreSQL connection -docker-compose exec postgres psql -U xpeditis -d xpeditis_dev -c "SELECT version();" - -# Test Redis connection -docker-compose exec redis redis-cli -a xpeditis_redis_password ping -# Should return: PONG -``` - ---- - -### Step 3: Setup Environment Variables - -#### Backend - -```bash -cp apps/backend/.env.example apps/backend/.env -``` - -**Default values work for local development!** You can start immediately. - -**Optional customization** (edit `apps/backend/.env`): -```env -# These work out of the box: -DATABASE_HOST=localhost -DATABASE_PORT=5432 -DATABASE_USER=xpeditis -DATABASE_PASSWORD=xpeditis_dev_password -DATABASE_NAME=xpeditis_dev - -REDIS_HOST=localhost -REDIS_PORT=6379 -REDIS_PASSWORD=xpeditis_redis_password - -JWT_SECRET=your-super-secret-jwt-key-change-this-in-production - -# Add these later when you have credentials: -# MAERSK_API_KEY=your-key -# GOOGLE_CLIENT_ID=your-client-id -# etc. -``` - -#### Frontend - -```bash -cp apps/frontend/.env.example apps/frontend/.env -``` - -**Default values**: -```env -NEXT_PUBLIC_API_URL=http://localhost:4000 -NEXT_PUBLIC_API_PREFIX=api/v1 -``` - ---- - -### Step 4: Start Backend Development Server - -```bash -# Option 1: From root -npm run backend:dev - -# Option 2: From backend directory -cd apps/backend -npm run dev -``` - -**What happens**: -- NestJS compiles TypeScript -- Connects to PostgreSQL -- Connects to Redis -- Starts server on port 4000 -- Watches for file changes (hot reload) - -**Expected output**: -``` -[Nest] 12345 - 10/07/2025, 3:00:00 PM LOG [NestFactory] Starting Nest application... -[Nest] 12345 - 10/07/2025, 3:00:00 PM LOG [InstanceLoader] ConfigModule dependencies initialized -[Nest] 12345 - 10/07/2025, 3:00:00 PM LOG [InstanceLoader] TypeOrmModule dependencies initialized -... - - ╔═══════════════════════════════════════╗ - ║ ║ - ║ 🚢 Xpeditis API Server Running ║ - ║ ║ - ║ API: http://localhost:4000/api/v1 ║ - ║ Docs: http://localhost:4000/api/docs ║ - ║ ║ - ╚═══════════════════════════════════════╝ -``` - -**Verification**: -```bash -# Test health endpoint -curl http://localhost:4000/api/v1/health - -# Or open in browser: -# http://localhost:4000/api/v1/health - -# Open Swagger docs: -# http://localhost:4000/api/docs -``` - ---- - -### Step 5: Start Frontend Development Server - -In a **new terminal**: - -```bash -# Option 1: From root -npm run frontend:dev - -# Option 2: From frontend directory -cd apps/frontend -npm run dev -``` - -**What happens**: -- Next.js compiles TypeScript -- Starts dev server on port 3000 -- Watches for file changes (hot reload) -- Enables Fast Refresh - -**Expected output**: -``` - ▲ Next.js 14.0.4 - - Local: http://localhost:3000 - - Network: http://192.168.1.x:3000 - - ✓ Ready in 2.3s -``` - -**Verification**: -```bash -# Open in browser: -# http://localhost:3000 - -# You should see the Xpeditis homepage -``` - ---- - -## ✅ Installation Complete! - -You should now have: - -| Service | URL | Status | -|---------|-----|--------| -| **Frontend** | http://localhost:3000 | ✅ Running | -| **Backend API** | http://localhost:4000/api/v1 | ✅ Running | -| **API Docs** | http://localhost:4000/api/docs | ✅ Running | -| **PostgreSQL** | localhost:5432 | ✅ Running | -| **Redis** | localhost:6379 | ✅ Running | - ---- - -## Troubleshooting - -### Issue: npm install fails - -**Solution**: -```bash -# Clear npm cache -npm cache clean --force - -# Delete node_modules -rm -rf node_modules apps/*/node_modules packages/*/node_modules - -# Retry -npm install -``` - -### Issue: Docker containers won't start - -**Solution**: -```bash -# Check Docker is running -docker --version - -# Check if ports are in use -# Windows: -netstat -ano | findstr :5432 -netstat -ano | findstr :6379 - -# Mac/Linux: -lsof -i :5432 -lsof -i :6379 - -# Stop any conflicting services -# Then retry: -docker-compose up -d -``` - -### Issue: Backend won't connect to database - -**Solution**: -```bash -# Check PostgreSQL is running -docker-compose ps - -# Check PostgreSQL logs -docker-compose logs postgres - -# Verify connection manually -docker-compose exec postgres psql -U xpeditis -d xpeditis_dev - -# If that works, check your .env file: -# DATABASE_HOST=localhost (not 127.0.0.1) -# DATABASE_PORT=5432 -# DATABASE_USER=xpeditis -# DATABASE_PASSWORD=xpeditis_dev_password -# DATABASE_NAME=xpeditis_dev -``` - -### Issue: Port 4000 or 3000 already in use - -**Solution**: -```bash -# Find what's using the port -# Windows: -netstat -ano | findstr :4000 - -# Mac/Linux: -lsof -i :4000 - -# Kill the process or change the port in: -# Backend: apps/backend/.env (PORT=4000) -# Frontend: package.json dev script or use -p flag -``` - -### Issue: Module not found errors - -**Solution**: -```bash -# Backend -cd apps/backend -npm install - -# Frontend -cd apps/frontend -npm install - -# If still failing, check tsconfig.json paths are correct -``` - ---- - -## Common Development Tasks - -### View Logs - -```bash -# Backend logs (already in terminal) - -# Docker logs -docker-compose logs -f - -# PostgreSQL logs only -docker-compose logs -f postgres - -# Redis logs only -docker-compose logs -f redis -``` - -### Database Operations - -```bash -# Connect to PostgreSQL -docker-compose exec postgres psql -U xpeditis -d xpeditis_dev - -# List tables -\dt - -# Describe a table -\d table_name - -# Run migrations (when created) -cd apps/backend -npm run migration:run -``` - -### Redis Operations - -```bash -# Connect to Redis -docker-compose exec redis redis-cli -a xpeditis_redis_password - -# List all keys -KEYS * - -# Get a value -GET key_name - -# Flush all data -FLUSHALL -``` - -### Run Tests - -```bash -# Backend unit tests -cd apps/backend -npm test - -# Backend tests with coverage -npm run test:cov - -# Backend E2E tests -npm run test:e2e - -# Frontend tests -cd apps/frontend -npm test - -# All tests -npm run test:all -``` - -### Code Quality - -```bash -# Format code -npm run format - -# Check formatting -npm run format:check - -# Lint backend -npm run backend:lint - -# Lint frontend -npm run frontend:lint -``` - ---- - -## Next Steps - -Now that everything is installed and running: - -1. **📚 Read the docs**: - - [QUICK-START.md](QUICK-START.md) - Quick reference - - [README.md](README.md) - Full documentation - - [CLAUDE.md](CLAUDE.md) - Architecture guidelines - -2. **🛠️ Start developing**: - - Check [TODO.md](TODO.md) for the roadmap - - Review [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) for what's done - - Begin Phase 1: Domain entities and ports - -3. **🧪 Write tests**: - - Domain layer tests (90%+ coverage target) - - Integration tests for repositories - - E2E tests for API endpoints - -4. **🚀 Deploy** (when ready): - - Review production checklist in SPRINT-0-FINAL.md - - Update environment variables - - Setup CI/CD pipelines - ---- - -## Success Checklist - -Before moving to Phase 1, verify: - -- [ ] `npm install` completed successfully -- [ ] Docker containers running (postgres + redis) -- [ ] Backend starts without errors -- [ ] Frontend starts without errors -- [ ] Health endpoint returns 200 OK -- [ ] Swagger docs accessible -- [ ] Frontend homepage loads -- [ ] Tests pass (`npm test`) -- [ ] No TypeScript errors -- [ ] Hot reload works (edit a file, see changes) - ---- - -**You're ready to build! 🎉** - -For questions, check the documentation or open an issue on GitHub. - ---- - -*Xpeditis - Maritime Freight Booking Platform* diff --git a/NEXT-STEPS.md b/NEXT-STEPS.md deleted file mode 100644 index 5ee6263..0000000 --- a/NEXT-STEPS.md +++ /dev/null @@ -1,471 +0,0 @@ -# 🚀 Next Steps - Getting Started with Development - -You've successfully completed Sprint 0! Here's what to do next. - ---- - -## 🎯 Immediate Actions (Today) - -### 1. Install Dependencies - -```bash -# From the root directory -npm install -``` - -**Expected**: This will take 2-3 minutes. You may see some deprecation warnings (normal). - -**On Windows**: If you see `EISDIR` symlink errors, that's okay - dependencies are still installed. - -### 2. Start Docker Services - -```bash -docker-compose up -d -``` - -**Expected**: PostgreSQL and Redis containers will start. - -**Verify**: -```bash -docker-compose ps - -# You should see: -# xpeditis-postgres - Up (healthy) -# xpeditis-redis - Up (healthy) -``` - -### 3. Setup Environment Files - -```bash -# Backend -cp apps/backend/.env.example apps/backend/.env - -# Frontend -cp apps/frontend/.env.example apps/frontend/.env -``` - -**Note**: Default values work for local development. No changes needed! - -### 4. Start the Backend - -```bash -# Option 1: From root -npm run backend:dev - -# Option 2: From backend directory -cd apps/backend -npm run dev -``` - -**Expected Output**: -``` -╔═══════════════════════════════════════╗ -║ 🚢 Xpeditis API Server Running ║ -║ API: http://localhost:4000/api/v1 ║ -║ Docs: http://localhost:4000/api/docs ║ -╚═══════════════════════════════════════╝ -``` - -**Verify**: Open http://localhost:4000/api/v1/health - -### 5. Start the Frontend (New Terminal) - -```bash -# Option 1: From root -npm run frontend:dev - -# Option 2: From frontend directory -cd apps/frontend -npm run dev -``` - -**Expected Output**: -``` -▲ Next.js 14.0.4 -- Local: http://localhost:3000 -✓ Ready in 2.3s -``` - -**Verify**: Open http://localhost:3000 - ---- - -## ✅ Verification Checklist - -Before proceeding to development, verify: - -- [ ] `npm install` completed successfully -- [ ] Docker containers are running (check with `docker-compose ps`) -- [ ] Backend starts without errors -- [ ] Health endpoint returns 200 OK: http://localhost:4000/api/v1/health -- [ ] Swagger docs accessible: http://localhost:4000/api/docs -- [ ] Frontend loads: http://localhost:3000 -- [ ] No TypeScript compilation errors - -**All green? You're ready to start Phase 1! 🎉** - ---- - -## 📅 Phase 1 - Core Search & Carrier Integration (Next 6-8 weeks) - -### Week 1-2: Domain Layer & Port Definitions - -**Your first tasks**: - -#### 1. Create Domain Entities - -Create these files in `apps/backend/src/domain/entities/`: - -```typescript -// organization.entity.ts -export class Organization { - constructor( - public readonly id: string, - public readonly name: string, - public readonly type: 'FREIGHT_FORWARDER' | 'NVOCC' | 'DIRECT_SHIPPER', - public readonly scac?: string, - public readonly address?: Address, - public readonly logoUrl?: string, - ) {} -} - -// user.entity.ts -export class User { - constructor( - public readonly id: string, - public readonly organizationId: string, - public readonly email: Email, // Value Object - public readonly role: UserRole, - public readonly passwordHash: string, - ) {} -} - -// rate-quote.entity.ts -export class RateQuote { - constructor( - public readonly id: string, - public readonly origin: PortCode, // Value Object - public readonly destination: PortCode, // Value Object - public readonly carrierId: string, - public readonly price: Money, // Value Object - public readonly surcharges: Surcharge[], - public readonly etd: Date, - public readonly eta: Date, - public readonly transitDays: number, - public readonly route: RouteStop[], - public readonly availability: number, - ) {} -} - -// More entities: Carrier, Port, Container, Booking -``` - -#### 2. Create Value Objects - -Create these files in `apps/backend/src/domain/value-objects/`: - -```typescript -// email.vo.ts -export class Email { - private constructor(private readonly value: string) { - this.validate(value); - } - - static create(value: string): Email { - return new Email(value); - } - - private validate(value: string): void { - const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; - if (!emailRegex.test(value)) { - throw new InvalidEmailException(value); - } - } - - getValue(): string { - return this.value; - } -} - -// port-code.vo.ts -export class PortCode { - private constructor(private readonly value: string) { - this.validate(value); - } - - static create(value: string): PortCode { - return new PortCode(value.toUpperCase()); - } - - private validate(value: string): void { - // UN LOCODE format: 5 characters (CCCCC) - if (!/^[A-Z]{5}$/.test(value)) { - throw new InvalidPortCodeException(value); - } - } - - getValue(): string { - return this.value; - } -} - -// More VOs: Money, ContainerType, BookingNumber, DateRange -``` - -#### 3. Define Ports - -**API Ports (domain/ports/in/)** - What the domain exposes: - -```typescript -// search-rates.port.ts -export interface SearchRatesPort { - execute(input: RateSearchInput): Promise; -} - -export interface RateSearchInput { - origin: PortCode; - destination: PortCode; - containerType: ContainerType; - mode: 'FCL' | 'LCL'; - departureDate: Date; - weight?: number; - volume?: number; - hazmat: boolean; -} -``` - -**SPI Ports (domain/ports/out/)** - What the domain needs: - -```typescript -// rate-quote.repository.ts -export interface RateQuoteRepository { - save(rateQuote: RateQuote): Promise; - findById(id: string): Promise; - findByRoute(origin: PortCode, destination: PortCode): Promise; -} - -// carrier-connector.port.ts -export interface CarrierConnectorPort { - searchRates(input: RateSearchInput): Promise; - checkAvailability(input: AvailabilityInput): Promise; -} - -// cache.port.ts -export interface CachePort { - get(key: string): Promise; - set(key: string, value: T, ttl: number): Promise; - delete(key: string): Promise; -} -``` - -#### 4. Write Domain Tests - -```typescript -// domain/services/rate-search.service.spec.ts -describe('RateSearchService', () => { - let service: RateSearchService; - let mockCache: jest.Mocked; - let mockConnectors: jest.Mocked[]; - - beforeEach(() => { - mockCache = createMockCache(); - mockConnectors = [createMockConnector('Maersk')]; - service = new RateSearchService(mockCache, mockConnectors); - }); - - it('should return cached rates if available', async () => { - const input = createTestRateSearchInput(); - const cachedRates = [createTestRateQuote()]; - mockCache.get.mockResolvedValue(cachedRates); - - const result = await service.execute(input); - - expect(result).toEqual(cachedRates); - expect(mockConnectors[0].searchRates).not.toHaveBeenCalled(); - }); - - it('should query carriers if cache miss', async () => { - const input = createTestRateSearchInput(); - mockCache.get.mockResolvedValue(null); - const carrierRates = [createTestRateQuote()]; - mockConnectors[0].searchRates.mockResolvedValue(carrierRates); - - const result = await service.execute(input); - - expect(result).toEqual(carrierRates); - expect(mockCache.set).toHaveBeenCalledWith( - expect.any(String), - carrierRates, - 900, // 15 minutes - ); - }); - - // Target: 90%+ coverage for domain -}); -``` - ---- - -## 📚 Recommended Reading Order - -Before starting development, read these in order: - -1. **[QUICK-START.md](QUICK-START.md)** (5 min) - - Get everything running - -2. **[CLAUDE.md](CLAUDE.md)** (30 min) - - Understand hexagonal architecture - - Learn the rules for each layer - - See complete examples - -3. **[apps/backend/README.md](apps/backend/README.md)** (10 min) - - Backend-specific guidelines - - Available scripts - - Testing strategy - -4. **[TODO.md](TODO.md)** - Sections relevant to current sprint (20 min) - - Detailed task breakdown - - Acceptance criteria - - Technical specifications - ---- - -## 🛠️ Development Guidelines - -### Hexagonal Architecture Rules - -**Domain Layer** (`src/domain/`): -- ✅ Pure TypeScript classes -- ✅ Define interfaces (ports) -- ✅ Business logic only -- ❌ NO imports from NestJS, TypeORM, or any framework -- ❌ NO decorators (@Injectable, @Column, etc.) - -**Application Layer** (`src/application/`): -- ✅ Import from `@domain/*` only -- ✅ Controllers, DTOs, Mappers -- ✅ Handle HTTP-specific concerns -- ❌ NO business logic - -**Infrastructure Layer** (`src/infrastructure/`): -- ✅ Import from `@domain/*` only -- ✅ Implement port interfaces -- ✅ Framework-specific code (TypeORM, Redis, etc.) -- ❌ NO business logic - -### Testing Strategy - -- **Domain**: 90%+ coverage, test without any framework -- **Application**: 80%+ coverage, test DTOs and mappings -- **Infrastructure**: 70%+ coverage, test with test databases - -### Git Workflow - -```bash -# Create feature branch -git checkout -b feature/domain-entities - -# Make changes and commit -git add . -git commit -m "feat: add Organization and User domain entities" - -# Push and create PR -git push origin feature/domain-entities -``` - ---- - -## 🎯 Success Criteria for Week 1-2 - -By the end of Sprint 1-2, you should have: - -- [ ] All core domain entities created (Organization, User, RateQuote, Carrier, Port, Container) -- [ ] All value objects created (Email, PortCode, Money, ContainerType, etc.) -- [ ] All API ports defined (SearchRatesPort, CreateBookingPort, etc.) -- [ ] All SPI ports defined (Repositories, CarrierConnectorPort, CachePort, etc.) -- [ ] Domain services implemented (RateSearchService, BookingService, etc.) -- [ ] Domain unit tests written (90%+ coverage) -- [ ] All tests passing -- [ ] No TypeScript errors -- [ ] Code formatted and linted - ---- - -## 💡 Tips for Success - -### 1. Start Small -Don't try to implement everything at once. Start with: -- One entity (e.g., Organization) -- One value object (e.g., Email) -- One port (e.g., SearchRatesPort) -- Tests for what you created - -### 2. Test First (TDD) -```typescript -// 1. Write the test -it('should create organization with valid data', () => { - const org = new Organization('1', 'ACME Freight', 'FREIGHT_FORWARDER'); - expect(org.name).toBe('ACME Freight'); -}); - -// 2. Implement the entity -export class Organization { /* ... */ } - -// 3. Run the test -npm test - -// 4. Refactor if needed -``` - -### 3. Follow Patterns -Look at examples in CLAUDE.md and copy the structure: -- Entities are classes with readonly properties -- Value objects validate in the constructor -- Ports are interfaces -- Services implement ports - -### 4. Ask Questions -If something is unclear: -- Re-read CLAUDE.md -- Check TODO.md for specifications -- Look at the PRD.md for business context - -### 5. Commit Often -```bash -git add . -git commit -m "feat: add Email value object with validation" -# Small, focused commits are better -``` - ---- - -## 📞 Need Help? - -**Documentation**: -- [QUICK-START.md](QUICK-START.md) - Setup issues -- [CLAUDE.md](CLAUDE.md) - Architecture questions -- [TODO.md](TODO.md) - Task details -- [apps/backend/README.md](apps/backend/README.md) - Backend specifics - -**Troubleshooting**: -- [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Common issues - -**Architecture**: -- Read the hexagonal architecture guidelines in CLAUDE.md -- Study the example flows at the end of CLAUDE.md - ---- - -## 🎉 You're Ready! - -**Current Status**: ✅ Sprint 0 Complete -**Next Milestone**: Sprint 1-2 - Domain Layer -**Timeline**: 2 weeks -**Focus**: Create all domain entities, value objects, and ports - -**Let's build something amazing! 🚀** - ---- - -*Xpeditis MVP - Maritime Freight Booking Platform* -*Good luck with Phase 1!* diff --git a/QUICK-START.md b/QUICK-START.md deleted file mode 100644 index 04f7f5e..0000000 --- a/QUICK-START.md +++ /dev/null @@ -1,302 +0,0 @@ -# 🚀 Quick Start Guide - Xpeditis - -Get the Xpeditis maritime freight booking platform running in **5 minutes**. - ---- - -## Prerequisites - -Before you begin, ensure you have: - -- ✅ **Node.js** v20+ ([Download](https://nodejs.org/)) -- ✅ **npm** v10+ (comes with Node.js) -- ✅ **Docker Desktop** ([Download](https://www.docker.com/products/docker-desktop/)) -- ✅ **Git** ([Download](https://git-scm.com/)) - ---- - -## Step 1: Clone & Install (2 minutes) - -```bash -# Clone the repository -cd xpeditis2.0 - -# Install all dependencies -npm install - -# This will install: -# - Root workspace dependencies -# - Backend dependencies (~50 packages) -# - Frontend dependencies (~30 packages) -``` - -**Note**: If you encounter `EISDIR` errors on Windows, it's okay - the dependencies are still installed correctly. - ---- - -## Step 2: Start Infrastructure (1 minute) - -```bash -# Start PostgreSQL + Redis with Docker -docker-compose up -d - -# Verify containers are running -docker-compose ps - -# You should see: -# ✅ xpeditis-postgres (port 5432) -# ✅ xpeditis-redis (port 6379) -``` - ---- - -## Step 3: Configure Environment (1 minute) - -```bash -# Backend -cp apps/backend/.env.example apps/backend/.env - -# Frontend -cp apps/frontend/.env.example apps/frontend/.env -``` - -**The default `.env` values work for local development!** No changes needed to get started. - ---- - -## Step 4: Start Development Servers (1 minute) - -### Option A: Two Terminals - -```bash -# Terminal 1 - Backend -cd apps/backend -npm run dev - -# Terminal 2 - Frontend -cd apps/frontend -npm run dev -``` - -### Option B: Root Commands - -```bash -# Terminal 1 - Backend -npm run backend:dev - -# Terminal 2 - Frontend -npm run frontend:dev -``` - ---- - -## Step 5: Verify Everything Works - -### Backend ✅ - -Open: **http://localhost:4000/api/v1/health** - -Expected response: -```json -{ - "status": "ok", - "timestamp": "2025-10-07T...", - "uptime": 12.345, - "environment": "development", - "version": "0.1.0" -} -``` - -### API Documentation ✅ - -Open: **http://localhost:4000/api/docs** - -You should see the Swagger UI with: -- Health endpoints -- (More endpoints will be added in Phase 1) - -### Frontend ✅ - -Open: **http://localhost:3000** - -You should see: -``` -🚢 Xpeditis -Maritime Freight Booking Platform -Search, compare, and book maritime freight in real-time -``` - ---- - -## 🎉 Success! - -You now have: -- ✅ Backend API running on port 4000 -- ✅ Frontend app running on port 3000 -- ✅ PostgreSQL database on port 5432 -- ✅ Redis cache on port 6379 -- ✅ Swagger API docs available -- ✅ Hot reload enabled for both apps - ---- - -## Common Commands - -### Development - -```bash -# Backend -npm run backend:dev # Start backend dev server -npm run backend:test # Run backend tests -npm run backend:test:watch # Run tests in watch mode -npm run backend:lint # Lint backend code - -# Frontend -npm run frontend:dev # Start frontend dev server -npm run frontend:build # Build for production -npm run frontend:test # Run frontend tests -npm run frontend:lint # Lint frontend code - -# Both -npm run format # Format all code -npm run format:check # Check formatting -npm run test:all # Run all tests -``` - -### Infrastructure - -```bash -# Docker -docker-compose up -d # Start services -docker-compose down # Stop services -docker-compose logs -f # View logs -docker-compose ps # Check status - -# Database -docker-compose exec postgres psql -U xpeditis -d xpeditis_dev - -# Redis -docker-compose exec redis redis-cli -a xpeditis_redis_password -``` - ---- - -## Troubleshooting - -### Port Already in Use - -```bash -# Backend (port 4000) -# Windows: netstat -ano | findstr :4000 -# Mac/Linux: lsof -i :4000 - -# Frontend (port 3000) -# Windows: netstat -ano | findstr :3000 -# Mac/Linux: lsof -i :3000 -``` - -### Docker Not Starting - -```bash -# Check Docker is running -docker --version - -# Restart Docker Desktop -# Then retry: docker-compose up -d -``` - -### Database Connection Issues - -```bash -# Check PostgreSQL is running -docker-compose ps - -# View PostgreSQL logs -docker-compose logs postgres - -# Restart PostgreSQL -docker-compose restart postgres -``` - -### npm Install Errors - -```bash -# Clear cache and retry -npm cache clean --force -rm -rf node_modules -npm install -``` - ---- - -## Next Steps - -### 📚 Read the Documentation - -- [README.md](README.md) - Full project documentation -- [CLAUDE.md](CLAUDE.md) - Hexagonal architecture guidelines -- [TODO.md](TODO.md) - 30-week development roadmap -- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Sprint 0 completion report - -### 🛠️ Start Building - -Ready to start Phase 1? Check out [TODO.md](TODO.md) for the roadmap: - -- **Sprint 1-2**: Domain entities and ports -- **Sprint 3-4**: Infrastructure and database -- **Sprint 5-6**: Rate search API -- **Sprint 7-8**: Rate search UI - -### 🧪 Run Tests - -```bash -# Backend unit tests -cd apps/backend -npm test - -# Backend E2E tests -npm run test:e2e - -# Frontend tests -cd apps/frontend -npm test -``` - -### 🔍 Explore the Code - -**Hexagonal Architecture**: -``` -apps/backend/src/ -├── domain/ # Pure business logic (start here!) -├── application/ # Controllers & DTOs -└── infrastructure/ # External adapters -``` - -**Frontend Structure**: -``` -apps/frontend/ -├── app/ # Next.js App Router -├── components/ # React components -└── lib/ # Utilities -``` - ---- - -## 🎯 You're Ready! - -The Xpeditis development environment is fully set up and ready for Phase 1 development. - -**Happy coding! 🚀** - ---- - -## Need Help? - -- 📖 Check [README.md](README.md) for detailed documentation -- 🏗️ Review [CLAUDE.md](CLAUDE.md) for architecture guidelines -- 📝 Follow [TODO.md](TODO.md) for the development roadmap -- ❓ Open an issue on GitHub - ---- - -*Xpeditis - Maritime Freight Booking Platform* diff --git a/READY.md b/READY.md deleted file mode 100644 index 1b0d123..0000000 --- a/READY.md +++ /dev/null @@ -1,412 +0,0 @@ -# ✅ Xpeditis MVP - READY FOR DEVELOPMENT - -## 🎉 Sprint 0 Successfully Completed! - -**Project**: Xpeditis - Maritime Freight Booking Platform -**Status**: 🟢 **READY FOR PHASE 1** -**Completion Date**: October 7, 2025 -**Sprint 0**: 100% Complete - ---- - -## 📦 What Has Been Created - -### 📄 Documentation Suite (11 files, 4000+ lines) - -1. **[README.md](README.md)** - Project overview -2. **[CLAUDE.md](CLAUDE.md)** - Hexagonal architecture guide (476 lines) -3. **[PRD.md](PRD.md)** - Product requirements (352 lines) -4. **[TODO.md](TODO.md)** - 30-week roadmap (1000+ lines) -5. **[QUICK-START.md](QUICK-START.md)** - 5-minute setup guide -6. **[INSTALLATION-STEPS.md](INSTALLATION-STEPS.md)** - Detailed installation -7. **[NEXT-STEPS.md](NEXT-STEPS.md)** - What to do next -8. **[SPRINT-0-FINAL.md](SPRINT-0-FINAL.md)** - Complete sprint report -9. **[SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md)** - Executive summary -10. **[INDEX.md](INDEX.md)** - Documentation index -11. **[READY.md](READY.md)** - This file - -### 🏗️ Backend (NestJS + Hexagonal Architecture) - -**Folder Structure**: -``` -apps/backend/src/ -├── domain/ ✅ Pure business logic layer -│ ├── entities/ -│ ├── value-objects/ -│ ├── services/ -│ ├── ports/in/ -│ ├── ports/out/ -│ └── exceptions/ -├── application/ ✅ Controllers & DTOs -│ ├── controllers/ -│ ├── dto/ -│ ├── mappers/ -│ └── config/ -└── infrastructure/ ✅ External adapters - ├── persistence/ - ├── cache/ - ├── carriers/ - ├── email/ - ├── storage/ - └── config/ -``` - -**Files Created** (15+): -- ✅ package.json (50+ dependencies) -- ✅ tsconfig.json (strict mode + path aliases) -- ✅ nest-cli.json -- ✅ .eslintrc.js -- ✅ .env.example (all variables documented) -- ✅ src/main.ts (bootstrap with Swagger) -- ✅ src/app.module.ts (root module) -- ✅ src/application/controllers/health.controller.ts -- ✅ test/app.e2e-spec.ts -- ✅ test/jest-e2e.json -- ✅ README.md (backend guide) - -**Features**: -- ✅ Hexagonal architecture properly implemented -- ✅ TypeScript strict mode -- ✅ Swagger API docs at /api/docs -- ✅ Health check endpoints -- ✅ Pino structured logging -- ✅ Environment validation (Joi) -- ✅ Jest testing infrastructure -- ✅ Security configured (helmet, CORS, JWT) - -### 🎨 Frontend (Next.js 14 + TypeScript) - -**Folder Structure**: -``` -apps/frontend/ -├── app/ ✅ Next.js App Router -│ ├── layout.tsx -│ ├── page.tsx -│ └── globals.css -├── components/ ✅ Ready for components -│ └── ui/ -├── lib/ ✅ Utilities -│ ├── api/ -│ ├── hooks/ -│ └── utils.ts -└── public/ ✅ Static assets -``` - -**Files Created** (12+): -- ✅ package.json (30+ dependencies) -- ✅ tsconfig.json (path aliases) -- ✅ next.config.js -- ✅ tailwind.config.ts -- ✅ postcss.config.js -- ✅ .eslintrc.json -- ✅ .env.example -- ✅ app/layout.tsx -- ✅ app/page.tsx -- ✅ app/globals.css (Tailwind + CSS variables) -- ✅ lib/utils.ts (cn helper) -- ✅ README.md (frontend guide) - -**Features**: -- ✅ Next.js 14 with App Router -- ✅ TypeScript strict mode -- ✅ Tailwind CSS with custom theme -- ✅ shadcn/ui components ready -- ✅ Dark mode support (CSS variables) -- ✅ TanStack Query configured -- ✅ react-hook-form + zod validation -- ✅ Jest + Playwright testing ready - -### 🐳 Docker Infrastructure - -**Files Created**: -- ✅ docker-compose.yml -- ✅ infra/postgres/init.sql - -**Services**: -- ✅ PostgreSQL 15 (port 5432) - - Database: xpeditis_dev - - User: xpeditis - - Extensions: uuid-ossp, pg_trgm - - Health checks enabled - - Persistent volumes - -- ✅ Redis 7 (port 6379) - - Password protected - - AOF persistence - - Health checks enabled - - Persistent volumes - -### 🔄 CI/CD Pipelines - -**GitHub Actions Workflows**: -- ✅ .github/workflows/ci.yml - - Lint & format check - - Backend tests (unit + E2E) - - Frontend tests - - Build verification - - Code coverage upload - -- ✅ .github/workflows/security.yml - - npm audit (weekly) - - Dependency review (PRs) - -- ✅ .github/pull_request_template.md - - Structured PR template - - Architecture compliance checklist - -### 📝 Configuration Files - -**Root Level**: -- ✅ package.json (workspace configuration) -- ✅ .gitignore -- ✅ .prettierrc -- ✅ .prettierignore - -**Per App**: -- ✅ Backend: tsconfig, nest-cli, eslint, env.example -- ✅ Frontend: tsconfig, next.config, tailwind.config, postcss.config - ---- - -## 🎯 Ready For Phase 1 - -### ✅ All Sprint 0 Objectives Met - -| Objective | Status | Notes | -|-----------|--------|-------| -| Monorepo structure | ✅ Complete | npm workspaces configured | -| Backend hexagonal arch | ✅ Complete | Domain/Application/Infrastructure | -| Frontend Next.js 14 | ✅ Complete | App Router + TypeScript | -| Docker infrastructure | ✅ Complete | PostgreSQL + Redis | -| TypeScript strict mode | ✅ Complete | All projects | -| Testing infrastructure | ✅ Complete | Jest, Supertest, Playwright | -| CI/CD pipelines | ✅ Complete | GitHub Actions | -| API documentation | ✅ Complete | Swagger at /api/docs | -| Logging | ✅ Complete | Pino structured logging | -| Security foundations | ✅ Complete | Helmet, JWT, CORS, rate limiting | -| Environment validation | ✅ Complete | Joi schema validation | -| Health endpoints | ✅ Complete | /health, /ready, /live | -| Documentation | ✅ Complete | 11 comprehensive files | - ---- - -## 🚀 Next Actions - -### 1. Install Dependencies (3 minutes) - -```bash -npm install -``` - -Expected: ~80 packages installed - -### 2. Start Infrastructure (1 minute) - -```bash -docker-compose up -d -``` - -Expected: PostgreSQL + Redis running - -### 3. Configure Environment (30 seconds) - -```bash -cp apps/backend/.env.example apps/backend/.env -cp apps/frontend/.env.example apps/frontend/.env -``` - -Expected: Default values work immediately - -### 4. Start Development (1 minute) - -**Terminal 1 - Backend**: -```bash -npm run backend:dev -``` - -Expected: Server at http://localhost:4000 - -**Terminal 2 - Frontend**: -```bash -npm run frontend:dev -``` - -Expected: App at http://localhost:3000 - -### 5. Verify (1 minute) - -- ✅ Backend health: http://localhost:4000/api/v1/health -- ✅ API docs: http://localhost:4000/api/docs -- ✅ Frontend: http://localhost:3000 -- ✅ Docker: `docker-compose ps` - ---- - -## 📚 Start Reading - -**New developers start here** (2 hours): - -1. **[QUICK-START.md](QUICK-START.md)** (30 min) - - Get everything running - - Verify installation - -2. **[CLAUDE.md](CLAUDE.md)** (60 min) - - **MUST READ** for architecture - - Hexagonal architecture principles - - Layer responsibilities - - Complete examples - -3. **[NEXT-STEPS.md](NEXT-STEPS.md)** (30 min) - - What to build first - - Code examples - - Testing strategy - -4. **[TODO.md](TODO.md)** - Sprint 1-2 section (30 min) - - Detailed task breakdown - - Acceptance criteria - ---- - -## 🎯 Phase 1 Goals (Weeks 1-8) - -### Sprint 1-2: Domain Layer (Weeks 1-2) - -**Your first tasks**: -- [ ] Create domain entities (Organization, User, RateQuote, Carrier, Port, Container) -- [ ] Create value objects (Email, PortCode, Money, ContainerType) -- [ ] Define API ports (SearchRatesPort, CreateBookingPort) -- [ ] Define SPI ports (Repositories, CarrierConnectorPort, CachePort) -- [ ] Implement domain services -- [ ] Write domain unit tests (90%+ coverage) - -**Where to start**: See [NEXT-STEPS.md](NEXT-STEPS.md) for code examples - -### Sprint 3-4: Infrastructure Layer (Weeks 3-4) - -- [ ] Design database schema (ERD) -- [ ] Create TypeORM entities -- [ ] Implement repositories -- [ ] Create migrations -- [ ] Seed data (carriers, ports) -- [ ] Implement Redis cache adapter -- [ ] Create Maersk connector -- [ ] Integration tests - -### Sprint 5-6: Application Layer (Weeks 5-6) - -- [ ] Create DTOs and mappers -- [ ] Implement controllers (RatesController, PortsController) -- [ ] Complete OpenAPI documentation -- [ ] Implement caching strategy -- [ ] Performance optimization -- [ ] E2E tests - -### Sprint 7-8: Frontend UI (Weeks 7-8) - -- [ ] Search form components -- [ ] Port autocomplete -- [ ] Results display (cards + table) -- [ ] Filtering & sorting -- [ ] Export functionality -- [ ] Responsive design -- [ ] Frontend tests - ---- - -## 📊 Success Metrics - -### Technical Metrics (Sprint 0 - Achieved) - -- ✅ Project structure: Complete -- ✅ Backend setup: Complete -- ✅ Frontend setup: Complete -- ✅ Docker infrastructure: Complete -- ✅ CI/CD pipelines: Complete -- ✅ Documentation: 11 files, 4000+ lines -- ✅ Configuration: All files created -- ✅ Testing infrastructure: Ready - -### Phase 1 Metrics (Target) - -- 🎯 Domain entities: All created -- 🎯 Domain tests: 90%+ coverage -- 🎯 Database schema: Designed and migrated -- 🎯 Carrier connectors: At least 1 (Maersk) -- 🎯 Rate search API: Functional -- 🎯 Rate search UI: Responsive -- 🎯 Cache hit ratio: >90% -- 🎯 API response time: <2s - ---- - -## 🎉 Summary - -**Sprint 0**: ✅ **100% COMPLETE** - -**Created**: -- 📄 11 documentation files (4000+ lines) -- 🏗️ Complete hexagonal architecture (backend) -- 🎨 Modern React setup (frontend) -- 🐳 Docker infrastructure (PostgreSQL + Redis) -- 🔄 CI/CD pipelines (GitHub Actions) -- ⚙️ 50+ configuration files -- 📦 80+ dependencies installed - -**Ready For**: -- ✅ Domain modeling -- ✅ Database design -- ✅ API development -- ✅ Frontend development -- ✅ Testing -- ✅ Deployment - -**Time to Phase 1**: **NOW! 🚀** - ---- - -## 🎓 Learning Resources - -**Architecture**: -- [Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/) -- [Domain-Driven Design](https://martinfowler.com/bliki/DomainDrivenDesign.html) -- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) - -**Frameworks**: -- [NestJS Documentation](https://docs.nestjs.com/) -- [Next.js Documentation](https://nextjs.org/docs) -- [TypeORM Documentation](https://typeorm.io/) - -**Internal**: -- [CLAUDE.md](CLAUDE.md) - Our architecture guide -- [apps/backend/README.md](apps/backend/README.md) - Backend specifics -- [apps/frontend/README.md](apps/frontend/README.md) - Frontend specifics - ---- - -## 🎊 Congratulations! - -**You have a production-ready foundation for the Xpeditis MVP.** - -Everything is in place to start building: -- 🏗️ Architecture: Solid and scalable -- 📚 Documentation: Comprehensive -- ⚙️ Configuration: Complete -- 🧪 Testing: Ready -- 🚀 CI/CD: Automated - -**Let's build something amazing! 🚢** - ---- - -**Status**: 🟢 **READY FOR DEVELOPMENT** -**Next Sprint**: Sprint 1-2 - Domain Layer -**Start Date**: Today -**Duration**: 2 weeks - -**Good luck with Phase 1!** 🎯 - ---- - -*Xpeditis MVP - Maritime Freight Booking Platform* -*Sprint 0 Complete - October 7, 2025* -*Ready for Phase 1 Development* diff --git a/SPRINT-0-COMPLETE.md b/SPRINT-0-COMPLETE.md deleted file mode 100644 index c5bcf4b..0000000 --- a/SPRINT-0-COMPLETE.md +++ /dev/null @@ -1,271 +0,0 @@ -# Sprint 0 - Project Setup & Infrastructure ✅ - -## Completed Tasks - -### ✅ 1. Monorepo Structure Initialized -- Created workspace structure with npm workspaces -- Organized into `apps/` (backend, frontend) and `packages/` (shared-types, domain) -- Setup root `package.json` with workspace configuration -- Created `.gitignore`, `.prettierrc`, and `.prettierignore` -- Created comprehensive README.md - -### ✅ 2. Backend Setup (NestJS + Hexagonal Architecture) -- **Package Configuration**: Full `package.json` with all NestJS dependencies -- **TypeScript**: Strict mode enabled with path aliases for hexagonal architecture -- **Hexagonal Folder Structure**: - ``` - src/ - ├── domain/ # Pure business logic (NO external dependencies) - │ ├── entities/ - │ ├── value-objects/ - │ ├── services/ - │ ├── ports/ - │ │ ├── in/ # API Ports (Use Cases) - │ │ └── out/ # SPI Ports (Repositories, External Services) - │ └── exceptions/ - ├── application/ # Controllers & DTOs - │ ├── controllers/ - │ ├── dto/ - │ ├── mappers/ - │ └── config/ - └── infrastructure/ # External integrations - ├── persistence/ - │ └── typeorm/ - ├── cache/ - ├── carriers/ - ├── email/ - ├── storage/ - └── config/ - ``` -- **Main Files**: - - `main.ts`: Bootstrap with Swagger, helmet, validation pipes - - `app.module.ts`: Root module with ConfigModule, LoggerModule, TypeORM - - `health.controller.ts`: Health check endpoints (/health, /ready, /live) -- **Configuration**: - - `.env.example`: All environment variables documented - - `nest-cli.json`: NestJS CLI configuration - - `.eslintrc.js`: ESLint with TypeScript rules -- **Testing**: Jest configured with path aliases - -### ✅ 3. Frontend Setup (Next.js 14) -- **Package Configuration**: Full `package.json` with Next.js 14, React 18, TailwindCSS -- **Dependencies Added**: - - UI: Radix UI components, Tailwind CSS, lucide-react (icons) - - State Management: TanStack Query (React Query) - - Forms: react-hook-form + zod validation - - HTTP: axios - - Testing: Jest, React Testing Library, Playwright - -### ✅ 4. Docker Compose Configuration -- **PostgreSQL 15**: - - Database: `xpeditis_dev` - - User: `xpeditis` - - Port: 5432 - - Persistent volume - - Health checks configured - - Init script with UUID extension and pg_trgm (for fuzzy search) -- **Redis 7**: - - Port: 6379 - - Password protected - - AOF persistence enabled - - Health checks configured - -### ✅ 5. API Documentation (Swagger) -- Swagger UI configured at `/api/docs` -- Bearer authentication setup -- API tags defined (rates, bookings, auth, users, organizations) -- Health check endpoints documented - -### ✅ 6. Monitoring & Logging -- **Logging**: Pino logger with pino-pretty for development -- **Log Levels**: Debug in development, info in production -- **Structured Logging**: JSON format ready for production - -### ✅ 7. Security Foundations -- **Helmet.js**: Security headers configured -- **CORS**: Configured with frontend URL -- **Validation**: Global validation pipe with class-validator -- **JWT**: Configuration ready (access: 15min, refresh: 7 days) -- **Password Hashing**: bcrypt with 12 rounds (configured in env) -- **Rate Limiting**: Environment variables prepared - -### ✅ 8. Testing Infrastructure -- **Backend**: - - Jest configured with TypeScript support - - Unit tests setup with path aliases - - E2E tests with Supertest - - Coverage reports configured -- **Frontend**: - - Jest with jsdom environment - - React Testing Library - - Playwright for E2E tests - -## 📁 Complete Project Structure - -``` -xpeditis/ -├── apps/ -│ ├── backend/ -│ │ ├── src/ -│ │ │ ├── domain/ ✅ Hexagonal core -│ │ │ ├── application/ ✅ Controllers & DTOs -│ │ │ ├── infrastructure/ ✅ External adapters -│ │ │ ├── main.ts ✅ Bootstrap -│ │ │ └── app.module.ts ✅ Root module -│ │ ├── test/ ✅ E2E tests -│ │ ├── package.json ✅ Complete -│ │ ├── tsconfig.json ✅ Path aliases -│ │ ├── nest-cli.json ✅ CLI config -│ │ ├── .eslintrc.js ✅ Linting -│ │ └── .env.example ✅ All variables -│ └── frontend/ -│ ├── package.json ✅ Next.js 14 + deps -│ └── [to be scaffolded] -├── packages/ -│ ├── shared-types/ ✅ Created -│ └── domain/ ✅ Created -├── infra/ -│ └── postgres/ -│ └── init.sql ✅ DB initialization -├── docker-compose.yml ✅ PostgreSQL + Redis -├── package.json ✅ Workspace root -├── .gitignore ✅ Complete -├── .prettierrc ✅ Code formatting -├── README.md ✅ Documentation -├── CLAUDE.md ✅ Architecture guide -├── PRD.md ✅ Product requirements -└── TODO.md ✅ Full roadmap - -``` - -## 🚀 Next Steps - -### To Complete Sprint 0: - -1. **Frontend Configuration Files** (Remaining): - ```bash - cd apps/frontend - # Create: - # - tsconfig.json - # - next.config.js - # - tailwind.config.js - # - postcss.config.js - # - .env.example - # - app/ directory structure - ``` - -2. **CI/CD Pipeline** (Week 2 task): - ```bash - # Create .github/workflows/ - # - ci.yml (lint, test, build) - # - deploy.yml (optional) - ``` - -3. **Install Dependencies**: - ```bash - # Root - npm install - - # Backend - cd apps/backend && npm install - - # Frontend - cd apps/frontend && npm install - ``` - -4. **Start Infrastructure**: - ```bash - docker-compose up -d - ``` - -5. **Verify Setup**: - ```bash - # Backend - cd apps/backend - npm run dev - # Visit: http://localhost:4000/api/docs - - # Frontend - cd apps/frontend - npm run dev - # Visit: http://localhost:3000 - ``` - -## 📊 Sprint 0 Progress: 85% Complete - -### Completed ✅ -- Monorepo structure -- Backend (NestJS + Hexagonal architecture) -- Docker Compose (PostgreSQL + Redis) -- API Documentation (Swagger) -- Monitoring & Logging (Pino) -- Security foundations -- Testing infrastructure -- Frontend package.json - -### Remaining ⏳ -- Frontend configuration files (5%) -- CI/CD pipelines (10%) - -## 🎯 Key Achievements - -1. **Hexagonal Architecture Properly Implemented**: - - Domain layer completely isolated - - Clear separation: Domain → Application → Infrastructure - - Path aliases configured for clean imports - - Ready for domain-driven development - -2. **Production-Ready Configuration**: - - Environment validation with Joi - - Structured logging - - Security best practices - - Health check endpoints - -3. **Developer Experience**: - - TypeScript strict mode - - ESLint + Prettier - - Hot reload for both backend and frontend - - Clear folder structure - - Comprehensive documentation - -4. **Testing Strategy**: - - Unit tests for domain layer - - Integration tests for infrastructure - - E2E tests for complete flows - - Coverage reports - -## 📝 Important Notes - -- **Environment Variables**: Copy `.env.example` to `.env` in both apps before running -- **Database**: PostgreSQL runs on port 5432, credentials in docker-compose.yml -- **Redis**: Runs on port 6379 with password authentication -- **API**: Backend runs on port 4000, frontend on port 3000 -- **Swagger**: Available at http://localhost:4000/api/docs - -## 🔒 Security Checklist for Production - -Before deploying to production: -- [ ] Change all default passwords -- [ ] Generate strong JWT secret -- [ ] Configure OAuth2 credentials -- [ ] Setup email service (SendGrid/SES) -- [ ] Configure AWS S3 credentials -- [ ] Obtain carrier API keys -- [ ] Enable HTTPS/TLS -- [ ] Configure Sentry for error tracking -- [ ] Setup monitoring (Prometheus/Grafana) -- [ ] Enable database backups -- [ ] Review CORS configuration -- [ ] Test rate limiting -- [ ] Run security audit - -## 🎉 Sprint 0 Status: NEARLY COMPLETE - -The foundation is solid and ready for Phase 1 development (Rate Search & Carrier Integration). - -**Estimated time to complete remaining tasks**: 2-4 hours - -**Ready to proceed with**: -- Domain entity modeling -- Rate search implementation -- Carrier connector development diff --git a/SPRINT-0-FINAL.md b/SPRINT-0-FINAL.md deleted file mode 100644 index 0ba73c2..0000000 --- a/SPRINT-0-FINAL.md +++ /dev/null @@ -1,475 +0,0 @@ -# 🎉 Sprint 0 - COMPLETE ✅ - -## Project Setup & Infrastructure - Xpeditis MVP - -**Status**: ✅ **100% COMPLETE** -**Date**: October 7, 2025 -**Duration**: 2 weeks (as planned) - ---- - -## 📊 Summary - -Sprint 0 has been successfully completed with ALL infrastructure and configuration files in place. The Xpeditis maritime freight booking platform is now ready for Phase 1 development. - ---- - -## ✅ Completed Deliverables - -### 1. Monorepo Structure ✅ - -``` -xpeditis/ -├── apps/ -│ ├── backend/ ✅ NestJS + Hexagonal Architecture -│ └── frontend/ ✅ Next.js 14 + TypeScript -├── packages/ -│ ├── shared-types/ ✅ Shared TypeScript types -│ └── domain/ ✅ Shared domain logic -├── infra/ ✅ Infrastructure configs -├── .github/workflows/ ✅ CI/CD pipelines -└── [config files] ✅ All configuration files -``` - -### 2. Backend (NestJS + Hexagonal Architecture) ✅ - -**✅ Complete Implementation**: -- **Hexagonal Architecture** properly implemented - - `domain/` - Pure business logic (NO framework dependencies) - - `application/` - Controllers, DTOs, Mappers - - `infrastructure/` - External adapters (DB, Cache, APIs) -- **Main Files**: - - `main.ts` - Bootstrap with Swagger, security, validation - - `app.module.ts` - Root module with all configurations - - `health.controller.ts` - Health check endpoints -- **Configuration**: - - TypeScript strict mode + path aliases - - Environment validation with Joi - - Pino logger (structured logging) - - Swagger API documentation at `/api/docs` - - Jest testing infrastructure - - E2E testing with Supertest -- **Dependencies** (50+ packages): - - NestJS 10+, TypeORM, PostgreSQL, Redis (ioredis) - - JWT, Passport, bcrypt, helmet - - Swagger/OpenAPI, Pino logger - - Circuit breaker (opossum) - -**Files Created** (15+): -- `package.json`, `tsconfig.json`, `nest-cli.json` -- `.eslintrc.js`, `.env.example` -- `src/main.ts`, `src/app.module.ts` -- `src/application/controllers/health.controller.ts` -- `test/app.e2e-spec.ts`, `test/jest-e2e.json` -- Domain/Application/Infrastructure folder structure - -### 3. Frontend (Next.js 14 + TypeScript) ✅ - -**✅ Complete Implementation**: -- **Next.js 14** with App Router -- **TypeScript** with strict mode -- **Tailwind CSS** + shadcn/ui design system -- **Configuration Files**: - - `tsconfig.json` - Path aliases configured - - `next.config.js` - Next.js configuration - - `tailwind.config.ts` - Complete theme setup - - `postcss.config.js` - PostCSS configuration - - `.eslintrc.json` - ESLint configuration - - `.env.example` - Environment variables -- **App Structure**: - - `app/layout.tsx` - Root layout - - `app/page.tsx` - Home page - - `app/globals.css` - Global styles + CSS variables - - `lib/utils.ts` - Utility functions (cn helper) -- **Dependencies** (30+ packages): - - Next.js 14, React 18, TypeScript 5 - - Radix UI components, Tailwind CSS - - TanStack Query (React Query) - - react-hook-form + zod validation - - axios, lucide-react (icons) - - Jest, React Testing Library, Playwright - -### 4. Docker Infrastructure ✅ - -**✅ docker-compose.yml**: -- **PostgreSQL 15**: - - Container: `xpeditis-postgres` - - Database: `xpeditis_dev` - - User: `xpeditis` - - Port: 5432 - - Health checks enabled - - Persistent volumes - - Init script with extensions (uuid-ossp, pg_trgm) - -- **Redis 7**: - - Container: `xpeditis-redis` - - Port: 6379 - - Password protected - - AOF persistence - - Health checks enabled - - Persistent volumes - -**✅ Database Initialization**: -- `infra/postgres/init.sql` - UUID extension, pg_trgm (fuzzy search) - -### 5. CI/CD Pipelines ✅ - -**✅ GitHub Actions Workflows**: - -#### `.github/workflows/ci.yml`: -- **Lint & Format Check** - - Prettier format check - - ESLint backend - - ESLint frontend - -- **Test Backend** - - PostgreSQL service container - - Redis service container - - Unit tests - - E2E tests - - Coverage upload to Codecov - -- **Test Frontend** - - Unit tests - - Coverage upload to Codecov - -- **Build Backend** - - TypeScript compilation - - Artifact upload - -- **Build Frontend** - - Next.js build - - Artifact upload - -#### `.github/workflows/security.yml`: -- npm audit (weekly) -- Dependency review on PRs - -#### `.github/pull_request_template.md`: -- Structured PR template -- Checklist for hexagonal architecture compliance - -### 6. Configuration Files ✅ - -**✅ Root Level**: -- `package.json` - Workspace configuration -- `.gitignore` - Complete ignore rules -- `.prettierrc` - Code formatting rules -- `.prettierignore` - Files to ignore -- `README.md` - Comprehensive documentation -- `docker-compose.yml` - Infrastructure setup -- `CLAUDE.md` - Architecture guidelines (pre-existing) -- `PRD.md` - Product requirements (pre-existing) -- `TODO.md` - 30-week roadmap (pre-existing) -- `SPRINT-0-COMPLETE.md` - Sprint summary - -### 7. Documentation ✅ - -**✅ Created**: -- `README.md` - Full project documentation - - Quick start guide - - Project structure - - Development commands - - Architecture overview - - Tech stack details - - Security practices -- `SPRINT-0-COMPLETE.md` - This summary -- `SPRINT-0-FINAL.md` - Comprehensive completion report - ---- - -## 🎯 Key Achievements - -### 1. Hexagonal Architecture ✅ -- **Domain Layer**: Completely isolated, no external dependencies -- **Application Layer**: Controllers, DTOs, Mappers -- **Infrastructure Layer**: TypeORM, Redis, Carriers, Email, Storage -- **Path Aliases**: Clean imports (`@domain/*`, `@application/*`, `@infrastructure/*`) -- **Testability**: Domain can be tested without NestJS - -### 2. Production-Ready Configuration ✅ -- **Environment Validation**: Joi schema validation -- **Structured Logging**: Pino with pretty-print in dev -- **Security**: Helmet.js, CORS, rate limiting, JWT -- **Health Checks**: `/health`, `/ready`, `/live` endpoints -- **API Documentation**: Swagger UI at `/api/docs` - -### 3. Developer Experience ✅ -- **TypeScript**: Strict mode everywhere -- **Hot Reload**: Backend and frontend -- **Linting**: ESLint + Prettier -- **Testing**: Jest + Supertest + Playwright -- **CI/CD**: Automated testing and builds -- **Docker**: One-command infrastructure startup - -### 4. Complete Tech Stack ✅ - -**Backend**: -- Framework: NestJS 10+ -- Language: TypeScript 5+ -- Database: PostgreSQL 15 -- Cache: Redis 7 -- ORM: TypeORM -- Auth: JWT + Passport + OAuth2 -- API Docs: Swagger/OpenAPI -- Logging: Pino -- Testing: Jest + Supertest -- Security: Helmet, bcrypt, rate limiting -- Patterns: Circuit breaker (opossum) - -**Frontend**: -- Framework: Next.js 14 (App Router) -- Language: TypeScript 5+ -- Styling: Tailwind CSS + shadcn/ui -- State: TanStack Query -- Forms: react-hook-form + zod -- HTTP: axios -- Icons: lucide-react -- Testing: Jest + React Testing Library + Playwright - -**Infrastructure**: -- PostgreSQL 15 (Docker) -- Redis 7 (Docker) -- CI/CD: GitHub Actions -- Version Control: Git - ---- - -## 📁 File Count - -- **Backend**: 15+ files -- **Frontend**: 12+ files -- **Infrastructure**: 3 files -- **CI/CD**: 3 files -- **Documentation**: 5 files -- **Configuration**: 10+ files - -**Total**: ~50 files created - ---- - -## 🚀 How to Use - -### 1. Install Dependencies - -```bash -# Root (workspaces) -npm install - -# Backend (if needed separately) -cd apps/backend && npm install - -# Frontend (if needed separately) -cd apps/frontend && npm install -``` - -### 2. Start Infrastructure - -```bash -# Start PostgreSQL + Redis -docker-compose up -d - -# Check status -docker-compose ps - -# View logs -docker-compose logs -f -``` - -### 3. Configure Environment - -```bash -# Backend -cp apps/backend/.env.example apps/backend/.env -# Edit apps/backend/.env with your values - -# Frontend -cp apps/frontend/.env.example apps/frontend/.env -# Edit apps/frontend/.env with your values -``` - -### 4. Start Development Servers - -```bash -# Terminal 1 - Backend -npm run backend:dev -# API: http://localhost:4000 -# Docs: http://localhost:4000/api/docs - -# Terminal 2 - Frontend -npm run frontend:dev -# App: http://localhost:3000 -``` - -### 5. Verify Health - -```bash -# Backend health check -curl http://localhost:4000/api/v1/health - -# Expected response: -# { -# "status": "ok", -# "timestamp": "2025-10-07T...", -# "uptime": 12.345, -# "environment": "development", -# "version": "0.1.0" -# } -``` - -### 6. Run Tests - -```bash -# All tests -npm run test:all - -# Backend only -npm run backend:test -npm run backend:test:cov - -# Frontend only -npm run frontend:test - -# E2E tests -npm run backend:test:e2e -``` - -### 7. Lint & Format - -```bash -# Check formatting -npm run format:check - -# Fix formatting -npm run format - -# Lint -npm run lint -``` - ---- - -## 🎯 Success Criteria - ALL MET ✅ - -- ✅ Monorepo structure with workspaces -- ✅ Backend with hexagonal architecture -- ✅ Frontend with Next.js 14 -- ✅ Docker Compose for PostgreSQL + Redis -- ✅ Complete TypeScript configuration -- ✅ ESLint + Prettier setup -- ✅ Testing infrastructure (Jest, Supertest, Playwright) -- ✅ CI/CD pipelines (GitHub Actions) -- ✅ API documentation (Swagger) -- ✅ Logging (Pino) -- ✅ Security foundations (Helmet, JWT, CORS) -- ✅ Environment variable validation -- ✅ Health check endpoints -- ✅ Comprehensive documentation - ---- - -## 📊 Sprint 0 Metrics - -- **Duration**: 2 weeks (as planned) -- **Completion**: 100% -- **Files Created**: ~50 -- **Lines of Code**: ~2,000+ -- **Dependencies**: 80+ packages -- **Documentation Pages**: 5 -- **CI/CD Workflows**: 2 -- **Docker Services**: 2 - ---- - -## 🔐 Security Checklist (Before Production) - -- [ ] Change all default passwords in `.env` -- [ ] Generate strong JWT secret (min 32 chars) -- [ ] Configure OAuth2 credentials (Google, Microsoft) -- [ ] Setup email service (SendGrid/AWS SES) -- [ ] Configure AWS S3 credentials -- [ ] Obtain carrier API keys (Maersk, MSC, CMA CGM, etc.) -- [ ] Enable HTTPS/TLS 1.3 -- [ ] Configure Sentry DSN for error tracking -- [ ] Setup monitoring (Prometheus/Grafana) -- [ ] Enable automated database backups -- [ ] Review and restrict CORS origins -- [ ] Test rate limiting configuration -- [ ] Run OWASP ZAP security scan -- [ ] Enable two-factor authentication (2FA) -- [ ] Setup secrets rotation - ---- - -## 🎯 Next Steps - Phase 1 - -Now ready to proceed with **Phase 1 - Core Search & Carrier Integration** (6-8 weeks): - -### Sprint 1-2: Domain Layer & Port Definitions -- Create domain entities (Organization, User, RateQuote, Carrier, Port, Container) -- Create value objects (Email, PortCode, Money, ContainerType) -- Define API Ports (SearchRatesPort, GetPortsPort) -- Define SPI Ports (Repositories, CarrierConnectorPort, CachePort) -- Implement domain services -- Write domain unit tests (target: 90%+ coverage) - -### Sprint 3-4: Infrastructure Layer -- Design database schema (ERD) -- Create TypeORM entities -- Implement repositories -- Create database migrations -- Seed data (carriers, ports) -- Implement Redis cache adapter -- Create Maersk connector -- Integration tests - -### Sprint 5-6: Application Layer & Rate Search API -- Create DTOs and mappers -- Implement controllers (RatesController, PortsController) -- Complete OpenAPI documentation -- Implement caching strategy -- Performance optimization -- E2E tests - -### Sprint 7-8: Frontend Rate Search UI -- Search form components -- Port autocomplete -- Results display (cards + table) -- Filtering & sorting -- Export functionality -- Responsive design -- Frontend tests - ---- - -## 🏆 Sprint 0 - SUCCESSFULLY COMPLETED - -**All infrastructure and configuration are in place.** -**The foundation is solid and ready for production development.** - -### Team Achievement -- ✅ Hexagonal architecture properly implemented -- ✅ Production-ready configuration -- ✅ Excellent developer experience -- ✅ Comprehensive testing strategy -- ✅ CI/CD automation -- ✅ Complete documentation - -### Ready to Build -- ✅ Domain entities -- ✅ Rate search functionality -- ✅ Carrier integrations -- ✅ Booking workflow -- ✅ User authentication -- ✅ Dashboard - ---- - -**Project Status**: 🟢 READY FOR PHASE 1 -**Sprint 0 Completion**: 100% ✅ -**Time to Phase 1**: NOW 🚀 - ---- - -*Generated on October 7, 2025* -*Xpeditis MVP - Maritime Freight Booking Platform* diff --git a/SPRINT-0-SUMMARY.md b/SPRINT-0-SUMMARY.md deleted file mode 100644 index 103aa0b..0000000 --- a/SPRINT-0-SUMMARY.md +++ /dev/null @@ -1,436 +0,0 @@ -# 📊 Sprint 0 - Executive Summary - -## Xpeditis MVP - Project Setup & Infrastructure - -**Status**: ✅ **COMPLETE** -**Completion Date**: October 7, 2025 -**Duration**: As planned (2 weeks) -**Completion**: 100% - ---- - -## 🎯 Objectives Achieved - -Sprint 0 successfully established a production-ready foundation for the Xpeditis maritime freight booking platform with: - -1. ✅ Complete monorepo structure with npm workspaces -2. ✅ Backend API with hexagonal architecture (NestJS) -3. ✅ Frontend application (Next.js 14) -4. ✅ Database and cache infrastructure (PostgreSQL + Redis) -5. ✅ CI/CD pipelines (GitHub Actions) -6. ✅ Complete documentation suite -7. ✅ Testing infrastructure -8. ✅ Security foundations - ---- - -## 📦 Deliverables - -### Code & Configuration (50+ files) - -| Component | Files | Status | -|-----------|-------|--------| -| **Backend** | 15+ | ✅ Complete | -| **Frontend** | 12+ | ✅ Complete | -| **Infrastructure** | 3 | ✅ Complete | -| **CI/CD** | 3 | ✅ Complete | -| **Documentation** | 8 | ✅ Complete | -| **Configuration** | 10+ | ✅ Complete | - -### Documentation Suite - -1. **README.md** - Project overview and quick start -2. **CLAUDE.md** - Hexagonal architecture guidelines (476 lines) -3. **TODO.md** - 30-week development roadmap (1000+ lines) -4. **SPRINT-0-FINAL.md** - Complete sprint report -5. **SPRINT-0-SUMMARY.md** - This executive summary -6. **QUICK-START.md** - 5-minute setup guide -7. **INSTALLATION-STEPS.md** - Detailed installation -8. **apps/backend/README.md** - Backend documentation -9. **apps/frontend/README.md** - Frontend documentation - ---- - -## 🏗️ Architecture - -### Backend (Hexagonal Architecture) - -**Strict separation of concerns**: - -``` -✅ Domain Layer (Pure Business Logic) - ├── Zero framework dependencies - ├── Testable without NestJS - └── 90%+ code coverage target - -✅ Application Layer (Controllers & DTOs) - ├── REST API endpoints - ├── Input validation - └── DTO mapping - -✅ Infrastructure Layer (External Adapters) - ├── TypeORM repositories - ├── Redis cache - ├── Carrier connectors - ├── Email service - └── S3 storage -``` - -**Key Benefits**: -- Domain can be tested in isolation -- Easy to swap databases or frameworks -- Clear separation of concerns -- Maintainable and scalable - -### Frontend (Next.js 14 + React 18) - -**Modern React stack**: -- App Router with server components -- TypeScript strict mode -- Tailwind CSS + shadcn/ui -- TanStack Query for state -- react-hook-form + zod for forms - ---- - -## 🛠️ Technology Stack - -### Backend -- **Framework**: NestJS 10+ -- **Language**: TypeScript 5+ -- **Database**: PostgreSQL 15 -- **Cache**: Redis 7 -- **ORM**: TypeORM -- **Auth**: JWT + Passport + OAuth2 -- **API Docs**: Swagger/OpenAPI -- **Logging**: Pino (structured JSON) -- **Testing**: Jest + Supertest -- **Security**: Helmet, bcrypt, rate limiting - -### Frontend -- **Framework**: Next.js 14 -- **Language**: TypeScript 5+ -- **Styling**: Tailwind CSS -- **UI**: shadcn/ui (Radix UI) -- **State**: TanStack Query -- **Forms**: react-hook-form + zod -- **HTTP**: axios -- **Testing**: Jest + React Testing Library + Playwright - -### Infrastructure -- **Database**: PostgreSQL 15 (Docker) -- **Cache**: Redis 7 (Docker) -- **CI/CD**: GitHub Actions -- **Container**: Docker + Docker Compose - ---- - -## 📊 Metrics - -| Metric | Value | -|--------|-------| -| **Files Created** | ~50 | -| **Lines of Code** | 2,000+ | -| **Dependencies** | 80+ packages | -| **Documentation** | 8 files, 3000+ lines | -| **CI/CD Workflows** | 2 (ci.yml, security.yml) | -| **Docker Services** | 2 (PostgreSQL, Redis) | -| **Test Coverage Target** | Domain: 90%, App: 80%, Infra: 70% | - ---- - -## ✅ Success Criteria - All Met - -| Criteria | Status | Notes | -|----------|--------|-------| -| Monorepo structure | ✅ | npm workspaces configured | -| Backend hexagonal arch | ✅ | Complete separation of layers | -| Frontend Next.js 14 | ✅ | App Router + TypeScript | -| Docker infrastructure | ✅ | PostgreSQL + Redis with health checks | -| TypeScript strict mode | ✅ | All projects | -| Testing infrastructure | ✅ | Jest, Supertest, Playwright | -| CI/CD pipelines | ✅ | GitHub Actions (lint, test, build) | -| API documentation | ✅ | Swagger at /api/docs | -| Logging | ✅ | Pino structured logging | -| Security foundations | ✅ | Helmet, JWT, CORS, rate limiting | -| Environment validation | ✅ | Joi schema validation | -| Health endpoints | ✅ | /health, /ready, /live | -| Documentation | ✅ | 8 comprehensive documents | - ---- - -## 🎯 Key Features Implemented - -### Backend Features - -1. **Health Check System** - - `/health` - Overall system health - - `/ready` - Readiness for traffic - - `/live` - Liveness check - -2. **Logging System** - - Structured JSON logs (Pino) - - Pretty print in development - - Request/response logging - - Log levels (debug, info, warn, error) - -3. **Configuration Management** - - Environment variable validation - - Type-safe configuration - - Multiple environments support - -4. **Security** - - Helmet.js security headers - - CORS configuration - - Rate limiting prepared - - JWT authentication ready - - Password hashing (bcrypt) - -5. **API Documentation** - - Swagger UI at `/api/docs` - - OpenAPI specification - - Request/response schemas - - Authentication documentation - -### Frontend Features - -1. **Modern React Setup** - - Next.js 14 App Router - - Server and client components - - TypeScript strict mode - - Path aliases configured - -2. **UI Framework** - - Tailwind CSS with custom theme - - shadcn/ui components ready - - Dark mode support (CSS variables) - - Responsive design utilities - -3. **State Management** - - TanStack Query for server state - - React hooks for local state - - Form state with react-hook-form - -4. **Utilities** - - `cn()` helper for className merging - - Type-safe API client ready - - Zod schemas for validation - ---- - -## 🚀 Ready for Phase 1 - -The project is **fully ready** for Phase 1 development: - -### Phase 1 - Core Search & Carrier Integration (6-8 weeks) - -**Sprint 1-2: Domain Layer** -- ✅ Folder structure ready -- ✅ Path aliases configured -- ✅ Testing infrastructure ready -- 🎯 Ready to create: Entities, Value Objects, Ports, Services - -**Sprint 3-4: Infrastructure** -- ✅ Database configured (PostgreSQL) -- ✅ Cache configured (Redis) -- ✅ TypeORM setup -- 🎯 Ready to create: Repositories, Migrations, Seed data - -**Sprint 5-6: Application Layer** -- ✅ NestJS configured -- ✅ Swagger ready -- ✅ Validation pipes configured -- 🎯 Ready to create: Controllers, DTOs, Mappers - -**Sprint 7-8: Frontend UI** -- ✅ Next.js configured -- ✅ Tailwind CSS ready -- ✅ shadcn/ui ready -- 🎯 Ready to create: Search components, Results display - ---- - -## 📁 Project Structure - -``` -xpeditis/ -├── apps/ -│ ├── backend/ ✅ NestJS + Hexagonal -│ │ ├── src/ -│ │ │ ├── domain/ ✅ Pure business logic -│ │ │ ├── application/ ✅ Controllers & DTOs -│ │ │ ├── infrastructure/ ✅ External adapters -│ │ │ ├── main.ts ✅ Bootstrap -│ │ │ └── app.module.ts ✅ Root module -│ │ ├── test/ ✅ E2E tests -│ │ └── [config files] ✅ All complete -│ │ -│ └── frontend/ ✅ Next.js 14 -│ ├── app/ ✅ App Router -│ ├── components/ ✅ Ready for components -│ ├── lib/ ✅ Utilities -│ └── [config files] ✅ All complete -│ -├── packages/ -│ ├── shared-types/ ✅ Created -│ └── domain/ ✅ Created -│ -├── infra/ -│ └── postgres/ ✅ Init scripts -│ -├── .github/ -│ └── workflows/ ✅ CI/CD pipelines -│ -├── docker-compose.yml ✅ PostgreSQL + Redis -├── package.json ✅ Workspace root -├── [documentation] ✅ 8 files -└── [config files] ✅ Complete -``` - ---- - -## 💻 Development Workflow - -### Quick Start (5 minutes) - -```bash -# 1. Install dependencies -npm install - -# 2. Start infrastructure -docker-compose up -d - -# 3. Configure environment -cp apps/backend/.env.example apps/backend/.env -cp apps/frontend/.env.example apps/frontend/.env - -# 4. Start backend -npm run backend:dev - -# 5. Start frontend (in another terminal) -npm run frontend:dev -``` - -### Verification - -- ✅ Backend: http://localhost:4000/api/v1/health -- ✅ API Docs: http://localhost:4000/api/docs -- ✅ Frontend: http://localhost:3000 -- ✅ PostgreSQL: localhost:5432 -- ✅ Redis: localhost:6379 - ---- - -## 🎓 Learning Resources - -For team members new to the stack: - -**Hexagonal Architecture**: -- Read [CLAUDE.md](CLAUDE.md) (comprehensive guide) -- Review backend folder structure -- Study the flow: HTTP → Controller → Use Case → Domain - -**NestJS**: -- [Official Docs](https://docs.nestjs.com/) -- Focus on: Modules, Controllers, Providers, DTOs - -**Next.js 14**: -- [Official Docs](https://nextjs.org/docs) -- Focus on: App Router, Server Components, Client Components - -**TypeORM**: -- [Official Docs](https://typeorm.io/) -- Focus on: Entities, Repositories, Migrations - ---- - -## 🔒 Security Considerations - -**Implemented**: -- ✅ Helmet.js security headers -- ✅ CORS configuration -- ✅ Input validation (class-validator) -- ✅ Environment variable validation -- ✅ Password hashing configuration -- ✅ JWT configuration -- ✅ Rate limiting preparation - -**For Production** (before deployment): -- [ ] Change all default passwords -- [ ] Generate strong JWT secret -- [ ] Configure OAuth2 credentials -- [ ] Setup email service -- [ ] Configure AWS S3 -- [ ] Obtain carrier API keys -- [ ] Enable HTTPS/TLS -- [ ] Setup Sentry -- [ ] Configure monitoring -- [ ] Enable database backups -- [ ] Run security audit - ---- - -## 📈 Next Steps - -### Immediate (This Week) - -1. ✅ Sprint 0 complete -2. 🎯 Install dependencies (`npm install`) -3. 🎯 Start infrastructure (`docker-compose up -d`) -4. 🎯 Verify all services running -5. 🎯 Begin Sprint 1 (Domain entities) - -### Short Term (Next 2 Weeks - Sprint 1-2) - -1. Create domain entities (Organization, User, RateQuote, Carrier, Port) -2. Create value objects (Email, PortCode, Money, ContainerType) -3. Define API ports (SearchRatesPort, GetPortsPort) -4. Define SPI ports (Repositories, CarrierConnectorPort, CachePort) -5. Implement domain services -6. Write domain unit tests (90%+ coverage) - -### Medium Term (Weeks 3-8 - Sprint 3-6) - -1. Design and implement database schema -2. Create TypeORM entities and repositories -3. Implement Redis cache adapter -4. Create Maersk carrier connector -5. Implement rate search API -6. Build frontend search UI - ---- - -## 🎉 Conclusion - -Sprint 0 has been **successfully completed** with: - -- ✅ **100% of planned deliverables** -- ✅ **Production-ready infrastructure** -- ✅ **Hexagonal architecture properly implemented** -- ✅ **Complete documentation suite** -- ✅ **Automated CI/CD pipelines** -- ✅ **Developer-friendly setup** - -**The Xpeditis MVP project is ready for Phase 1 development.** - ---- - -## 📞 Support - -For questions or issues: - -1. Check documentation (8 comprehensive guides) -2. Review [QUICK-START.md](QUICK-START.md) -3. Consult [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) -4. Open a GitHub issue - ---- - -**Status**: 🟢 **READY FOR DEVELOPMENT** -**Next Phase**: Phase 1 - Core Search & Carrier Integration -**Team**: ✅ **Ready to build** - ---- - -*Xpeditis MVP - Maritime Freight Booking Platform* -*Sprint 0 Complete - October 7, 2025* diff --git a/START-HERE.md b/START-HERE.md deleted file mode 100644 index 625a564..0000000 --- a/START-HERE.md +++ /dev/null @@ -1,358 +0,0 @@ -# 🚀 START HERE - Xpeditis MVP - -## ✅ Sprint 0 Complete! - -Tout le code et la configuration sont prêts. Suivez ces étapes pour démarrer. - ---- - -## 📋 Étape par Étape (10 minutes) - -### 1️⃣ Installer les Dépendances (5 min) - -⚠️ **IMPORTANT pour Windows** : Les workspaces npm ne fonctionnent pas bien sur Windows. -Utilisez cette commande pour installer dans chaque app séparément : - -```bash -# Option A: Script automatique -npm run install:all - -# Option B: Manuel (recommandé si Option A échoue) -# 1. Racine -npm install - -# 2. Backend -cd apps/backend -npm install -cd ../.. - -# 3. Frontend -cd apps/frontend -npm install -cd ../.. -``` - -**Durée**: 3-5 minutes -**Packages**: ~80 packages au total - -### 2️⃣ Démarrer Docker (1 min) - -```bash -docker-compose up -d -``` - -**Vérifier** : -```bash -docker-compose ps -# Doit afficher postgres et redis "Up (healthy)" -``` - -### 3️⃣ Configurer l'Environnement (30 sec) - -```bash -# Backend -cp apps/backend/.env.example apps/backend/.env - -# Frontend -cp apps/frontend/.env.example apps/frontend/.env -``` - -✅ **Les valeurs par défaut fonctionnent** - pas besoin de modifier ! - -### 4️⃣ Démarrer le Backend (1 min) - -```bash -# Option A: Depuis la racine -npm run backend:dev - -# Option B: Depuis apps/backend -cd apps/backend -npm run dev -``` - -**Attendu** : -``` -╔═══════════════════════════════════════╗ -║ 🚢 Xpeditis API Server Running ║ -║ API: http://localhost:4000/api/v1 ║ -║ Docs: http://localhost:4000/api/docs ║ -╚═══════════════════════════════════════╝ -``` - -**Vérifier** : http://localhost:4000/api/v1/health - -### 5️⃣ Démarrer le Frontend (1 min) - Nouveau Terminal - -```bash -# Option A: Depuis la racine -npm run frontend:dev - -# Option B: Depuis apps/frontend -cd apps/frontend -npm run dev -``` - -**Attendu** : -``` -▲ Next.js 14.0.4 -- Local: http://localhost:3000 -✓ Ready in 2.3s -``` - -**Vérifier** : http://localhost:3000 - ---- - -## ✅ Checklist de Vérification - -Avant de continuer, vérifiez que tout fonctionne : - -- [ ] Backend démarre sans erreur -- [ ] Frontend démarre sans erreur -- [ ] http://localhost:4000/api/v1/health renvoie `{"status":"ok"}` -- [ ] http://localhost:4000/api/docs affiche Swagger UI -- [ ] http://localhost:3000 affiche la page Xpeditis -- [ ] `docker-compose ps` montre postgres et redis "healthy" - -**Tout est vert ? Excellent ! 🎉** - ---- - -## 📚 Prochaines Étapes - -### Lire la Documentation (2 heures) - -**Obligatoire** (dans cet ordre) : - -1. **[QUICK-START.md](QUICK-START.md)** (10 min) - - Référence rapide des commandes - -2. **[CLAUDE.md](CLAUDE.md)** (60 min) 🔥 **TRÈS IMPORTANT** - - **Architecture hexagonale complète** - - Règles pour chaque couche - - Exemples de code - - **À LIRE ABSOLUMENT avant de coder** - -3. **[NEXT-STEPS.md](NEXT-STEPS.md)** (30 min) - - Quoi faire ensuite - - Exemples de code pour démarrer - - Phase 1 expliquée - -4. **[TODO.md](TODO.md)** - Section Sprint 1-2 (30 min) - - Tâches détaillées - - Critères d'acceptation - -### Commencer le Développement - -**Sprint 1-2 : Domain Layer** (2 semaines) - -Créer les fichiers dans `apps/backend/src/domain/` : - -**Entités** (`entities/`) : -- `organization.entity.ts` -- `user.entity.ts` -- `rate-quote.entity.ts` -- `carrier.entity.ts` -- `port.entity.ts` -- `container.entity.ts` -- `booking.entity.ts` - -**Value Objects** (`value-objects/`) : -- `email.vo.ts` -- `port-code.vo.ts` -- `money.vo.ts` -- `container-type.vo.ts` -- `booking-number.vo.ts` - -**Ports** : -- `ports/in/` - API ports (SearchRatesPort, CreateBookingPort, etc.) -- `ports/out/` - SPI ports (Repositories, CarrierConnectorPort, CachePort, etc.) - -**Services** (`services/`) : -- `rate-search.service.ts` -- `booking.service.ts` -- `user.service.ts` - -**Tests** : -- `*.spec.ts` pour chaque service -- **Cible : 90%+ de couverture** - -Voir [NEXT-STEPS.md](NEXT-STEPS.md) pour des exemples de code complets ! - ---- - -## 🛠️ Commandes Utiles - -### Développement - -```bash -# Backend -npm run backend:dev # Démarrer -npm run backend:test # Tests -npm run backend:lint # Linter - -# Frontend -npm run frontend:dev # Démarrer -npm run frontend:test # Tests -npm run frontend:lint # Linter - -# Les deux -npm run format # Formater le code -npm run format:check # Vérifier le formatage -``` - -### Docker - -```bash -docker-compose up -d # Démarrer -docker-compose down # Arrêter -docker-compose logs -f # Voir les logs -docker-compose ps # Status -``` - -### Base de données - -```bash -# Se connecter à PostgreSQL -docker-compose exec postgres psql -U xpeditis -d xpeditis_dev - -# Se connecter à Redis -docker-compose exec redis redis-cli -a xpeditis_redis_password -``` - ---- - -## 🐛 Problèmes Courants - -### npm install échoue - -**Solution** : Voir [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md) - -### Backend ne démarre pas - -```bash -cd apps/backend -rm -rf node_modules package-lock.json -npm install -npm run dev -``` - -### Frontend ne démarre pas - -```bash -cd apps/frontend -rm -rf node_modules package-lock.json -npm install -npm run dev -``` - -### Docker ne démarre pas - -```bash -# Vérifier que Docker Desktop est lancé -docker --version - -# Redémarrer les containers -docker-compose down -docker-compose up -d -``` - -### Port déjà utilisé - -```bash -# Trouver le processus sur le port 4000 -netstat -ano | findstr :4000 - -# Ou changer le port dans apps/backend/.env -PORT=4001 -``` - ---- - -## 📖 Documentation Complète - -Tous les fichiers de documentation : - -### Getting Started -- **[START-HERE.md](START-HERE.md)** ⭐ - Ce fichier -- [QUICK-START.md](QUICK-START.md) - Guide rapide -- [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - Installation détaillée -- [WINDOWS-INSTALLATION.md](WINDOWS-INSTALLATION.md) - Spécifique Windows -- [NEXT-STEPS.md](NEXT-STEPS.md) - Quoi faire ensuite - -### Architecture -- **[CLAUDE.md](CLAUDE.md)** 🔥 - **À LIRE ABSOLUMENT** -- [apps/backend/README.md](apps/backend/README.md) - Backend -- [apps/frontend/README.md](apps/frontend/README.md) - Frontend - -### Project Planning -- [PRD.md](PRD.md) - Exigences produit -- [TODO.md](TODO.md) - Roadmap 30 semaines -- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Rapport Sprint 0 -- [SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md) - Résumé -- [INDEX.md](INDEX.md) - Index complet - ---- - -## 🎯 Objectifs Phase 1 (6-8 semaines) - -**Sprint 1-2** : Domain Layer -- Créer toutes les entités métier -- Définir tous les ports (API & SPI) -- Implémenter les services métier -- Tests unitaires (90%+) - -**Sprint 3-4** : Infrastructure Layer -- Schéma de base de données -- Repositories TypeORM -- Adapter Redis cache -- Connecteur Maersk - -**Sprint 5-6** : Application Layer -- API rate search -- Controllers & DTOs -- Documentation OpenAPI -- Tests E2E - -**Sprint 7-8** : Frontend UI -- Interface de recherche -- Affichage des résultats -- Filtres et tri -- Tests frontend - ---- - -## 💡 Conseils Importants - -### ⚠️ À LIRE ABSOLUMENT - -**[CLAUDE.md](CLAUDE.md)** - Contient toutes les règles d'architecture : -- Comment organiser le code -- Quoi mettre dans chaque couche -- Ce qu'il faut éviter -- Exemples complets - -**Sans lire CLAUDE.md, vous risquez de violer l'architecture hexagonale !** - -### ✅ Bonnes Pratiques - -- **Tests first** : Écrire les tests avant le code -- **Commits fréquents** : Petits commits, souvent -- **Lire les specs** : Vérifier TODO.md pour les critères d'acceptation -- **Suivre l'archi** : Respecter Domain → Application → Infrastructure - ---- - -## 🎉 Vous êtes Prêt ! - -**Sprint 0** : ✅ Complete -**Installation** : ✅ Fonctionnelle -**Documentation** : ✅ Disponible -**Prochaine étape** : Lire CLAUDE.md et commencer Sprint 1 - -**Bon développement ! 🚀** - ---- - -*Xpeditis MVP - Maritime Freight Booking Platform* -*Démarrez ici pour le développement Phase 1* diff --git a/WINDOWS-INSTALLATION.md b/WINDOWS-INSTALLATION.md deleted file mode 100644 index 6053cce..0000000 --- a/WINDOWS-INSTALLATION.md +++ /dev/null @@ -1,406 +0,0 @@ -# 🪟 Installation sur Windows - Xpeditis - -## Problème avec npm Workspaces sur Windows - -Sur Windows, les workspaces npm peuvent rencontrer des problèmes de symlinks (`EISDIR` error). Voici la solution. - ---- - -## ✅ Solution : Installation Séparée par App - -Au lieu d'utiliser `npm install` à la racine, installez les dépendances dans chaque app séparément. - -### Étape 1 : Supprimer le node_modules racine (si existe) - -```bash -# Si node_modules existe à la racine -rm -rf node_modules -``` - -### Étape 2 : Installer les dépendances Backend - -```bash -cd apps/backend -npm install -cd ../.. -``` - -**Durée** : 2-3 minutes -**Packages installés** : ~50 packages NestJS, TypeORM, etc. - -### Étape 3 : Installer les dépendances Frontend - -```bash -cd apps/frontend -npm install -cd ../.. -``` - -**Durée** : 2-3 minutes -**Packages installés** : ~30 packages Next.js, React, Tailwind, etc. - -### Étape 4 : Installer les dépendances racine (optionnel) - -```bash -npm install --no-workspaces -``` - -**Packages installés** : prettier, typescript (partagés) - ---- - -## ✅ Vérification de l'Installation - -### Vérifier Backend - -```bash -cd apps/backend - -# Vérifier que node_modules existe -ls node_modules - -# Vérifier des packages clés -ls node_modules/@nestjs -ls node_modules/typeorm -ls node_modules/pg - -# Essayer de démarrer -npm run dev -``` - -**Attendu** : Le serveur démarre sur le port 4000 - -### Vérifier Frontend - -```bash -cd apps/frontend - -# Vérifier que node_modules existe -ls node_modules - -# Vérifier des packages clés -ls node_modules/next -ls node_modules/react -ls node_modules/tailwindcss - -# Essayer de démarrer -npm run dev -``` - -**Attendu** : Le serveur démarre sur le port 3000 - ---- - -## 🚀 Démarrage Après Installation - -### 1. Démarrer l'infrastructure Docker - -```bash -docker-compose up -d -``` - -### 2. Configurer l'environnement - -```bash -# Backend -cp apps/backend/.env.example apps/backend/.env - -# Frontend -cp apps/frontend/.env.example apps/frontend/.env -``` - -### 3. Démarrer le Backend - -```bash -cd apps/backend -npm run dev -``` - -**URL** : http://localhost:4000/api/v1/health - -### 4. Démarrer le Frontend (nouveau terminal) - -```bash -cd apps/frontend -npm run dev -``` - -**URL** : http://localhost:3000 - ---- - -## 📝 Scripts Modifiés pour Windows - -Comme les workspaces ne fonctionnent pas, utilisez ces commandes : - -### Backend - -```bash -# Au lieu de: npm run backend:dev -cd apps/backend && npm run dev - -# Au lieu de: npm run backend:test -cd apps/backend && npm test - -# Au lieu de: npm run backend:build -cd apps/backend && npm run build -``` - -### Frontend - -```bash -# Au lieu de: npm run frontend:dev -cd apps/frontend && npm run dev - -# Au lieu de: npm run frontend:test -cd apps/frontend && npm test - -# Au lieu de: npm run frontend:build -cd apps/frontend && npm run build -``` - -### Les deux en parallèle - -**Option 1** : Deux terminaux - -Terminal 1 : -```bash -cd apps/backend -npm run dev -``` - -Terminal 2 : -```bash -cd apps/frontend -npm run dev -``` - -**Option 2** : PowerShell avec Start-Process - -```powershell -# Backend -Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd apps/backend; npm run dev" - -# Frontend -Start-Process powershell -ArgumentList "-NoExit", "-Command", "cd apps/frontend; npm run dev" -``` - ---- - -## 🔧 Alternative : Utiliser pnpm ou yarn - -Si npm continue à poser problème, utilisez pnpm (meilleur support Windows) : - -### Avec pnpm - -```bash -# Installer pnpm globalement -npm install -g pnpm - -# Installer les dépendances -pnpm install - -# Démarrer backend -pnpm --filter backend dev - -# Démarrer frontend -pnpm --filter frontend dev -``` - -### Avec yarn - -```bash -# Installer yarn globalement -npm install -g yarn - -# Installer les dépendances -yarn install - -# Démarrer backend -yarn workspace backend dev - -# Démarrer frontend -yarn workspace frontend dev -``` - ---- - -## ✅ Checklist d'Installation Windows - -- [ ] Docker Desktop installé et démarré -- [ ] Node.js v20+ installé -- [ ] `cd apps/backend && npm install` terminé -- [ ] `cd apps/frontend && npm install` terminé -- [ ] `docker-compose up -d` exécuté -- [ ] Containers PostgreSQL et Redis en cours d'exécution -- [ ] `.env` files copiés -- [ ] Backend démarre sur port 4000 -- [ ] Frontend démarre sur port 3000 -- [ ] Health endpoint répond : http://localhost:4000/api/v1/health - ---- - -## 🐛 Dépannage Windows - -### Erreur : EBUSY (resource busy or locked) - -**Cause** : Fichiers verrouillés par un processus Windows (antivirus, Windows Defender, etc.) - -**Solutions** : -1. Fermer VSCode et tous les terminals -2. Désactiver temporairement l'antivirus -3. Exclure le dossier `node_modules` de Windows Defender -4. Réessayer l'installation - -### Erreur : EISDIR (illegal operation on directory) - -**Cause** : Windows ne supporte pas bien les symlinks npm workspaces - -**Solution** : Utiliser l'installation séparée (cette page) - -### Erreur : EPERM (operation not permitted) - -**Cause** : Permissions insuffisantes - -**Solutions** : -1. Exécuter PowerShell/CMD en tant qu'administrateur -2. Ou utiliser l'installation séparée (pas besoin d'admin) - -### Backend ne démarre pas - "Cannot find module" - -**Cause** : node_modules manquant ou incomplet - -**Solution** : -```bash -cd apps/backend -rm -rf node_modules package-lock.json -npm install -``` - -### Frontend ne démarre pas - "Cannot find module 'next'" - -**Cause** : node_modules manquant ou incomplet - -**Solution** : -```bash -cd apps/frontend -rm -rf node_modules package-lock.json -npm install -``` - -### Frontend build fail - "EISDIR: illegal operation on directory, readlink" - -**Cause** : Next.js rencontre un problème avec les symlinks sur Windows lors du build - -**Erreur complète** : -``` -Error: EISDIR: illegal operation on a directory, readlink 'D:\xpeditis2.0\apps\frontend\node_modules\next\dist\pages\_app.js' -``` - -**Solutions** : - -**Option 1** : Utiliser le mode développement (recommandé pour le développement) -```bash -cd apps/frontend -npm run dev # Fonctionne sans problème -``` - -**Option 2** : Utiliser WSL2 pour le build de production -```bash -# Dans WSL2 -cd /mnt/d/xpeditis2.0/apps/frontend -npm run build # Fonctionne correctement -``` - -**Option 3** : Build depuis PowerShell avec mode développeur activé -```powershell -# Activer le mode développeur Windows (une seule fois) -# Paramètres > Mise à jour et sécurité > Pour les développeurs > Mode développeur - -# Ensuite: -cd apps/frontend -npm run build -``` - -**Note** : Pour le développement quotidien, utilisez `npm run dev` qui n'a pas ce problème. Le build de production n'est nécessaire que pour le déploiement. - ---- - -## 💡 Recommandations pour Windows - -### 1. Utiliser PowerShell Core (v7+) - -Plus moderne et meilleur support des outils Node.js : -- [Télécharger PowerShell](https://github.com/PowerShell/PowerShell) - -### 2. Utiliser Windows Terminal - -Meilleure expérience terminal : -- [Télécharger Windows Terminal](https://aka.ms/terminal) - -### 3. Considérer WSL2 (Windows Subsystem for Linux) - -Pour une expérience Linux native sur Windows : - -```bash -# Installer WSL2 -wsl --install - -# Installer Ubuntu -wsl --install -d Ubuntu - -# Utiliser WSL2 pour le développement -cd /mnt/d/xpeditis2.0 -npm install # Fonctionne comme sur Linux -``` - -### 4. Exclure node_modules de l'antivirus - -Pour améliorer les performances : - -**Windows Defender** : -1. Paramètres Windows > Mise à jour et sécurité > Sécurité Windows -2. Protection contre les virus et menaces > Gérer les paramètres -3. Exclusions > Ajouter une exclusion > Dossier -4. Ajouter : `D:\xpeditis2.0\node_modules` -5. Ajouter : `D:\xpeditis2.0\apps\backend\node_modules` -6. Ajouter : `D:\xpeditis2.0\apps\frontend\node_modules` - ---- - -## ✅ Installation Réussie ! - -Une fois les dépendances installées dans chaque app : - -```bash -# Backend -cd apps/backend -npm run dev -# Visiter: http://localhost:4000/api/docs - -# Frontend (nouveau terminal) -cd apps/frontend -npm run dev -# Visiter: http://localhost:3000 -``` - -**Tout fonctionne ? Excellent ! 🎉** - -Passez à [NEXT-STEPS.md](NEXT-STEPS.md) pour commencer le développement. - ---- - -## 📞 Besoin d'Aide ? - -Si les problèmes persistent : - -1. Vérifier Node.js version : `node --version` (doit être v20+) -2. Vérifier npm version : `npm --version` (doit être v10+) -3. Essayer avec pnpm : `npm install -g pnpm && pnpm install` -4. Utiliser WSL2 pour une expérience Linux -5. Consulter [INSTALLATION-STEPS.md](INSTALLATION-STEPS.md) - ---- - -*Xpeditis - Installation Windows* -*Solution pour npm workspaces sur Windows*