Karbé

Marketplace de location de carbets fluviaux de Guyane.

Karbé connecte les voyageurs et les hôtes pour des séjours authentiques le long des fleuves de Guyane, au cœur de la forêt amazonienne. La plateforme permet aux propriétaires de publier leurs carbets, et aux voyageurs de rechercher, réserver et payer leur séjour en ligne.

Sommaire

• Présentation
• Fonctionnalités
• Stack technique
• Prérequis
• Installation
• Variables d'environnement
• Déploiement production (karbe.cosmolan.fr)
• Développement
• Base de données (Prisma)
• Scripts npm
• Structure du projet
• Conventions Git & contribution
• Documentation complémentaire
• Licence

Présentation

Le carbet est l'habitat traditionnel amazonien : un abri ouvert, souvent en bois, installé au bord des fleuves. En Guyane, les carbets fluviaux sont un mode d'hébergement prisé pour découvrir la forêt, naviguer sur les fleuves (Maroni, Oyapock, Approuague…) et vivre une expérience proche de la nature.

Karbé est une marketplace à deux faces :

• Voyageurs — recherchent un carbet, consultent les disponibilités, réservent et paient en ligne, échangent avec l'hôte et laissent un avis après le séjour.
• Hôtes (loueurs) — créent leur profil, publient et gèrent leurs carbets (photos, tarifs, calendrier de disponibilité) et suivent leurs réservations.

La plateforme prévoit également une dimension B2B (créneaux réservés aux comités d'entreprise) et un modèle d'abonnement loueur. Voir la roadmap produit pour le détail des phases.

Fonctionnalités

Domaine	Description
Comptes multi-rôles	Voyageur, hôte et administrateur (authentification NextAuth).
Fiches carbet	Titre, description, fleuve, localité, géolocalisation, capacité, équipements, photos.
Recherche publique	Listing et fiche carbet rendus côté serveur (SSR) pour le SEO.
Disponibilités & tarifs	Calendrier par date, prix personnalisés, nuits minimum.
Réservation	Sélection de dates, calcul du prix (nuitée, ménage, frais de service).
Paiement	Encaissement via Stripe (réservation + abonnement loueur).
Messagerie	Conversation par réservation entre voyageur et hôte.
Avis & notes	Évaluation du séjour après le check-out.
Conformité	CGV, RGPD, mentions légales.

Toutes ces fonctionnalités ne sont pas encore livrées : voir la roadmap pour l'état d'avancement par phase.

Stack technique

• Next.js 16 — App Router, TypeScript, rendu serveur.
• React 19.
• Tailwind CSS v4 — styles utilitaires.
• Prisma 7 — ORM, datasource PostgreSQL. Le client est généré dans src/generated/prisma.
• NextAuth — authentification multi-rôles.
• Stripe — paiements (prévu).

Pour les choix d'architecture et les flux détaillés, voir docs/ARCHITECTURE.md.

Note : ce dépôt utilise une version de Next.js qui peut différer de la documentation publique. En cas de doute sur une API, consultez la documentation embarquée dans node_modules/next/dist/docs/.

Prérequis

• Node.js >= 20
• npm (fourni avec Node.js)
• Une base de données PostgreSQL accessible (locale ou distante)

Installation

1. Installer les dépendances :

   npm install
   

   Le script postinstall génère automatiquement le client Prisma dans src/generated/prisma.

2. Configurer les variables d'environnement :

   cp .env.example .env
   

   Renseignez ensuite les valeurs dans .env (voir ci-dessous).

3. Préparer la base de données :

   npx prisma migrate dev
   

Variables d'environnement

Le fichier .env.example liste les variables attendues. Copiez-le en .env et renseignez vos valeurs.

Variable	Rôle
DATABASE_URL	Chaîne de connexion PostgreSQL utilisée par Prisma.
AUTH_SECRET / NEXTAUTH_SECRET	Secret de signature des sessions NextAuth. Générer avec openssl rand -base64 32.
NEXT_PUBLIC_SITE_URL / APP_URL	URL publique de l'application (ex: https://karbe.cosmolan.fr).
STRIPE_SECRET_KEY	Clé secrète Stripe (mode test pour MVP).
STRIPE_WEBHOOK_SECRET	Secret du webhook Stripe.
STRIPE_OWNER_SUBSCRIPTION_PRICE_ID	Price ID de l'abonnement loueur Stripe.

Le fichier .env ne doit jamais être commité (il est ignoré par Git). Au fur et à mesure de l'ajout des intégrations (ex. Stripe), de nouvelles variables seront ajoutées à .env.example.

Déploiement production (karbe.cosmolan.fr)

Le repo inclut une stack de self-hosting Docker pour le MVP:

• Dockerfile (build Next.js standalone)
• docker-compose.prod.yml (app + PostgreSQL + MinIO + reverse proxy Caddy HTTPS)
• docker/Caddyfile
• .env.production.example

1) Préparer le serveur

• Docker Engine + Docker Compose plugin installés.
• DNS A/AAAA de karbe.cosmolan.fr pointant vers le serveur.
• Ports 80 et 443 ouverts.

2) Configurer l'environnement

cp .env.production.example .env.production

Renseigner toutes les variables, en particulier: POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD, DATABASE_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_OWNER_SUBSCRIPTION_PRICE_ID, APP_URL et NEXT_PUBLIC_SITE_URL.

docker-compose.prod.yml crée automatiquement le bucket MinIO défini par S3_BUCKET au démarrage via le service minio-init.

3) Appliquer les migrations Prisma

Les migrations doivent être appliquées avant le premier démarrage :

npx prisma migrate deploy

4) Lancer la stack

docker compose -f docker-compose.prod.yml up -d --build

Vérifier la santé:

curl -fsS https://karbe.cosmolan.fr/api/health

5) Connecter le webhook Stripe (TEST)

Depuis un poste ayant Stripe CLI:

stripe listen --forward-to https://karbe.cosmolan.fr/api/stripe/webhook

Copier le secret affiché (whsec_...) dans STRIPE_WEBHOOK_SECRET, puis redéployer.

Développement

npm run dev

L'application est disponible sur http://localhost:3000.

Base de données (Prisma)

Le schéma vit dans prisma/schema.prisma. Il décrit les entités de Karbé (utilisateurs, carbets, réservations, paiements, avis, messagerie…). Le modèle de données est détaillé dans docs/ARCHITECTURE.md.

# Régénérer le client Prisma après une modification du schéma
npx prisma generate

# Créer / appliquer une migration en développement
npx prisma migrate dev --name <nom_de_la_migration>

# Inspecter la base via une interface web
npx prisma studio

Scripts npm

Script	Description
npm run dev	Démarre le serveur de développement.
npm run build	Build de production.
npm run start	Démarre le serveur de production.
npm run lint	Lance ESLint.

Structure du projet

karbe/
├── prisma/
│   ├── schema.prisma      # Modèle de données (entités Karbé)
│   └── migrations/        # Migrations SQL générées par Prisma
├── public/                # Fichiers statiques
├── src/
│   ├── app/               # Routes App Router (pages, layouts, route handlers)
│   └── generated/prisma/  # Client Prisma généré (ne pas éditer à la main)
├── docs/
│   └── ARCHITECTURE.md    # Documentation d'architecture
├── ROADMAP.md             # Roadmap produit (MVP → V2 → V3)
└── README.md

Conventions Git & contribution

• La branche main est protégée : aucun commit direct.
• Travaillez sur une branche dédiée nommée feat/<sujet> (ou fix/<sujet>).
• Ouvrez une Pull Request vers main pour toute modification.
• Avant d'ouvrir la PR, vérifiez que npm run lint et npm run build passent.

Documentation complémentaire

• Roadmap produit — phases MVP → V2 → V3.
• Documentation d'architecture — stack, modèle de données et flux principaux.

Licence

Voir le fichier LICENSE.