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

Matrix Planta Bot - Claude Code Guidelines

Overview

Matrix Planta Bot provides plant care management via Matrix chat. It integrates with the Planta backend for plant CRUD operations, watering schedules, watering history, and care settings.

Tech Stack

• Framework: NestJS 10
• Matrix: matrix-bot-sdk
• Backend: Planta API (port 3022)
• Auth: Mana Core Auth (JWT)

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-planta-bot/
├── src/
│   ├── main.ts               # Application entry point (port 3322)
│   ├── app.module.ts         # Root module
│   ├── health.controller.ts  # Health check endpoint
│   ├── config/
│   │   └── configuration.ts  # Configuration & help messages
│   ├── bot/
│   │   ├── bot.module.ts
│   │   └── matrix.service.ts # Matrix client & command handlers
│   ├── planta/
│   │   ├── planta.module.ts
│   │   └── planta.service.ts # Planta Backend API client
│   └── session/
│       ├── session.module.ts
│       └── session.service.ts  # User session & auth management
├── Dockerfile
└── package.json

Bot Commands

Command	Aliases	Description
!help	hilfe	Show help message
!login email pass	-	Login
!logout	-	Logout
!status	-	Bot status

Plant Management

Command	Aliases	Description
!pflanzen	plants, liste	List all plants
!pflanze [nr]	plant, details	Show plant details
!neu Name	new, add	Add new plant
!loeschen [nr]	delete, entfernen	Remove plant
!edit [nr] [feld] [wert]	bearbeiten	Edit plant field

Watering

Command	Aliases	Description
!giessen [nr]	water	Mark plant as watered
!giessen [nr] Notiz	-	Water with note
!faellig	due, upcoming	Show watering status
!historie [nr]	history, verlauf	Watering history
!intervall [nr] [tage]	interval, frequenz	Set watering interval

Editable Fields

Field	Aliases	Values
name	-	Any text
art	wissenschaftlich, scientific	Scientific name
licht	light	wenig/low, mittel/medium, hell/bright, direkt/direct
wasser	water	Number of days
feuchtigkeit	humidity	niedrig/low, mittel/medium, hoch/high
temperatur	temperature	Any text
erde	soil	Any text
notizen	notes	Any text

Example Usage

# Login
!login max@example.com mypassword

# Add a new plant
!neu Monstera Deliciosa

# Edit plant properties
!edit 1 licht hell
!edit 1 wasser 7
!edit 1 notizen Fensterbank Wohnzimmer

# Water a plant
!giessen 1
!giessen 1 Etwas Duenger hinzugefuegt

# Check watering status
!faellig

# View watering history
!historie 1

# Set watering interval
!intervall 1 5

Plant Health Status

Status	Emoji	Description
healthy	🌱	Plant is healthy
needs_attention	⚠️	Plant needs care
sick	🥀	Plant is sick

Environment Variables

# Server
PORT=3322

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

# Planta Backend
PLANTA_BACKEND_URL=http://localhost:3022
PLANTA_API_PREFIX=/api

# Mana Core Auth
MANA_CORE_AUTH_URL=http://localhost:3001

Docker

# Build locally
docker build -f services/matrix-planta-bot/Dockerfile -t matrix-planta-bot services/matrix-planta-bot

# Run
docker run -p 3322:3322 \
  -e MATRIX_HOMESERVER_URL=http://synapse:8008 \
  -e MATRIX_ACCESS_TOKEN=syt_xxx \
  -e PLANTA_BACKEND_URL=http://planta-backend:3022 \
  -e MANA_CORE_AUTH_URL=http://mana-core-auth:3001 \
  -v matrix-planta-bot-data:/app/data \
  matrix-planta-bot

Health Check

curl http://localhost:3322/health

Planta Backend API Endpoints Used

Endpoint	Method	Description
/health	GET	Health check
/api/plants	GET	List user's plants
/api/plants	POST	Create plant
/api/plants/:id	GET	Get plant details
/api/plants/:id	PUT	Update plant
/api/plants/:id	DELETE	Delete plant
/api/watering/upcoming	GET	Get upcoming waterings
/api/watering/:plantId/water	POST	Log watering
/api/watering/:plantId	PUT	Update watering schedule
/api/watering/:plantId/history	GET	Get watering history

Number-Based Reference System

The bot uses a number-based reference system for ease of use:

1. User runs !pflanzen or !faellig to get a list
2. Bot stores the list internally for the user
3. User can reference plants by their list number
4. Numbers are valid until the user runs a new list command

This allows simple commands like:

• !pflanze 3 - Show details for plant #3
• !giessen 1 - Water plant #1
• !edit 2 licht hell - Set light requirement for plant #2