Changeset 0.20.0 (#85)

docs/ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# Architecture — Chat Switchboard v0.17
+# Architecture — Chat Switchboard v0.20
 
 ## Deployment Modes
 
@@ -126,7 +126,7 @@ server/
 │       └── 002_v017_persona_kb.sql
 ├── store/
 │   ├── interfaces.go          # Store interfaces + shared types
-│   ├── postgres/              # Postgres implementations (20 stores)
+│   ├── postgres/              # Postgres implementations (22 stores)
 │   │   ├── stores.go          # NewStores() constructor
 │   │   ├── provider.go        # ProviderStore
 │   │   ├── catalog.go         # CatalogStore
@@ -140,7 +140,7 @@ server/
 │   │   ├── memory.go          # MemoryStore (CRUD + recall)
 │   │   ├── memory_hybrid.go   # RecallHybrid (pgvector cosine)
 │   │   └── ...
-│   └── sqlite/                # SQLite implementations (20 stores)
+│   └── sqlite/                # SQLite implementations (22 stores)
 │       ├── stores.go          # NewStores() constructor
 │       └── ...                # Mirror of postgres/ with dialect adaptations
 ├── models/models.go           # Shared domain types
@@ -154,6 +154,12 @@ server/
 ├── memory/                    # Long-term memory extraction + scanning
 │   ├── extractor.go           # Conversation analysis → fact extraction
 │   └── scanner.go             # Background job: find channels needing extraction
+├── mentions/                  # @mention parsing for multi-model routing
+│   └── parser.go              # Parse() extracts + resolves @mentions against roster
+├── notifications/             # Notification service + email transport
+│   ├── service.go             # Notify/NotifyMany, preference resolution, dispatch
+│   ├── email.go               # SMTP transport (TLS/STARTTLS, multipart MIME)
+│   └── templates.go           # HTML + plaintext email templates
 ├── handlers/                  # HTTP handlers (Gin)
 │   ├── auth.go                # Login, register, refresh, logout
 │   ├── admin.go               # User/config/model management
@@ -169,6 +175,10 @@ server/
 │   ├── knowledge.go           # Knowledge base management
 │   ├── memory.go              # Memory CRUD + review (user + admin)
 │   ├── memory_inject.go       # BuildMemoryHint() for completion injection
+│   ├── notifications.go       # Notification CRUD + preference endpoints
+│   ├── admin_email.go         # Admin SMTP test email endpoint
+│   ├── channel_models.go      # Channel model roster CRUD (multi-model)
+│   ├── model_prefs.go         # User model visibility preferences
 │   └── ...
 ├── notelinks/                 # Wikilink extraction (regex → NoteLink structs)
 ├── knowledge/                 # KB chunking, embedding, search
@@ -273,6 +283,45 @@ Migrations are handled by the backend on startup (no separate migration job):
 
 Postgres uses consolidated schemas (`001_v016_schema.sql` + incremental). SQLite uses application-generated UUIDs and `datetime()` instead of `gen_random_uuid()` and `now()`. Both drivers share the same migration tracking table.
 
+## Notifications (v0.20.0)
+
+Centralized notification infrastructure with real-time WebSocket delivery
+and optional email transport.
+
+**Service Pattern:** All notification sources go through `notifications.Service`,
+never insert directly. `Notify()` persists to store, checks user preferences,
+pushes via WebSocket (if online), and dispatches email (if configured and
+opted-in). `NotifyMany()` fans out to multiple users (best-effort).
+
+**Preference Resolution:**
+```
+Specific type pref → User wildcard '*' pref → System default (in_app=true, email=false)
+```
+
+**Email Transport:** Optional SMTP via `EmailTransport`. Supports implicit TLS
+(port 465) and STARTTLS (port 587). Multipart MIME (HTML + plaintext).
+Templates rendered via Go `html/template` with instance branding. Async
+delivery via goroutine (failures logged, never block notification creation).
+Admin configures SMTP in platform settings; users toggle per-type delivery
+in Settings → Notifications.
+
+**Cleanup:** Background goroutine deletes notifications older than retention
+period (default 90 days, configurable via admin settings).
+
+## @mention Routing + Multi-model (v0.20.0)
+
+Channels support multiple AI models. The `channel_models` table (schema 001)
+holds the roster; `mentions.Parse()` extracts @mentions from message content
+and resolves against display names (case-insensitive, longest-match-first).
+
+**Completion Fan-out:** When mentions resolve to channel models, the completion
+handler fires sequentially for each target, producing one assistant message
+per model. Without @mention, the default channel model responds (backward
+compatible). Frontend renders model attribution labels on multi-model responses.
+
+**Autocomplete:** CM6 `mentionCompletion` extension triggers on `@` in the
+chat input, showing a dropdown of channel model display names.
+
 ## Frontend Architecture
 
 Vanilla JavaScript, no framework. The frontend ships as static files served by nginx. The only build step is the CM6 editor bundle, compiled at Docker build time via esbuild (IIFE output, no runtime bundler).