mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-14 19:01:08 +02:00

Till JS b0a08ce239 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.

2026-04-08 12:23:48 +02:00

2.6 KiB

Raw Blame History

mana-notify (Go)

Go replacement for the NestJS mana-notify service. Unified notification microservice for email, push, Matrix, and webhook notifications.

Architecture

Language: Go 1.25
Database: PostgreSQL (pgx v5, 5 tables in notify schema)
Queue: Go channels + goroutine worker pool (replaces BullMQ)
Metrics: Prometheus
Port: 3040

Endpoints

Notifications (X-Service-Key auth)

POST /api/v1/notifications/send — Send immediately
POST /api/v1/notifications/schedule — Schedule for future
POST /api/v1/notifications/batch — Batch send (max 100)
GET /api/v1/notifications/{id} — Get status
DELETE /api/v1/notifications/{id} — Cancel pending

Templates (X-Service-Key auth)

GET /api/v1/templates — List all
GET /api/v1/templates/{slug} — Get by slug
POST /api/v1/templates — Create
PUT /api/v1/templates/{slug} — Update
DELETE /api/v1/templates/{slug} — Delete
POST /api/v1/templates/{slug}/preview — Preview
POST /api/v1/templates/preview — Preview custom

Devices (JWT auth)

POST /api/v1/devices/register — Register push device
GET /api/v1/devices — List devices
DELETE /api/v1/devices/{id} — Unregister

Preferences (JWT auth)

GET /api/v1/preferences — Get preferences
PUT /api/v1/preferences — Update preferences

System

GET /health — Health check
GET /metrics — Prometheus metrics

Notification Channels

Channel	Service	Worker Concurrency	Max Retries
Email	Stalwart SMTP (self-hosted, see `docs/MAIL_SERVER.md`)	5	3
Push	Expo Push API	10	3
Matrix	Matrix Homeserver API	5	3
Webhook	HTTP callback	10	5

Commands

go run ./cmd/server          # Dev
go build -o bin/mana-notify ./cmd/server  # Build
go test ./...                # Test

Environment Variables

Variable	Default	Description
`PORT`	3040	Server port
`DATABASE_URL`	postgresql://...localhost:5432/mana_notify	PostgreSQL
`SERVICE_KEY`	dev-service-key	Service-to-service auth
`MANA_AUTH_URL`	http://localhost:3001	JWT validation
`SMTP_HOST`	stalwart	SMTP host (self-hosted Stalwart)
`SMTP_PORT`	587	SMTP port
`SMTP_USER`		SMTP username
`SMTP_PASSWORD`		SMTP password
`SMTP_FROM`	Mana noreply@mana.how	Default from
`EXPO_ACCESS_TOKEN`		Expo push token
`MATRIX_HOMESERVER_URL`		Matrix homeserver
`MATRIX_ACCESS_TOKEN`		Matrix bot token

2.6 KiB Raw Blame History