init codebase

docs/prd/tui-sm.md

@@ -125,9 +125,75 @@ TUI SM buffers presence events to avoid flooding clients:
 - On flush: diff with previous state, send only changes
 - Typing indicators sent immediately (latency-sensitive)
 
-## 7. Test Cases
+## 7. Service Configuration
 
-### 7.1 SSE Connection
+### 7.1 Config Shape
+
+```clojure
+{:server {:host "0.0.0.0" :port 3003}
+ :api    {:base-url "http://localhost:3001"}
+ :nats   {:url "nats://localhost:4222"
+          :stream-name "ajet-events"}
+ :session {:max-connections 5000          ;; max concurrent SSE connections
+           :ping-interval-sec 30}
+ :presence {:batch-interval-sec 60}}
+```
+
+### 7.2 Startup / Shutdown Sequence
+
+**Startup:**
+```
+1. Load config
+2. Connect to NATS
+3. Initialize connection tracker (atom)
+4. Start http-kit server
+5. Start ping scheduler (30s interval)
+6. Log "TUI SM started on port {port}"
+```
+
+**Shutdown (graceful):**
+```
+1. Stop accepting new SSE connections
+2. Send close event to all connected TUI clients
+3. Stop ping scheduler
+4. Unsubscribe all NATS subscriptions
+5. Close NATS connection
+6. Stop http-kit server
+7. Log "TUI SM stopped"
+```
+
+### 7.3 Health Check
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/tui/health` | None | Service health |
+
+```json
+{"status": "ok", "connections": 23, "checks": {"api": "ok", "nats": "ok"}}
+```
+
+### 7.4 Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| API unavailable | Client signals (POST) return 502 JSON error. SSE stays open. |
+| NATS unavailable | SSE stays open, no real-time events. Events resume when NATS reconnects. Status event sent to client. |
+| Client sends invalid JSON | Return 400 with error description |
+| Client sends to unauthorized channel | Return 403 |
+| SSE write fails (dead connection) | Clean up connection state, unsubscribe NATS |
+| Max connections reached | Return 503 `{"error": "max connections reached, retry later"}` |
+
+### 7.5 Backpressure
+
+- If a client's SSE buffer exceeds 1000 events, disconnect the client (forces reconnect with replay)
+- Events are dropped (not queued) if write buffer is full — JetStream replay handles recovery
+- Connection tracking atom is bounded by `max-connections` config
+
+---
+
+## 8. Test Cases
+
+### 8.1 SSE Connection
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -138,7 +204,7 @@ TUI SM buffers presence events to avoid flooding clients:
 | TSM-T5 | Disconnect cleanup | SSE disconnect unsubscribes from NATS |
 | TSM-T6 | Reconnect with last_event_id | Missed events replayed via JetStream |
 
-### 7.2 Real-Time Events
+### 8.2 Real-Time Events
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -153,7 +219,7 @@ TUI SM buffers presence events to avoid flooding clients:
 | TSM-T15 | Notification event | User-targeted notification forwarded |
 | TSM-T16 | Unread count update | New message in other channel → unread count SSE event |
 
-### 7.3 Client Signals
+### 8.3 Client Signals
 
 | ID | Test | Description |
 |----|------|-------------|
@@ -166,7 +232,7 @@ TUI SM buffers presence events to avoid flooding clients:
 | TSM-T23 | Slash command | POST /tui/command → API command → result |
 | TSM-T24 | Heartbeat | POST /tui/heartbeat → proxied to API |
 
-### 7.4 Edge Cases
+### 8.4 Edge Cases
 
 | ID | Test | Description |
 |----|------|-------------|