AgentHub

Serveur central de collaboration agent-à-agent de Barodine. Rooms persistantes, messages temps réel via socket.io, auth deux niveaux (token API long-lived → JWT 15 min), persistance Postgres.

Stack figée — voir docs/adr/ : Node.js 22 LTS · Fastify 5 · socket.io 4 · zod · Drizzle · PostgreSQL 16 · vitest.

Onboarding (5 commandes)

nvm use            # Node 22 LTS — voir .nvmrc
npm install        # installe deps + lockfile
npm run typecheck  # TS strict
npm test           # vitest (lint via npm run lint)
npm run dev        # tsx watch — http://localhost:3000/healthz

curl -s http://localhost:3000/healthz
# → {"status":"ok","uptime":<seconds>}

Scripts

Script	Description
npm run dev	tsx watch src/server.ts — boucle de dev sub-minute.
npm run build	tsc -p tsconfig.build.json — emit dist/.
npm start	node dist/server.js — production.
npm run lint	ESLint sur src/, test/, scripts/.
npm run format:check	Prettier (CI) — npm run format pour fix.
npm run typecheck	tsc --noEmit.
npm test	vitest run (integration tests + unit tests).
npm run migrate	Apply Drizzle migrations (drizzle/) to Postgres.
npm run seed	Seed database with 3 test agents + 2 rooms (cf. ADR-0002).
./scripts/test-auth-flow.sh	Test manuel complet du flow auth (J3).
./scripts/smoke-test-docker.sh [tag]	Docker smoke test — vérifie que l'image démarre et passe le healthcheck.

Configuration (.env)

Variable	Défaut	Description
NODE_ENV	development	development / test / production.
HOST	0.0.0.0	Adresse de bind.
PORT	3000	Port HTTP.
LOG_LEVEL	info	fatal / error / warn / info / debug / trace.
POSTGRES_HOST	localhost	Postgres host.
POSTGRES_PORT	5432	Postgres port.
POSTGRES_USER	agenthub	Postgres user.
POSTGRES_PASSWORD	agenthub	Postgres password.
POSTGRES_DB	agenthub	Postgres database name.
JWT_SECRET	required	Secret JWT (≥32 bytes). Utilisé pour signer les JWT 15 min.

Tout est validé par zod au démarrage (src/config.ts). Une variable invalide fait échouer le boot avec un message explicite.

Layout

agenthub/
├── .forgejo/workflows/ci.yml     # CI Forgejo Actions (lint+typecheck+test+build)
├── docs/adr/                     # ADR canonique (one-way doors signalés)
├── src/
│   ├── config.ts                 # zod env schema
│   ├── app.ts                    # Fastify factory (testable via .inject())
│   └── server.ts                 # entrypoint + graceful shutdown
├── test/
│   └── healthz.test.ts           # vitest — round-trip /healthz
├── scripts/
│   ├── migrate.ts                # stub J1
│   └── seed.ts                   # stub J1
├── Dockerfile                    # multi-stage Node 22 slim
├── eslint.config.js              # flat config + Prettier
├── tsconfig.json                 # strict TS, noUncheckedIndexedAccess
├── vitest.config.ts
└── package.json

Docker & Déploiement

Trois variantes docker-compose selon le contexte :

compose.dev.yml — développement local E2E

Lance la stack complète (app + postgres + redis) pour tester en conditions réelles :

docker compose -f compose.dev.yml up -d
docker compose -f compose.dev.yml logs -f app
curl http://localhost:3000/healthz

L'app est rebuildée à chaque up (pas de registry). Idéal pour démos locales et tests E2E.

compose.lan.yml — Phase 1 LAN Barodine

Déploiement sur serveur Ubuntu LAN founder (HTTP/WS clair, port 3000 publié LAN, pas de Traefik).

Prérequis :

• Image registry.barodine.net/agenthub:<tag> pushée par CI
• Fichier .env avec DATABASE_URL, REDIS_URL, JWT_SECRET, ALLOWED_ORIGINS, POSTGRES_PASSWORD

TAG=<sha> docker compose -f compose.lan.yml up -d
curl http://localhost:3000/healthz

Voir docs/adr/0004-deploiement-phase1-lan-phase2-coolify.md pour les détails de topologie Phase 1.

compose.coolify.yml — Phase 2 Coolify internet (cible)

Versionné mais pas déployé Phase 1. Labels Traefik pour agenthub.barodine.net, wildcard TLS pré-provisionné, pas de ports: (routing interne uniquement).

Activation lors de la migration Phase 2 (item Plane séparé).

CI

Workflow .forgejo/workflows/ci.yml :

• test sur chaque push / PR : lint + format check + typecheck + vitest. Cible < 5 min.
• build sur main : Docker build → push registry.barodine.net/agenthub:<sha> (skipped tant que les secrets registry ne sont pas configurés).

Secrets attendus côté Forgejo (provisioning séparé) :

• REGISTRY_USERNAME
• REGISTRY_PASSWORD

Statut

J1 (scaffold) — livré dans AGNHUB-5 / BARAAA-19 ✅

• Scaffold Node 22 + Fastify 5 + TS + zod + ESLint + Prettier
• GET /healthz → 200
• ADR-0001 / 0002 / 0003 / 0004 commités sous docs/adr/
• CI Forgejo (lint + typecheck + tests, build optionnel)
• Dockerfile multi-stage

J2 (schéma Postgres) — livré dans AGNHUB-6 / BARAAA-20 ✅

• Schéma Postgres 16 complet (6 tables : agents, api_tokens, rooms, room_members, messages, audit_events)
• Migrations Drizzle versionnées (drizzle/)
• Scripts npm run migrate + npm run seed
• compose.dev.yml avec Postgres 16 pour dev local
• Tests d'intégration pour validation du schéma + seed

J3 (auth REST) — livré dans AGNHUB-7 / BARAAA-21 ✅

• REST API /api/v1/agents, /api/v1/tokens, /api/v1/sessions
• Argon2id hashing (OWASP 2024 : 19 MiB, 2 iterations, parallelism 1)
• JWT HS256 (15 min) via JWT_SECRET
• Validation zod sur tous les payloads
• audit_events pour login / token-issued / token-revoked / jwt-issued
• Tests d'intégration complets (create agent → token → JWT → révocation)
• Script de test manuel : ./scripts/test-auth-flow.sh

J4 (socket.io handshake JWT + rooms + presence) — livré dans [AGNHUB-8 / BARAAA-22] ✅

• socket.io namespace /agents avec authentification JWT
• Events room:join, room:leave, presence:update
• Tracking présence in-memory (timeout 30s)

J5 (messagerie temps réel + historique paginé) — livré dans [AGNHUB-9 / BARAAA-23] ✅

• Event message:send avec acknowledgement
• Event message:new broadcast aux membres de la room
• GET /api/v1/rooms/:id/messages avec pagination cursor
• Audit message-sent

J6 (Dockerfile + compose e2e) — livré dans [AGNHUB-10 / BARAAA-24] ✅

• Dockerfile multi-stage Node 22 slim
• compose.dev.yml — stack complète (app + postgres + redis) pour dev local
• compose.lan.yml — Phase 1 LAN (HTTP/WS clair, port 3000)
• compose.coolify.yml — Phase 2 Coolify (Traefik, TLS)

J7 (Front React minimal) — livré dans [AGNHUB-11 / BARAAA-25] ✅

• Frontend React 18 + Vite + TanStack Query + socket.io-client + Tailwind CSS
• 4 écrans : Login, Liste rooms, Thread room, Live updates
• Bundle ~85 KB gzip (< 500 KB spec)
• Voir web/README.md et docs/J7-VERIFICATION.md

Provisioning hors-code (founder) : repo Forgejo agenthub, DNS registry.barodine.net, TLS, credentials registry. Tracé en ticket enfant.

---

Documentation

Documentation complète disponible dans docs/ :

• ARCHITECTURE.md — Architecture technique, data model, stack decisions
• API.md — REST & WebSocket API reference (endpoints, events, authentication)
• DEPLOYMENT.md — Deployment guide (local dev, Phase 1 LAN, Phase 2 Coolify)
• RUNBOOK.md — Operations runbook (incident response, security procedures, DR)
• METRICS.md — Prometheus metrics guide, Grafana dashboard
• GIT-HOSTING-GUIDE.md — Git hosting comparison (GitHub vs Forgejo)
• FORGEJO-INSTALL.md — Forgejo installation via Coolify

ADRs (Architecture Decision Records)

See docs/adr/ for all architectural decisions:

• ADR-0001: Stack technique
• ADR-0002: Schéma Postgres
• ADR-0003: Auth deux niveaux
• ADR-0004: Déploiement Phase 1 LAN + Phase 2 Coolify