Premiers pas

Architecture

Vue d'ensemble de l'architecture Wakapp : hiérarchie multi-tenant, services, flux de communication et modes d'accès.

Version v1.04 min de lecture

Architecture

Une Wakapp est une application tierce intégrée à la plateforme WakaStart. Ce chapitre donne la carte complète du territoire avant de plonger dans les détails.

Pourquoi cette étape

Avant d'écrire la moindre ligne de code d'intégration, il faut comprendre comment les entités s'emboîtent et quels services exposent quelles frontières. Une erreur courante est de traiter la plateforme comme un simple CRUD REST alors qu'elle porte une hiérarchie multi-tenant stricte dont dépend toute l'isolation des données.

Hiérarchie multi-tenant

WakaStart organise les entités de haut en bas :

text
Partner
  └── Network  (1 realm Keycloak)
        └── Customer
              ├── App  ←── la Wakapp se connecte ici
              ├── User
              └── Team

Entité	Rôle	Identifiant court (WID)
Partner	Propriétaire de la plateforme (ex: Wakastellar)	`PTR001`
Network	Regroupement de Customers, 1 realm Keycloak dédié	`NET001`
Customer	Tenant final (une entreprise cliente)	`ACM001`
App	Application Wakapp enregistrée pour un Customer	`APP001`
User	Utilisateur humain, membre d'un Customer	`WKST05`
Team	Groupe d'utilisateurs au sein d'un Customer	`TEAM01`

Règle d'or : toute donnée appartient à un Customer. L'isolation est enforced au niveau des requêtes SQL (filtres Prisma) — jamais par des bases séparées.

Position de la WakaApp dans l'écosystème

text
                  ┌─────────────────────────────────────┐
                  │           PLATEFORME WAKASTART        │
                  │                                       │
  ┌──────────┐   │  ┌─────────────┐   ┌───────────────┐ │
  │          │   │  │  Discovery  │   │   Keycloak    │ │
  │  Wakapp  ├───┼─►│  :3002      │──►│   :8080       │ │
  │(frontend)│   │  │  pré-auth   │   │   OAuth2 OIDC │ │
  │          │   │  └─────────────┘   └───────┬───────┘ │
  │          │◄──┼────────────────────────────┘(PKCE)   │
  │          │   │                                       │
  │          │   │  ┌─────────────┐   ┌───────────────┐ │
  │          ├───┼─►│  BFF        │   │  ws-serv-token│ │
  │          │   │  │  :3009      ├──►│  :3001        │ │
  │          │   │  │  (wakastart │   │  enrichissement│ │
  │          │   │  │  seulement) │   │  JWT          │ │
  │          │   │  └─────────────┘   └───────────────┘ │
  │          │   │                                       │
  │          │   │  ┌─────────────────────────────────┐ │
  │          ├───┼─►│  Public API  :3005               │ │
  │          │   │  │  ws-back-api                     │ │
  │          │   │  │  CRUD multi-tenant (49 modules)  │ │
  │          │   │  └─────────────────────────────────┘ │
  └──────────┘   └─────────────────────────────────────┘

Points clés :

Le BFF wakastart (ws-back-wakastart :3009) est dédié à l'app Wakastart elle-même. Les Wakapps tierces ne le traversent pas pour le start-login — elles parlent directement à Discovery.
L'enrichissement /api/auth/enrich est exposé publiquement par le BFF : toute Wakapp peut l'appeler après avoir reçu un access_token Keycloak.
La Public API (ws-back-api :3005) est le point d'entrée unique pour toutes les opérations CRUD post-auth.

Les deux backends consommés par une Wakapp

Service	URL dev	Rôle	Quand
`ws-back-discovery`	`http://localhost:3002`	Lookup email/subdomain, `start-login`	Avant l'authentification
`ws-back-api`	`http://localhost:3005`	Tout le reste (me, config, invitations, etc.)	Après l'authentification

Ne jamais appeler ws-back-wakastart :3009 depuis une Wakapp tierce (sauf /api/auth/enrich). Ce BFF gère l'app Wakastart admin, pas vos applications.

Stack côté Wakastart vs côté WakaApp

Aspect	Plateforme WakaStart	Votre WakaApp
Framework backend	NestJS 11, TypeScript	Libre (NestJS, Express, FastAPI…)
Auth	Keycloak OAuth2 PKCE	Implémenter le flow PKCE (voir chapitre 3)
Token enrichi	HS256 signé par `JWT_SECRET`	Transmettre en `x-enriched-token`
ORM	Prisma 7 (PostgreSQL)	Libre
Frontend	Next.js 16 (wakastart)	Libre (Next.js, Nuxt, SvelteKit…)
Identifiants	WID (6 chars) + UUID	Utiliser de préférence les WIDs dans les URLs

Deux modes d'accès

Mode	Usage	Header(s) requis
JWT Bearer + enriched	Apps utilisateur (frontend proxifié)	`Authorization: Bearer <keycloak_token>` + `x-enriched-token: <wakastart_token>`
API Key	Services backend, scripts, cron	`x-api-key: sk_live_...`

Les API keys remplacent entièrement la paire Bearer+enriched : la Public API vérifie la clé via ws-serv-token et reconstruit le contexte utilisateur.

Flux de communication complet (vue d'ensemble)

text
1. [PREAAUTH]  Wakapp → Discovery  : POST /discover/start-login
                Discovery → Keycloak : URL de login construite
                Keycloak → Wakapp  : redirect avec code PKCE

2. [EXCHANGE]  Wakapp → Keycloak  : POST /token (code + verifier)
                Keycloak → Wakapp  : access_token RS256 + refresh_token

3. [ENRICH]    Wakapp → BFF       : POST /api/auth/enrich (Bearer RS256)
                BFF → ws-serv-token: enrichissement droits métier
                BFF → Wakapp      : wakaToken HS256

4. [PROFILE]   Wakapp → PublicAPI : GET /me (Bearer + x-enriched-token)
                PublicAPI → Wakapp: profil + rôles + appRights

5. [API CALLS] Wakapp → PublicAPI : GET|POST|PATCH|DELETE /api/...
                PublicAPI → Config : CRUD Prisma (filtrage tenant auto)
                PublicAPI → Wakapp: données métier paginées

Bonnes pratiques

Stocker les tokens dans des cookies HttpOnly (jamais localStorage).
Utiliser les WIDs dans vos URLs et logs — les UUIDs sont internes.
Ne jamais exposer x-internal-secret côté Wakapp : ce header est réservé aux services internes.
Respecter la hiérarchie dans vos requêtes : un CustomerAdmin ne peut pas accéder aux données d'un autre Customer.

Aller plus loin

Discovery — Identifier l'utilisateur : premier appel avant auth
Authentification — OAuth2 PKCE : flow complet
Utilisation de l'API : headers, pagination, multi-tenant