till/managarten
1
0
Fork 0
mirror of https://github.com/Memo-2023/mana-monorepo.git synced 2026-05-16 03:19:40 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
managarten/services/matrix-stats-bot/CLAUDE.md
Till-JS b1eaa88e6e 📝 docs(stats-bot): add Redis and Matrix-SSO-Link environment variables 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-14 12:35:15 +01:00

2.7 KiB
Raw Blame History

Matrix Stats Bot - Claude Code Guidelines

Overview

Matrix Stats Bot delivers analytics from Umami (self-hosted) via Matrix. GDPR-compliant replacement for telegram-stats-bot.

Tech Stack

  • Framework: NestJS 10
  • Matrix: matrix-bot-sdk
  • Analytics: Umami API + Prometheus/VictoriaMetrics
  • Scheduling: @nestjs/schedule

Commands

pnpm install
pnpm start:dev        # Development with hot reload
pnpm build            # Production build
pnpm type-check       # TypeScript check

Matrix Commands

Personal Stats (auto-login via Matrix-SSO-Link)

Command Description
!stats Your personal statistics across all ManaCore apps
!status Account status and credit balance

Note: If you logged in via another Matrix bot or via OIDC, you're automatically authenticated.

Global Analytics (Umami)

Command Description
!global Overview of all apps (30 days)
!today Today's statistics
!week This week's statistics
!realtime Active visitors right now

Infrastructure (Prometheus)

Command Description
!system Mac Mini status (CPU, RAM, Disk, Uptime)
!services Backend service health (UP/DOWN)
!traffic HTTP traffic & latency per service
!db PostgreSQL & Redis status
!growth User growth statistics

Account

Command Description
!login email password Login with ManaCore credentials
!logout Logout from current session
!help Show available commands

Scheduled Reports

Report Schedule Timezone
Daily 09:00 Europe/Berlin
Weekly Monday 09:00 Europe/Berlin

Environment Variables

PORT=4012
TZ=Europe/Berlin

# Matrix
MATRIX_HOMESERVER_URL=http://localhost:8008
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_REPORT_ROOM_ID=!roomid:mana.how

# Redis (for session storage & Matrix-SSO-Link)
REDIS_HOST=redis
REDIS_PASSWORD=xxx

# Mana Core Auth (for Matrix-SSO-Link auto-login)
MANA_CORE_AUTH_URL=http://mana-auth:3001
MANA_CORE_SERVICE_KEY=xxx

# Umami
UMAMI_API_URL=http://umami:3000
UMAMI_USERNAME=admin
UMAMI_PASSWORD=xxx

# Prometheus / VictoriaMetrics
PROMETHEUS_URL=http://victoriametrics:9090

# Database (for user counts)
DATABASE_URL=postgresql://...

Authentication

The bot uses Matrix-SSO-Link for automatic authentication:

  • Sessions are stored in Redis (shared across all bots)
  • If a user logged in via another bot or OIDC, they're automatically authenticated
  • Manual login via !login email password creates a persistent link

Health Check

curl http://localhost:3312/health