| README.md | ||
██╗ ██╗██████╗ ███████╗██████╗ ██╗████████╗██╗███████╗
╚██╗██╔╝██╔══██╗██╔════╝██╔══██╗██║╚══██╔══╝██║██╔════╝
╚███╔╝ ██████╔╝█████╗ ██║ ██║██║ ██║ ██║███████╗
██╔██╗ ██╔═══╝ ██╔══╝ ██║ ██║██║ ██║ ██║╚════██║
██╔╝ ██╗██║ ███████╗██████╔╝██║ ██║ ██║███████║
╚═╝ ╚═╝╚═╝ ╚══════╝╚═════╝ ╚═╝ ╚═╝ ╚═╝╚══════╝
"Navigating the Digital Ocean with Maritime Excellence"
Xpeditis - Plateforme SaaS de Transport International
Plateforme B2B/B2C spécialisée dans le transport maritime et routier international
Vue d'ensemble
Xpeditis est une plateforme SaaS moderne inspirée de searates.com, offrant des services complets de transport international avec devis instantanés, suivi en temps réel, et gestion documentaire automatisée.
Domaines
- Principal : xpeditis.fr
- API : api.xpeditis.fr
- Staging : staging.xpeditis.fr
Architecture
Structure Multi-Repository
xpeditis/
├── backend/ # API Spring Boot (Java 17)
├── frontend/ # Interface React TypeScript
├── mobile/ # Application mobile (React Native)
├── docs/ # Documentation technique
├── infrastructure/ # Configuration DevOps
└── shared/ # Ressources partagées
Stack Technique
Backend
- Framework : Spring Boot 3.2+
- Langage : Java 23
- Architecture : Hexagonale (Ports & Adapters)
- Base de données : PostgreSQL 15
- Sécurité : Spring Security + JWT
- Documentation : OpenAPI 3 (Swagger)
- Build : Maven
Frontend
- Framework : React 18 + TypeScript
- Build : Vite
- Styling : TailwindCSS + shadcn/ui
- State Management : React Query
- Routing : React Router
- Package Manager : pnpm
DevOps
- Conteneurisation : Docker + Docker Compose
- Orchestration : Kubernetes + Helm
- CI/CD : GitHub Actions
- Monitoring : Prometheus + Grafana
- Logs : ELK Stack
Fonctionnalités Principales
Implémentées
-
Devis Instantané Multi-Offres
- Génération automatique (Express, Standard, Éco)
- Calcul basé sur grilles tarifaires
- Validation et acceptation en ligne
- API REST complète avec endpoints CRUD
-
Interface Utilisateur Complète
- Landing page responsive avec statistiques
- Formulaire de devis interactif avec validation
- Dashboard avec métriques en temps réel
- Pages de réservation et suivi d'expéditions
- Planning des navires avec filtres
- Composants UI modernes (shadcn/ui)
-
API REST Sécurisée
- Authentification JWT avec intercepteurs
- Documentation OpenAPI/Swagger
- Gestion CORS multi-environnements
- Architecture hexagonale complète
- Mapping automatique avec MapStruct
-
Infrastructure DevOps Complète
- Docker multi-stage builds optimisés
- Kubernetes avec auto-scaling (HPA)
- CI/CD automatisé avec GitHub Actions
- Certificats SSL automatiques (cert-manager)
- Scripts de déploiement intelligents
- Monitoring et health checks
En Développement
- Track & Trace temps réel avec WebSocket
- Dossier d'export automatisé
- Facturation PDF avec génération automatique
- Centre d'aide avec recherche
- Notifications push
Installation et Démarrage
Prérequis
- Docker & Docker Compose
- Node.js 18+ & pnpm
- Java 17+ & Maven
- kubectl (pour la production)
Démarrage Rapide
# Cloner le repository
git clone https://github.com/your-username/xpeditis.git
cd xpeditis
# Démarrage avec Docker Compose (recommandé)
./scripts/deploy.sh dev all
# Ou démarrage manuel
# Backend
cd backend
mvn spring-boot:run
# Frontend (nouveau terminal)
cd frontend
pnpm install
pnpm dev
Accès aux Services
- Frontend : http://localhost:3000
- Backend API : http://localhost:8080/api
- Swagger UI : http://localhost:8080/swagger-ui.html
- Base de données : localhost:5432
- Actuator : http://localhost:8080/api/actuator
Structure du Projet
Backend (Architecture Hexagonale)
backend/src/main/java/com/xpeditis/
├── application/ # Controllers REST & DTOs
│ ├── controller/ # Contrôleurs REST
│ └── dto/ # Data Transfer Objects
├── bootstrap/ # Configuration & Main class
├── common/ # Exceptions & Utilities
├── domain/ # Modèles métier & Services
│ ├── model/ # Entités métier (Quote, Shipment)
│ └── service/ # Services métier
├── infrastructure/ # Repositories & Adaptateurs
│ ├── persistence/ # JPA Entities & Repositories
│ └── config/ # Configuration Spring
└── logs/ # Logging & Audit
Frontend (React TypeScript)
frontend/src/
├── components/ # Composants réutilisables
│ ├── ui/ # Composants de base (shadcn/ui)
│ ├── layout/ # Layout & Navigation
│ └── quote/ # Composants spécifiques devis
├── pages/ # Pages de l'application
│ ├── HomePage.tsx # Page d'accueil
│ ├── QuotePage.tsx # Formulaire de devis
│ ├── DashboardPage.tsx # Tableau de bord
│ └── TrackingPage.tsx # Suivi d'expéditions
├── lib/ # Utilitaires & API client
├── hooks/ # Hooks React personnalisés
└── types/ # Types TypeScript
Configuration
Variables d'Environnement
Backend (application.yml)
spring:
profiles:
active: ${SPRING_PROFILES_ACTIVE:dev}
datasource:
url: ${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/xpeditis_dev}
username: ${SPRING_DATASOURCE_USERNAME:xpeditis_user}
password: ${SPRING_DATASOURCE_PASSWORD:xpeditis_password}
jpa:
hibernate:
ddl-auto: ${SPRING_JPA_HIBERNATE_DDL_AUTO:update}
show-sql: ${SPRING_JPA_SHOW_SQL:false}
jwt:
secret: ${JWT_SECRET:dev-secret-key}
expiration: ${JWT_EXPIRATION:86400}
cors:
allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3000}
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
Frontend (.env)
VITE_API_URL=http://localhost:8080/api
VITE_APP_NAME=Xpeditis
VITE_APP_VERSION=1.0.0
Déploiement
Script de Déploiement Intelligent
# Développement complet
./scripts/deploy.sh dev all
# Staging avec build automatique
./scripts/deploy.sh staging all
# Production avec confirmation
./scripts/deploy.sh prod all
# Composant spécifique
./scripts/deploy.sh dev backend
./scripts/deploy.sh prod frontend
# Rollback automatique
./scripts/deploy.sh --rollback
# Aide détaillée
./scripts/deploy.sh --help
Kubernetes Production
# Déploiement complet avec secrets
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/postgres.yaml
kubectl apply -f k8s/backend.yaml
kubectl apply -f k8s/frontend.yaml
kubectl apply -f k8s/ingress.yaml
# Vérification du déploiement
kubectl get pods -n xpeditis
kubectl get services -n xpeditis
kubectl get ingress -n xpeditis
# Monitoring des logs
kubectl logs -f deployment/backend -n xpeditis
Tests
Backend
cd backend
mvn test # Tests unitaires
mvn verify # Tests d'intégration
mvn jacoco:report # Couverture de code
mvn spring-boot:run -Dspring.profiles.active=test
Frontend
cd frontend
pnpm test # Tests unitaires
pnpm test:coverage # Couverture de code
pnpm lint # Linting ESLint
pnpm type-check # Vérification TypeScript
pnpm build # Build de production
Monitoring et Observabilité
Health Checks
- Backend :
/api/actuator/health - Frontend :
/health - Database : Intégré dans Spring Boot Actuator
- Kubernetes : Liveness et Readiness probes
Métriques
- Prometheus :
/api/actuator/prometheus - Grafana : Dashboards pré-configurés
- Logs : Centralisés via ELK Stack
- APM : Traces distribuées
Auto-scaling
- HPA Backend : CPU 70%, Memory 80%, 2-10 replicas
- HPA Frontend : CPU 70%, 2-5 replicas
- Database : Scaling vertical automatique
Sécurité
Authentification
- JWT avec refresh tokens
- OAuth2 Resource Server
- Gestion des rôles et permissions
- Intercepteurs automatiques côté client
HTTPS et SSL
- Certificats SSL automatiques (Let's Encrypt)
- Redirection HTTP → HTTPS forcée
- HSTS headers configurés
- TLS 1.2+ uniquement
CORS et Sécurité API
- Configuration multi-environnements
- Origines autorisées dynamiques
- Headers sécurisés (CSP, X-Frame-Options)
- Rate limiting (100 req/min)
Contribution
Workflow Git
# Créer une branche feature
git checkout -b feature/nouvelle-fonctionnalite
# Développer et tester
git add .
git commit -m "feat: ajouter nouvelle fonctionnalité"
# Push et créer une PR
git push origin feature/nouvelle-fonctionnalite
Standards de Code
- Backend : Google Java Style Guide + Checkstyle
- Frontend : ESLint + Prettier + TypeScript strict
- Commits : Conventional Commits
- Tests : Couverture > 80%
- Documentation : JSDoc/JavaDoc obligatoire
Documentation
- API Interactive : http://localhost:8080/swagger-ui.html
- Architecture :
/docs/architecture.md - Déploiement :
/docs/deployment.md - Contribution :
/docs/contributing.md - API Reference : Documentation OpenAPI 3.0
Support et Debugging
Logs en Temps Réel
# Docker Compose
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres
# Kubernetes
kubectl logs -f deployment/backend -n xpeditis
kubectl logs -f deployment/frontend -n xpeditis
Debugging Avancé
# Backend debug mode avec profiler
SPRING_PROFILES_ACTIVE=dev,debug mvn spring-boot:run
# Frontend avec source maps
DEBUG=true pnpm dev
# Base de données
docker exec -it xpeditis-postgres psql -U xpeditis_user -d xpeditis_dev
Commandes Utiles
# Restart des services
docker-compose restart backend
kubectl rollout restart deployment/backend -n xpeditis
# Nettoyage
docker system prune -a
kubectl delete pods --field-selector=status.phase=Failed -n xpeditis
# Monitoring des ressources
docker stats
kubectl top pods -n xpeditis
Roadmap
Version 1.1 (Q1 2024)
- Authentification complète avec OAuth2
- Track & Trace en temps réel
- Notifications push
- Export PDF des devis
Version 1.2 (Q2 2024)
- Application mobile React Native
- API GraphQL
- Intégration paiements Stripe
- Multi-langues (EN, FR, ES)
Version 2.0 (Q3 2024)
- IA pour optimisation des routes
- Blockchain pour traçabilité
- Marketplace des transporteurs
- Analytics avancées
Licence
Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
Équipe
- Lead Developer : [Votre nom]
- DevOps Engineer : [Nom DevOps]
- UI/UX Designer : [Nom Designer]
- Product Owner : [Nom PO]
Xpeditis - Révolutionner le transport international Dernière mise à jour : Décembre 2024)