# 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.18) |
| `CHANGELOG.md` | All versions from v0.1.0 to v0.1.18 |
| `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