init codebase

2026-02-17 17:30:45 -05:00
parent a3b28549b4
commit f7e2755a91
175 changed files with 21600 additions and 232 deletions
@@ -314,7 +314,8 @@ All of these proxy to the API internally and return Datastar fragment responses.
 └──────────────────────────────────────┘
 ```

- Shown after first-ever OAuth login
+**Note:** The initial first-deployment setup wizard (configure OAuth providers, admin login, create first community) is handled entirely by Auth GW at `/setup/*` routes. The Web SM `/setup` page shown here is used for **subsequent** community creation by already-authenticated users (e.g., clicking `+` on the community strip).
+
 - Slug auto-generated from name (lowercase, hyphenated)
 - On submit: creates community + #general, redirects to /app

@@ -351,9 +352,142 @@ Web SM maintains per-user connection state:
 - Red dot if unread mentions exist
 - Community icon badge: sum of unread mentions across all channels in that community

-## 9. Test Cases
+## 9. Styling & CSS

-### 9.1 Page Rendering
+### 9.1 Approach
+
+**Tailwind CSS** via CDN (play CDN for dev, self-hosted build for prod).
+
+- All layout uses Tailwind utility classes in Hiccup
+- Custom CSS limited to: Datastar transition animations, syntax highlighting theme, spoiler reveal animation
+- Dark theme only for v1 (Discord-style dark background)
+- No CSS preprocessor — Tailwind utilities are sufficient
+
+### 9.2 Color Palette (Dark Theme)
+
+```
+Background:        #1e1e2e (base)
+Sidebar bg:        #181825 (darker)
+Message hover:     #2a2a3c
+Text primary:      #cdd6f4
+Text secondary:    #a6adc8
+Text muted:        #6c7086
+Accent:            #89b4fa (links, active channel)
+Mention highlight: #f38ba8 (pink, @mention background)
+Online dot:        #a6e3a1 (green)
+Unread badge:      #f38ba8 (red)
+Code bg:           #313244
+Input bg:          #313244
+Input border:      #45475a
+```
+
+### 9.3 Emoji Picker
+
+**Implementation:** Lightweight emoji picker rendered server-side as a Hiccup grid.
+
+```
+┌──────────────────────────────────┐
+│ 🔍 Search emoji...               │
+├──────────────────────────────────┤
+│ Frequently Used                  │
+│ 👍 ❤️ 😂 🎉 😮 😢 👀 🔥      │
+│                                  │
+│ Smileys & People                 │
+│ 😀 😃 😄 😁 😆 😅 🤣 😂      │
+│ 😊 😇 🙂 🙃 😉 😌 😍 🥰      │
+│ ...                              │
+├──────────────────────────────────┤
+│ 😀 👤 🐱 🍎 ⚽ 🚗 💡 🏳️       │  ← category tabs
+└──────────────────────────────────┘
+```
+
+- Triggered by clicking `+` on reaction bar or emoji button in input
+- Server renders emoji grid as Datastar fragment
+- Click emoji → POST to add reaction or insert into message input
+- Search filters emoji list (server-side filter, returns fragment)
+- Category tabs at bottom for quick navigation
+- "Frequently Used" based on user's recent emoji (stored in session state)
+
+### 9.4 Notification Toasts
+
+New notifications (beyond badge counts) show as brief toast popups:
+
+```
+┌──────────────────────────────────────┐
+│  @alice mentioned you in #backend    │  ← toast (top-right)
+│  "hey @bob can you review this?"     │
+│                                 ✕    │
+└──────────────────────────────────────┘
+```
+
+- Toasts appear for: @mentions, DMs, thread replies
+- Auto-dismiss after 5 seconds
+- Click toast → navigate to the message
+- Click ✕ → dismiss immediately
+- Max 3 toasts visible simultaneously (queue overflow)
+- Toasts rendered as Datastar fragments pushed via SSE
+
+## 10. Service Configuration
+
+### 10.1 Config Shape
+
+```clojure
+{:server {:host "0.0.0.0" :port 3002}
+ :api    {:base-url "http://localhost:3001"}
+ :nats   {:url "nats://localhost:4222"
+          :stream-name "ajet-events"}
+ :assets {:tailwind-cdn true            ;; false in prod (use built CSS)
+          :datastar-cdn true}           ;; false in prod (vendored)
+ :session {:max-connections 10000}      ;; max concurrent SSE connections
+ :ui     {:messages-per-page 50
+          :typing-timeout-sec 15
+          :toast-duration-sec 5}}
+```
+
+### 10.2 Startup / Shutdown Sequence
+
+**Startup:**
+```
+1. Load config
+2. Connect to NATS
+3. Initialize connection tracker (atom)
+4. Start http-kit server
+5. Log "Web SM started on port {port}"
+```
+
+**Shutdown (graceful):**
+```
+1. Stop accepting new SSE connections
+2. Send close event to all SSE clients
+3. Unsubscribe all NATS subscriptions
+4. Close NATS connection
+5. Stop http-kit server
+6. Log "Web SM stopped"
+```
+
+### 10.3 Health Check
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| GET | `/web/health` | None | Service health |
+
+```json
+{"status": "ok", "connections": 142, "checks": {"api": "ok", "nats": "ok"}}
+```
+
+### 10.4 Error Pages
+
+| Status | Page | Description |
+|--------|------|-------------|
+| 404 | Not Found | Unknown web route — shows "Page not found" with link to home |
+| 500 | Server Error | Unhandled exception — shows "Something went wrong" with retry link |
+| 502 | API Unavailable | API service unreachable — shows banner "Reconnecting..." with auto-retry |
+
+---
+
+## 11. Test Cases
+
+### 11.1 Page Rendering

 | ID | Test | Description |
 |----|------|-------------|
@@ -368,7 +502,7 @@ Web SM maintains per-user connection state:
 | WEB-T9 | Thread indicator | Messages with replies show reply count and link |
 | WEB-T10 | Setup wizard | GET /setup shows community creation form for first-time users |

-### 9.2 SSE & Real-Time
+### 11.2 SSE & Real-Time

 | ID | Test | Description |
 |----|------|-------------|
@@ -386,7 +520,7 @@ Web SM maintains per-user connection state:
 | WEB-T22 | Community switch | Switching community updates sidebar and message list |
 | WEB-T23 | Channel switch | Switching channel loads new messages, marks old as read |

-### 9.3 User Actions
+### 11.3 User Actions

 | ID | Test | Description |
 |----|------|-------------|
@@ -413,7 +547,7 @@ Web SM maintains per-user connection state:
 | WEB-T44 | Paginated loading | Scroll to "Load older" → click → older messages prepended |
 | WEB-T45 | Create community | Click + on community strip → wizard → community created |

-### 9.4 Profile & Settings
+### 11.4 Profile & Settings

 | ID | Test | Description |
 |----|------|-------------|
@@ -421,7 +555,7 @@ Web SM maintains per-user connection state:
 | WEB-T47 | Set status | Click own avatar → status input → save |
 | WEB-T48 | Set nickname | In community settings → nickname field → save |

-### 9.5 Error Handling
+### 11.5 Error Handling

 | ID | Test | Description |
 |----|------|-------------|
@@ -430,7 +564,7 @@ Web SM maintains per-user connection state:
 | WEB-T51 | Upload too large | Error shown, file not uploaded |
 | WEB-T52 | Rate limited | Error shown with retry countdown |

-### 9.6 Responsive / Layout
+### 11.6 Responsive / Layout

 | ID | Test | Description |
 |----|------|-------------|