mirror of
https://github.com/Memo-2023/mana-monorepo.git
synced 2026-05-17 18:49:39 +02:00
110 lines
2.7 KiB
Markdown
110 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
curl http://localhost:3312/health
|
|
```
|