Introduction

KOHAMI est un avatar IA conversationnel 3D destiné aux seniors autonomes, déployé en mode kiosque Android sur tablette. Le produit pilote une présence vocale continue (avec lip-sync), des widgets contextuels (météo, news, jeux cognitifs, vision), et un système d'alertes avec escalade aidants.

Cette documentation couvre exclusivement le périmètre back-end porté par Bruno Dogbase (apps/api/ plus voice-worker plus infra Scaleway). Le front-end React Native (tablette) et le dashboard administrateur sont produits par Nathan Lengagne (JUWA) et documentés séparément.

Public visé

• Nathan Lengagne (JUWA), intégration front-end React Native et dashboard admin
• Tristan Dumas (CTO JUWA), recette de jalon et validation contractuelle
• Futurs intégrateurs de l'API KOHAMI

Navigation

• Architecture, bounded contexts DDD, voice-worker, infra Scaleway
• Invariants, les 28 règles non négociables du produit
• Quickstart, du login JWT au premier event DataChannel reçu
• Authentification, trois rôles JWT, 2FA TOTP, refresh
• Environnements, URLs dev/staging/prod et gestion des secrets
• Guides, pipeline voix temps réel, états d'onboarding, cascade alertes, consentements RGPD
• Reference REST API, catalogue endpoint-par-endpoint
• Reference Events, schémas DataChannel auto-générés
• Troubleshooting, codes d'erreur et debug voix
• Operations, procédures de déploiement et runbooks

Conventions

• Contenu en français (langue primaire du projet KOHAMI)
• Snippets de code en anglais, commentaires inline tolérés en français
• Versions stack : NestJS 10, Bun 1.3.12, LiveKit Agents JS 1.4.x, Mistral La Plateforme
• Hébergement : Scaleway Object Storage public fr-par (INV-T02, aucune donnée hors UE)

Sources de vérité

Pour les décisions techniques internes du back-end, voir les ADRs dans le dépôt :

• apps/api/docs/decisions/, ADRs back-end
• packages/shared/src/events/, contrats Zod partagés
• apps/api/specs/, critères d'acceptation par bloc