flint/AGENT.md

AGENT.md - Guide SaaS Multi-Tenant

Version: 3.0

But

Decrire l'architecture cible du monorepo SaaS pour bot Discord multi-tenant.

Vue d'ensemble

• Stack backend: Node.js + TypeScript + Express + PostgreSQL + Redis + BullMQ.
• Bot runtime: Discord.js avec gestion dynamique multi-instance.
• Frontend: Next.js App Router.
• Structure: monorepo apps/* + packages/*.

Organisation des dossiers

• apps/api/
  • OAuth2 Discord, JWT cookie, routes multi-tenant, validation token bot, publication jobs BullMQ.
• apps/bot/
  • BotManager dynamique (Map<botId, Client>), worker de controle (start/stop/restart).
• apps/web/
  • Dashboard utilisateur (login, liste bots, ajout bot, actions runtime).
• packages/shared/
  • Types partages, constantes queue, helpers Redis namespacing, chiffrement token AES-GCM.
• database/migrations/
  • SQL versionne (schema_migrations) avec schema multi-tenant.

Principes d'architecture

• Multi-tenant strict:
  • toutes les requetes de lecture/ecriture passent par tenant_id.
  • tables critiques liees a tenant_id et/ou owner_user_id.
• Pas de secret en clair:
  • token bot chiffre en DB (token_ciphertext, token_iv, token_tag).
• Controle runtime decouple:
  • API publie des jobs, bot manager consomme et execute.
• Separation responsabilites:
  • API: auth + orchestration.
  • Bot: runtime Discord.
  • Web: UX dashboard.

Conventions de code

• TypeScript strict.
• Exports nommes.
• Erreurs API explicites et codes HTTP coherents.
• Logs sans fuite de secrets.

Workflow recommande

1. Ajouter/adapter migration SQL dans database/migrations.
2. Adapter repositories API/Bot avec filtre tenant.
3. Ajouter endpoint API + validation zod.
4. Brancher action queue si runtime impacte.
5. Mettre a jour le dashboard web.
6. Valider npm run typecheck puis docker compose up -d --build.

Securite

• Ne jamais committer .env.
• Garder TOKEN_ENCRYPTION_KEY hors depot.
• Appliquer httpOnly + sameSite sur cookie session.
• Eviter les logs de payloads sensibles (token, secrets).