docs(services): add CLAUDE.md for stt + events, fix stale entries, flag port collisions

New service docs:
- services/mana-stt/CLAUDE.md — FastAPI surface with Whisper MLX (local),
  WhisperX (rich), and Voxtral (local + Mistral API). Documents the lazy
  backend loading and the launchd plist setup on the Mac Mini.
- services/mana-events/CLAUDE.md — Hono/Bun service for public RSVP and
  event-sharing. Documents the host (JWT) vs public (token) split, the
  rate-limit sweeper, and the createApp factory pattern that lets unit
  tests run without bootstrapping the production sweeper.

Stale entries fixed:
- mana-auth: dropped "rewritten from NestJS / drop-in replacement" — the
  rewrite is the only mana-auth there is now. Email channel updated from
  Brevo SMTP to self-hosted Stalwart (see docs/MAIL_SERVER.md).
- mana-notify: same Brevo → Stalwart fix in the channel table and env
  var defaults.

PORT_SCHEMA.md flagged as aspirational:
- The doc was dated 2026-03-28 and presented as "single source of truth",
  but cross-checking against actual service source files (config.go,
  main.py, start.sh) shows nothing matches. Added a prominent warning at
  the top with the real ports + two confirmed collisions:
  * mana-image-gen and mana-video-gen both default to PORT 3026
  * mana-voice-bot and mana-sync both default to PORT 3050
  Today these are masked because image-gen + voice-bot live on the
  Windows GPU server while video-gen + sync live on the Mac Mini, but
  the moment they share a host they collide. Either execute the planned
  reorg or pick non-colliding ports and rewrite the doc to match
  reality — flagged as a real follow-up.
This commit is contained in:
Till JS 2026-04-08 12:23:48 +02:00
parent a3a47459c6
commit b0a08ce239
5 changed files with 197 additions and 8 deletions

View file

@ -1,8 +1,28 @@
# Port Schema
Canonical port assignments for all Mana services. This is the single source of truth.
> ⚠️ **ASPIRATIONAL — does not match running services as of 2026-04-08.**
>
> This document describes a *planned* reorganization of port assignments
> into clean ranges (30003009 core, 30103019 infra, 30203029 AI/ML, …).
> The reorg has not been executed: the actual ports the services bind to
> live in their `app/main.py` / `start.sh` / `config.ts` and currently
> follow a different scheme. Per-service ports are documented in each
> `services/*/CLAUDE.md`. Notable real-world ports today:
>
> - mana-auth `3001`, mana-credits `3061`, mana-user `3062`,
> mana-subscriptions `3063`, mana-analytics `3064`, mana-events `3065`
> - mana-media `3015`, mana-sync `3050`, mana-search `3021`,
> mana-notify `3040`, mana-crawler `3023`
> - mana-llm `3025`, mana-stt `3020`, mana-tts `3022`,
> mana-image-gen `3026`, mana-video-gen `3026` ⚠️ **collision**,
> mana-voice-bot `3050` ⚠️ **collision with mana-sync**
>
> Two real port collisions exist (image-gen ↔ video-gen, voice-bot ↔ sync)
> that are masked by the fact that they don't all run on the same host
> today. Either execute the reorg below, or pick non-colliding ports and
> update this doc to match reality.
**Last updated:** 2026-03-28
**Originally drafted:** 2026-03-28
## Principles