Développement local

title: Développement local description: Démarrer le dépôt applicatif Orbit : prérequis, base locale, scripts, tests de bout en bout et carte du dépôt.

Guide d'ingénierie du dépôt BoostEcom/orbit.easyconnector.app. Repris de l'ancien dépôt Studio (base figée 94d051c, voir la base source figée) et mis à jour pour Orbit. Le README du dépôt applicatif présente le produit ; toute la documentation vit dans ce dépôt, publiée sur https://docs.easyconnector.app : le dépôt applicatif ne contient aucun dossier de prose.

Orbit est le produit : un Context OS. Brain est son cœur de contexte et de mémoire (/brain), Creative Studio son outil natif de création (/studio : visuels, vidéos, films d'interface, voix), et MCP / API exposent le contexte d'Orbit aux agents et applications externes (/api/mcp, /api/v1). Tout est servi par une seule application web, https://orbit.easyconnector.app (architecture/domains.md).

Le code de Creative Studio vient d'un studio qui avait été extrait d'une ancienne plateforme externe (ADR 0011, remplacée par Orbit). Cette plateforme n'est pas le parent d'Orbit : ce qui en a été copié est de la provenance, et les ponts prévus vers elle (B1 à B10) sont retirés. Orbit a sa propre base, son propre login.

Deux modes

• Libre : générer sur n'importe quel sujet, sans produit. En base, productId = null.
• Connecté : générer pour un produit (projet) de l'espace. Les produits sont des données créées depuis l'interface ; le registre (products/products.json) ne contient que le produit de démonstration orbit, que le seed importe. Un produit apporte son site, son Brain, ses connexions et, s'il en a, son design.

Démarrage rapide

Prérequis : Node 24 (.nvmrc), pnpm 10, PostgreSQL 16 local.

# 1. Dépendances (génère aussi le client Prisma)
pnpm install

# 2. Une base locale dédiée à Orbit (jamais celle d'une autre application)
sudo -u postgres psql -c "CREATE ROLE orbit LOGIN SUPERUSER PASSWORD 'orbit'"
sudo -u postgres psql -c "CREATE DATABASE orbit OWNER orbit"

# 3. Variables : un seul .env, à la racine
cp .env.example .env
#    DATABASE_URL=postgresql://orbit:orbit@localhost:5432/orbit
#    FOUNDER_EMAIL=<ton adresse>
#    NEXTAUTH_SECRET=<openssl rand -base64 32>  (facultatif en dev)

# 4. Schéma, puis produits et fondateur
pnpm db:deploy     # applique les migrations committées
pnpm db:seed       # produit de démonstration + membre fondateur (action explicite, jamais au build)

# 5. L'application
pnpm dev           # http://localhost:3000
curl localhost:3000/api/health   # {"ok":true,"version":"0.1.0","db":"ok","auth":"development"}

Se connecter en local : ouvrir http://localhost:3000/auth (/ est l'accueil marketing public ; toute page de l'espace de travail renvoie vers /auth?from=… sans session), saisir FOUNDER_EMAIL, puis le code à six chiffres que le terminal de pnpm dev imprime sur une ligne [mail:console] (hors d'un déploiement Vercel, le studio n'envoie aucun email, quelles que soient les variables posées ; un déploiement ne retombe jamais sur la console, ADR 0016, C2). Le reste (inviter, allouer, plafonner, révoquer) : Runbook membres-et-credits.

Le rôle SUPERUSER local sert à prisma migrate dev, qui crée une base fantôme pour calculer une migration. En production, prisma migrate deploy n'en a pas besoin.

Scripts

db:migrate, db:deploy et db:seed refusent une base qui porte des tables d'un autre produit (celles de l'ancienne plateforme, PLATFORM_TABLES ; packages/db/scripts/guard-target.ts). En production, les migrations passent par le workflow Deploy production database (.github/workflows/db-deploy.yml), jamais par le build Vercel (README, « Production database releases »).

Tests de bout en bout

# Une fois : Chromium
pnpm --filter @orbit/web exec playwright install chromium

# Arrêter tout `pnpm dev` de ce dépôt d'abord (Next refuse un second
# serveur de développement dans le même dossier), puis :
pnpm e2e

pnpm e2e lance next dev sur le port 3217 (E2E_PORT pour un autre) contre la base orbit_e2e du même serveur Postgres (E2E_DATABASE_URL pour une autre ; son nom doit contenir e2e). La base est créée si elle manque, avant le démarrage du serveur, par apps/web/e2e/serve.mjs : le rôle doit donc pouvoir créer une base (le rôle orbit du démarrage rapide est SUPERUSER). Sans ce droit, la créer une fois à la main :

sudo -u postgres psql -c "CREATE DATABASE orbit_e2e OWNER orbit"

Puis global-setup.ts applique les migrations, vide toutes les tables et sème le fondateur. Le journal du serveur est écrit dans apps/web/e2e/.artifacts/server.log (les tests y lisent les codes) ; ses erreurs s'affichent aussi dans la sortie de Playwright, et si le serveur s'arrête avant d'être prêt, les dernières lignes du journal sont imprimées avec la cause.

Carte du dépôt

apps/web/             L'application Orbit : Next 16, React 19, Tailwind 4, sombre, français, URL en anglais
  src/app/            Routage et composition seulement :
                      / (accueil marketing public), /demo (prototype interne, PlatformAdmin),
                      (minimal)/  /auth (connexion OTP), /onboarding,
                      (dashboard)/ /brain, /studio et /studio/[product] (galerie, composer,
                      sections en ?s=, rendu ouvert en &item=), /studio/{overview,qc,concepts,
                      review,growth}, /academy, /developers/{api,mcp}, /costs (?period=),
                      /members (?member=<id>), /settings,
                      oauth/authorize, .well-known/oauth-*,
                      /api/auth/* (NextAuth, send-otp, sign-out ?reason=), /api/health,
                      /api/v1/projects, /api/mcp, /api/oauth/{register,token,revoke},
                      /api/feedback, /api/cockpit/* (lectures, gestes payants, suivi des jobs),
                      /api/dev/*/route.dev.ts (next dev seulement),
                      /api/generation/context, /api/generations(/[id]) (lectures GET),
                      /api/webhooks/render (rappel du runner), /api/webhooks/video/[id]
                      (webhook signé de la Gateway), /api/cron/{generations-sweep,retention}
  src/cockpit/        L'hôte du studio : périmètre produit, gestes, prix, galerie, tableaux, avatars, jobs
  src/components/     Interface : ui (primitives), shell (AppFrame), brain, studio, landing, developers, admin
  src/features/studio Navigation (nav/routes.ts : les pages et leurs permissions), ouverture du studio
  src/workspace/      Projets Studio, onboarding, inscription (sign-up.ts), PlatformAdmin
  src/modules/brain/  Le Brain : Spaces, Memories, capacité, sources, actions (ADR 0020)
  src/developers/     Clés orb_…, OAuth MCP, API v1
  messages/fr.json    Le catalogue next-intl de l'interface
  src/generation/     Couche serveur de la génération : mutations typées pour l'adaptateur
                      d'interface (contrat : https://docs.easyconnector.app/architecture/contrat-studiohost)
  src/proxy.ts        Première porte : pas de session valide, pas d'espace de travail
  src/auth/           OTP, NextAuth, matrice des permissions, requireMember
  src/members/        Gestes du fondateur (inviter, rôle, plafonds, révoquer)
  src/credits/        Branchement du ledger et alerte d'équipe
  src/lib/            Sécurité (IP de confiance, limites, verrouillage, Origin), HTTP (parseJson), emails, formats
  src/config/         Domaines (domains.ts), prix du composer dérivés de @orbit/engine/prices
  src/env/            Env typé (zod) et garde server-only
  src/i18n/           Dictionnaire fr typé, et le chargeur next-intl
  e2e/                Playwright
packages/db/          @orbit/db : schéma Prisma, migrations, client, seed, garde de cible
packages/remotion/    @orbit/remotion : compositions, capture, rendu, publication (React 18, projet à part)
packages/cinema/      @orbit/cinema : moteur cinéma, contrat de capture v1 (__ORBIT_CINEMA__), plateau local
packages/engine/      @orbit/engine : ledger par membre ; génération (journal, fournisseurs, Blob) ; rendus ; visual
packages/connectors/  @orbit/connectors : ports, registre des liaisons, crédits (ADR 0016)
products/             @orbit/products : registre (produit de démonstration orbit), lecteur typé, design orbit.DESIGN.json
.github/workflows/    ci.yml, render.yml (le runner de rendu), db-deploy.yml (migrations de production)

La documentation (ADR, architecture, runbooks, migration, roadmap) n'est pas dans ce dépôt : elle vit dans BoostEcom/docs.easyconnector.app.

Phases

1. Fondations : monorepo, app, schéma et migration, registre, docs, CI.
2. Accès et crédits : login OTP avec inscription libre, rôles relus en base, ledger par membre, écrans « Membres et crédits » et « Coût », alerte d'équipe.
3. Moteurs : Remotion, cinéma, génération, workflow de rendu, rappel et balayage ; la couche serveur que le cockpit transplanté appelle.
4. Surfaces : galerie, QC, concepts, coût, produits, cinéma, distribution, relecture, académie, développeurs.
5. Bout en bout et mise en ligne : les 30 flux E2E, la production. La bascule du trafic vers ce dépôt suit la porte de AGENTS.md (« Cutover »).

Les anciens ponts vers l'ancienne plateforme (B1 à B10) sont retirés, avec leurs variables ; la Fabrique (production par lots) aussi. Détail : roadmap.

Lire ensuite

• AGENTS.md (dépôt applicatif) : règles dures du dépôt (nommage, domaines, architecture, bascule).
• Architecture de l'application : paquets, données, accès, crédits, anciens ponts retirés (section 6), rendus, et l'interface (section 9).
• Migration : la base figée, ce qui a été repris, renommé ou retiré de l'ancien dépôt.
• Roadmap : les phases et les 30 flux E2E.