Fluid, segmented audio guide tailored for taxi passengers (and pedestrians) with mobile-first UX.

Structure minimale : apps/, services/, packages/, infra/

• pnpm (v7+)
• Node 18+
• git
• Docker Desktop

1. Installer : pnpm install
2. Postgres local : pnpm db:local:start (idempotent — laisse-le tourner)
3. Développement : pnpm dev (API + web ; réutilise le Postgres ci-dessus)
4. Full stack : pnpm dev:all (Postgres + OSRM + API avec DB + web :3080 + admin :3081)
5. Tests : pnpm test
6. Admin seul : pnpm admin

Commandes complètes : sections ci-dessous et package.json.

Voir les configurations de déploiement dans config.

Toutes les commandes vivent dans package.json. Préfixe utile à retenir :

« local » ne veut rien dire dans Docker Desktop ; dev = ce que tu lances avec pnpm dev / dev:infra.

Une seule stack day-to-day. Postgres pour le dev et les previews node ; OSRM pour le routing.

# Tout l'infra Docker de dev d'un coup
pnpm dev:infra:status
pnpm dev:infra:start
pnpm dev:infra:stop

# Ou service par service
pnpm db:local:status | start | stop | logs
pnpm osrm:local:status | start | stop

# Alias Postgres
pnpm db:start / pnpm db:stop

Rétrocompat : un Postgres déjà up sous city-guided / city-guided-local / city-guided-db est réutilisé (noop + message).
pnpm dev appelle db:local:start + osrm:local:start (sauf SKIP_OSRM=1).

Sur Postgres partagé, chaque preview node crée une base isolée (cityguided_pr_42, cityguided_main_<hash>, …).

Boote le head d’une PR dans un git worktree isolé (sans toucher à ton working tree). Deux modes :

• Nom stack : city-guided-preview-<n> (node : titre terminal / ps ; docker : visible dans Docker Desktop)
• Worktree : .worktrees/pr-<n>/ — ports/pids dans .preview-ports
• Ports dynamiques (base API 4100 / web 3180 / admin 3181) — plusieurs PRs en parallèle OK
• stop ne tue que la PR demandée

pnpm preview:pr 42                         # node (multi-instance)
pnpm preview:pr 43                         # 2e preview → autres ports + autre DB
pnpm preview:pr 42 --mode docker           # stack Compose isolée
pnpm preview:pr:stop 42                    # stop uniquement la #42
pnpm preview:pr:stop 42 --remove           # stop + worktree + drop DB (node)
pnpm preview:pr --help

Lien partageable : skill ezk-preview (tunnel) sur le port web de cette PR (banner au démarrage).

Même moteur que preview:pr, mais sur le checkout courant (pas de worktree, pas de git checkout). Le nom de stack vient de la branche (ou d’un argument).

• Slug = branche sanitizée + hash court du nom d’origine (évite les collisions feat/foo vs feat-foo)
• Meta : .preview-stacks/<slug>/ (ports/pids) — le code reste à la racine
• Mode node : distDir Next isolé (.next-preview-<slug>) pour cohabiter avec pnpm dev
• Pour forcer la DB partagée cityguided plutôt qu’une DB isolée : PREVIEW_DATABASE_URL=postgresql://cityguided:cityguided@localhost:5433/cityguided pnpm preview:branch (l’URL doit être joignable ; auto-start Docker local uniquement pour localhost:5433)

pnpm preview:branch                        # branche courante → city-guided-<slug>
pnpm preview:branch main                   # naming only (ne change pas de branche git)
pnpm preview:branch --mode docker
pnpm preview:branch:stop                   # stop la stack de la branche courante
pnpm preview:branch:stop main --remove     # même nom d’argument que au start
pnpm preview:branch --help

Si Docker Desktop montre encore city-guided + city-guided-local :

pnpm dev:infra:status

# 1) Arrêter l'ancien OSRM + Postgres legacy
pnpm osrm:local:stop          # stoppe aussi city-guided-local
pnpm db:local:stop            # stoppe city-guided / city-guided-db / city-guided-dev

# 2) Optionnel : retirer les containers morts
docker rm -f city-guided-local-postgres-1 city-guided-postgres-1 2>/dev/null || true

# 3) Relancer sous le nom unique city-guided-dev
pnpm dev:infra:start
pnpm dev:infra:status

Tu dois alors voir une stack city-guided-dev (postgres + osrm).
⚠️ Nouvelle volume Postgres si tu as rm l’ancien container — re-seed / db:push si besoin.

Ne lance plus de compose avec -p city-guided-local pour du Postgres.

Déploiement sur AWS ECS Fargate avec scale-to-zero automatique pour optimiser les coûts.

⚠️ L'infra AWS est un projet autonome, hors workspace pnpm (ses ~285 Mo de dépendances CDK faisaient échouer les builds Render en Out of memory). Elle s'installe à la demande :

pnpm infra:aws:install

Ensuite, tous les scripts pnpm infra:* fonctionnent normalement. Détails : infra/provisioning/aws/README.md.

Ce projet contient deux packages npm qui peuvent être installés dans d'autres projets:

• @bacasable/lifefindsaway - Système d'idéation et exploration de features (Phase A)
• @bacasable/iamthelaw - Système de gestion de règles LLM pour développement

📚 Documentation:

• PACKAGES.md - Guide complet d'installation et publication
• QUICKSTART-PACKAGES.md - Démarrage rapide
• ALTERNATIVE-VERDACCIO.md - Configuration registre privé

🚀 Utilisation rapide:

# Publier sur GitHub Packages
./scripts/publish-package.sh both patch

# Installer dans un autre projet
echo "@bacasable:registry=https://npm.pkg.github.com" > .npmrc
pnpm add @bacasable/lifefindsaway @bacasable/iamthelaw