mattermore/docs/PROJECT.md

Project: Matty

Purpose

Matty is a Mattermost (Community Edition) plugin that connects chat to remote LLMs via Ollama. Users address the bot by @-mentioning it in any channel (e.g. @matty write a poem). The bot responds only when addressed and disengages naturally. Follow-up messages continue the conversation without re-@mentioning while the session is active.

Structure

mattermore/
├── plugin.json              — Mattermost plugin manifest (v0.1.x)
├── Makefile                 — Build, lint, dist targets
├── .golangci.yml            — Linter configuration
├── CHANGELOG.md             — Per-release changelog
├── README.md                — User-facing docs
├── DESIGN.md                — Functional design document
├── DECISIONS.md             — Design rationale log
├── PROJECT.md               — This file
├── .gitignore               — Go + plugin ignores
├── dev/
│   ├── docker-compose.yml   — Local Mattermost + PostgreSQL test rig
│   └── init.sh              — Admin auto-creation script
├── server/
│   ├── main.go              — plugin.ClientMain entry point
│   ├── plugin.go            — Plugin struct with all fields
│   ├── hooks.go             — OnActivate, MessageHasBeenPosted, streaming
│   ├── command.go           — /ai and subcommands, persona override
│   ├── configuration.go     — Config struct, validation, OnConfigurationChange
│   ├── ollama.go            — OllamaClient (streaming + blocking chat)
│   ├── store.go             — ConversationStore (KV-backed context)
│   ├── rate.go              — RateLimiter (per-user token bucket)
│   ├── engagement.go        — EngagementEngine (sleep/active states)
│   └── persona.go           — PersonaLibrary with 19 personas
└── dist/
    └── com.forkless.mattermore-*.tar.gz

Key Files

Path	Purpose
plugin.json	Manifest with 12 configurable settings
server/hooks.go	Core interaction logic (@-mention detection, streaming)
server/command.go	/ai and /ai persona commands
server/ollama.go	HTTP client for Ollama REST API
server/store.go	Context persistence via Mattermost KV store
server/engagement.go	Active session tracking (5-min timeout)
server/persona.go	19 personas with stable short IDs
server/configuration.go	12 settings, validation, debug logging
DESIGN.md	Full functional design (up to date with v0.1.17)
CHANGELOG.md	All versions from v0.1.0 to v0.1.17
dev/docker-compose.yml	Disposable Mattermost + PostgreSQL test rig

External Dependencies

• Go ≥ 1.21 (toolchain)
• Mattermost Server ≥ v11.6 (plugin API)
• Ollama (remote inference server, any version)
• Go modules (see go.mod):
  • github.com/mattermost/mattermost/server/public — Plugin SDK

Release Cadence

• Tags: v0.x.y
• Built manually via make dist, uploaded via System Console
• No CI/CD pipeline yet

Documentation

• docs/DESIGN.md — full functional design with architecture, interaction model
• docs/DECISIONS.md — why key decisions were made
• CHANGELOG.md — per-version changelog (17 releases)
• README.md — quick start, config reference, build instructions