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            │
                │                                          │
  ┌──────────┐  │   ┌──────────────┐    ┌──────────────┐   │
  │          │  │   │ API Discovery │    │   Keycloak   │   │
  │  Wakapp  ├──┼──►│  pré-auth     │───►│  OAuth2 OIDC │   │
  │(frontend)│  │   └──────────────┘    └──────┬───────┘   │
  │          │◄─┼──────────────────────────────┘ (PKCE)    │
  │          │  │                                          │
  │          │  │   ┌──────────────────────────────────┐   │
  │          ├──┼──►│  API d'enrichissement /auth/enrich│   │
  │          │  │   └──────────────────────────────────┘   │
  │          │  │                                          │
  │          │  │   ┌──────────────────────────────────┐   │
  │          ├──┼──►│  API publique  /api/...           │   │
  │          │  │   │  CRUD multi-tenant + autorisations│   │
  │          │  │   └──────────────────────────────────┘   │
  └──────────┘  └──────────────────────────────────────────┘

Points clés :

L'API Discovery est consommée avant l'authentification pour obtenir l'URL de login Keycloak (start-login).
L'endpoint /api/auth/enrich est exposé publiquement : toute Wakapp peut l'appeler après avoir reçu un access_token Keycloak pour obtenir un wakaToken enrichi.
L'API publique est le point d'entrée unique pour toutes les opérations métier post-auth.

Les deux APIs publiques consommées par une Wakapp

API	Quand	Exemples d'endpoints
API Discovery	Avant l'authentification	`POST /discover/start-login`, `GET /api/discovery/subdomain`, `GET /api/discovery/email`
API publique	Après l'authentification	`GET /api/me`, `GET /api/config/users`, `POST /api/invitations`, etc.

Les URLs canoniques sont documentées dans Environnements. Aucune autre URL interne n'est consommable depuis une Wakapp.

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

Aspect	Plateforme WakaStart	Votre WakaApp
Auth	Keycloak OAuth2 PKCE	Implémenter le flow PKCE (voir chapitre 3)
Token enrichi	Géré par WakaStart, à transmettre en `x-enriched-token`	Stocker en cookie HttpOnly, ne pas inspecter localement
Vérification des droits	Endpoint `POST /api/token/authorize`	Déléguer la vérification — ne jamais décoder/valider le wakaToken localement
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 : l'API publique reconstruit le contexte utilisateur à partir de la clé.

Flux de communication (vue d'ensemble)

text
1. [PREAAUTH]  Wakapp → API Discovery  : POST /discover/start-login
                                          → URL Keycloak retournée
                Wakapp → Keycloak       : redirect navigateur (PKCE)
                Keycloak → Wakapp       : redirect avec code d'autorisation

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

3. [ENRICH]    Wakapp → API publique   : POST /api/auth/enrich (Bearer)
                                          → wakaToken enrichi retourné

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

5. [API CALLS] Wakapp → API publique   : GET|POST|PATCH|DELETE /api/...
                                          → 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 inspecter ni vérifier la signature du x-enriched-token côté Wakapp : déléguer à POST /api/token/authorize pour toute décision d'autorisation.
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