managarten/services/matrix-onboarding-bot/CLAUDE.md

Matrix Onboarding Bot - Claude Code Guidelines

Overview

Matrix Onboarding Bot guides new users through a profile setup process. It collects display name, interests, and language preference, storing them in mana-core-auth's globalSettings.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk via @manacore/matrix-bot-common
• Auth: mana-core-auth (Settings API)
• Sessions: Redis via @manacore/bot-services

Commands

# Development
pnpm install
pnpm start:dev        # Start with hot reload

# Build
pnpm build            # Production build

# Type check
pnpm type-check       # Check TypeScript types

Project Structure

services/matrix-onboarding-bot/
├── src/
│   ├── main.ts               # Application entry point (port 4020)
│   ├── app.module.ts         # Root module
│   ├── config/
│   │   └── configuration.ts  # Configuration & messages (de/en)
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── matrix.service.ts # Matrix client & command handlers
│   └── onboarding/
│       ├── onboarding.module.ts
│       ├── onboarding.service.ts  # API client for mana-core-auth
│       └── state-machine.ts       # Onboarding flow state machine
├── Dockerfile
└── package.json

Bot Commands

Command	Description
!start	Start onboarding (or restart if completed)
!profile	Show current profile
!edit name Max	Change display name
!edit interests KI, Musik	Change interests
!edit language de	Change language (de/en)
!skip	Skip current question (if allowed)
!cancel	Cancel onboarding
!help	Show help text

Onboarding Flow

IDLE → NAME → INTERESTS → LANGUAGE → SUMMARY → COMPLETED
               ↓           ↓
             SKIP        SKIP

1. NAME (required): Ask for display name
2. INTERESTS (skippable): Ask for interests (comma-separated)
3. LANGUAGE (skippable): Ask for language preference (de/en)
4. SUMMARY: Show profile and ask for confirmation
5. COMPLETED: Save to mana-core-auth and finish

Data Storage

Profile data is stored in mana-core-auth's user_settings.globalSettings:

interface GlobalSettings {
  // ... existing fields
  displayName?: string;       // From onboarding
  interests?: string[];       // From onboarding
  onboardingCompleted?: boolean;
}

Environment Variables

# Server
PORT=4020

# Matrix
MATRIX_HOMESERVER_URL=http://localhost:8008
MATRIX_ACCESS_TOKEN=syt_xxx
MATRIX_ALLOWED_ROOMS=#onboarding:matrix.mana.how
MATRIX_STORAGE_PATH=./data/bot-storage.json

# mana-core-auth
MANA_CORE_AUTH_URL=http://localhost:3001
MANA_CORE_SERVICE_KEY=your-service-key

# Redis (for session storage)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=redis123

API Endpoints Used

Endpoint	Method	Description
/api/v1/settings	GET	Get user settings
/api/v1/settings/global	PATCH	Update global settings

Docker

# Build
docker build -f services/matrix-onboarding-bot/Dockerfile -t matrix-onboarding-bot .

# Run
docker run -p 4020:4020 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e MANA_CORE_AUTH_URL=http://mana-auth:3001 \
  -e REDIS_HOST=redis \
  -v matrix-bots-data:/app/data \
  matrix-onboarding-bot

Health Check

curl http://localhost:4020/health

Authentication

The bot requires users to be logged in via Matrix-SSO-Link (shared Redis session).

1. User logs in via Matrix SSO link in another bot or web app
2. Session stored in Redis with Matrix user ID as key
3. Onboarding bot retrieves token from Redis
4. Token used to call mana-core-auth Settings API

Example Dialog

Bot: Willkommen beim Onboarding!

     Ich helfe dir, dein Profil einzurichten.
     Wie mochtest du genannt werden?

User: Max

Bot: Hallo Max! Was sind deine Interessen?
     (z.B. Programmierung, Musik - durch Komma getrennt)
     Sag `!skip` zum Uberspringen.

User: KI, Gaming, Musik

Bot: Welche Sprache bevorzugst du?
     Antworte mit `de` fur Deutsch oder `en` fur Englisch.

User: de

Bot: **Dein Profil:**
     - Name: Max
     - Interessen: KI, Gaming, Musik
     - Sprache: Deutsch

     Ist das korrekt? (ja/nein)

User: ja

Bot: Perfekt! Dein Profil ist eingerichtet.
     Du kannst es jederzeit mit `!profile` anzeigen oder mit `!edit` andern.

Localization

The bot supports German (de) and English (en). Messages are defined in src/config/configuration.ts under the MESSAGES object.

State Machine

The OnboardingStateMachine class in src/onboarding/state-machine.ts is a pure function that:

• Takes current state + action
• Returns new state + message key
• Has no side effects

This makes it easy to test and reason about the flow.