210 lines
15 KiB
Markdown
210 lines
15 KiB
Markdown
# Surface Audit — Settings, Admin, Team Admin, Docs
|
|
|
|
## Audit Methodology
|
|
|
|
For each surface: read the index.js (tab/section structure), read every
|
|
section module, check the HTML template, trace the topbar/navigation
|
|
pattern, identify bugs, missing features, dead ends, and legacy baggage.
|
|
|
|
---
|
|
|
|
## 1. Settings Surface
|
|
|
|
**Files:** `src/js/sw/surfaces/settings/` (7 files, ~868 lines)
|
|
**Template:** `surfaces/settings.html` — mounts into `#settings-mount`
|
|
**Topbar:** Custom — back arrow + user icon + "Settings" title. No bell. No user menu.
|
|
|
|
### Sections
|
|
|
|
| Section | Lines | Status | Notes |
|
|
|---------|-------|--------|-------|
|
|
| General | 62 | ✅ OK | Default surface picker. Clean. |
|
|
| Appearance | 78 | ✅ OK | Theme toggle (light/dark/system) + UI scale slider. |
|
|
| Profile | 180 | ✅ OK | Display name, email, avatar upload, password change. |
|
|
| Teams | 47 | ⚠️ Thin | Read-only list of your teams. No actions. No link to team admin. |
|
|
| Connections | 222 | ✅ OK | Personal BYOK connection CRUD. Functional. |
|
|
| Notifications | 96 | ✅ OK | Toggle notification types on/off. |
|
|
|
|
### Issues Found
|
|
|
|
| # | Severity | Issue |
|
|
|---|----------|-------|
|
|
| S1 | **P1** | **No notification bell.** Custom topbar renders back arrow + icon + "Settings" — no bell, no user menu dropdown. User can't see notifications or navigate to other surfaces without using the back button. |
|
|
| S2 | **P2** | **Teams section is a dead-end.** Lists your teams with no actions — can't leave team, can't navigate to team admin, can't see team details. Just names. Should either link to team admin or show useful info. |
|
|
| S3 | **P2** | **Back button uses sessionStorage return URL.** `sb_settings_return` stash means: open settings in a new tab → back goes to `/` (correct). But open settings from a deep link → back goes to referrer, which might be unexpected. Shell topbar with consistent home link would fix this. |
|
|
| S4 | **P3** | **Extension config sections.** `__CONFIG_SECTIONS__` injection works but has no documentation. Extension authors don't know they can add settings sections. Needs a docs entry. |
|
|
|
|
### Shell Topbar Migration
|
|
|
|
Settings renders its own `settings-topbar`. With shell topbar injection:
|
|
- **Option A (simple):** `sw.shell.topbar.hide()` and keep custom topbar. Works immediately.
|
|
- **Option B (ideal):** Remove custom topbar. Shell topbar provides back + title + bell + user menu. Settings nav stays in the sidebar.
|
|
- **Recommendation:** Option B. Settings topbar adds nothing the shell topbar doesn't. The back arrow just navigates to `/`.
|
|
|
|
---
|
|
|
|
## 2. Admin Surface
|
|
|
|
**Files:** `src/js/sw/surfaces/admin/` (13 files, ~2,522 lines)
|
|
**Template:** `surfaces/admin.html` — mounts into `#admin-mount`
|
|
**Topbar:** Custom — favicon + "Administration" + category tabs (People/Workflows/System/Monitoring) + UserMenu component. No notification bell.
|
|
|
|
### Sections
|
|
|
|
| Section | Category | Lines | Status | Notes |
|
|
|---------|----------|-------|--------|-------|
|
|
| Users | People | 152 | ✅ OK | User list, create, edit status/role. Functional. |
|
|
| Teams | People | 178 | ✅ OK | Team list, create, member management. |
|
|
| Groups | People | 207 | ✅ OK | Full CRUD — create, delete, permission toggles, member add/remove. Functional but **undocumented** (see issues). |
|
|
| Workflows | Workflows | 163 | ⚠️ | CRUD + stage editor. `sw.api.workflows.list()` — needs same error-surfacing treatment as workflow-demo. |
|
|
| Settings | System | 242 | ✅ OK | Comprehensive: default surface, registration, banner, message bar, footer, session TTLs, vault, package registry, email test. Actually solid. |
|
|
| Storage | System | 76 | ✅ OK | Status cards, orphan cleanup. Clean. |
|
|
| Packages | System | 391 | ⚠️ | Core feature. Large. Package list, install, uninstall, registry browse. **User menu doesn't update after install/uninstall** (main bug Jeff reported). |
|
|
| Connections | System | 210 | ✅ OK | Global connection CRUD. |
|
|
| Broadcast | System | 44 | ✅ OK | Send broadcast. Minimal. |
|
|
| Backup | System | 162 | ✅ OK | Create/restore/download/delete. Works. |
|
|
| Health | Monitoring | 209 | ✅ OK | Runtime, DB pool, cluster, extension metrics. |
|
|
| Audit | Monitoring | 88 | ✅ OK | Audit log viewer with pagination. |
|
|
|
|
### Issues Found
|
|
|
|
| # | Severity | Issue |
|
|
|---|----------|-------|
|
|
| A1 | **P1** | **User menu not reactive to package changes.** `UserMenu` fetches surface list once on mount (`useEffect([authenticated])`). Installing/uninstalling a package doesn't trigger re-fetch. User must refresh the page to see new surfaces in the menu. Same for role changes (adding as team-admin). |
|
|
| A2 | **P1** | **No notification bell.** Admin topbar has category tabs + UserMenu but no NotificationBell component. |
|
|
| A3 | **P2** | **Groups: no documentation or inline help.** Admin Groups has full CRUD but zero explanation of what groups are, what permissions mean, or how the RBAC model works. "No groups" → user creates one → sees a list of permission slugs like `surface.admin.access` with no description. Every permission should have a human-readable description. |
|
|
| A4 | **P2** | **Workflows: silent error potential.** `sw.api.workflows.list()` — if this fails, `catch (e) { sw.toast(e.message, 'error'); }` fires a toast but leaves the list empty. Better than workflow-demo's silent swallow, but the toast disappears and the user is left with an empty list + no context. Should show inline error state. |
|
|
| A5 | **P2** | **Packages: no post-install feedback.** After installing a package, the package list refreshes (good) but the user menu doesn't update (bad — A1). User installs Notes, doesn't see it in the menu, thinks it's broken. |
|
|
| A6 | **P3** | **Admin topbar favicon is hardcoded.** Line 142: `<img src="${BASE}/favicon.svg">`. Should respect light/dark theme favicon swap. |
|
|
| A7 | **P3** | **Category icon rendering is fragile.** Custom compact SVG format (`C12 12 3\|M19.4 15...`) in `CatIcon`. Works but is unmaintainable — any icon change requires understanding the custom format. Should use standard SVG paths or lucide/feather icons. |
|
|
|
|
### Shell Topbar Migration
|
|
|
|
Admin has the most complex custom topbar — category tabs are genuinely useful navigation. Options:
|
|
- **Option A (recommended):** `sw.shell.topbar.hide()`. Admin keeps its custom topbar but adds NotificationBell component to its existing right-side area next to UserMenu.
|
|
- **Option B:** Shell topbar with `sw.shell.topbar.setSlot()` for category tabs. Works but requires rethinking the layout since shell topbar has fixed structure (home | title | slot | bell | user).
|
|
- **Recommendation:** Option A for v0.7.0. Admin's custom topbar is bespoke enough to warrant keeping. Just wire in the bell.
|
|
|
|
---
|
|
|
|
## 3. Team Admin Surface
|
|
|
|
**Files:** `src/js/sw/surfaces/team-admin/` (7 files, ~1,119 lines)
|
|
**Template:** `surfaces/team-admin.html` — mounts into `#team-admin-mount`
|
|
**Topbar:** Custom — back arrow + "Team Admin: {team name}" title. No bell. No user menu.
|
|
|
|
### Sections
|
|
|
|
| Section | Lines | Status | Notes |
|
|
|---------|-------|--------|-------|
|
|
| Members | ~90 | ✅ OK | Member list, add, remove. Functional. |
|
|
| Groups | 37 | ❌ Dead-end | Read-only "No groups" display. No create, no docs, no link to admin. |
|
|
| Connections | ~120 | ✅ OK | Team-scoped connections. Same pattern as user/admin connections. |
|
|
| Workflows | 723 | ⚠️ Massive | Three tabs: Workflows (CRUD + inline stage editor), Assignments (claim/release/complete), Monitor (active instances + signoff). This is 65% of the surface's code. |
|
|
| Settings | 72 | ✅ OK | Team name + description. Clean. |
|
|
| Activity | ~80 | ✅ OK | Audit log. Works. |
|
|
|
|
### Issues Found
|
|
|
|
| # | Severity | Issue |
|
|
|---|----------|-------|
|
|
| T1 | **P1** | **Groups is a dead-end.** 37 lines. Read-only list of team groups. No "Create Group" button. No explanation of what groups are. No link to Admin > Groups where creation actually happens. A team admin user who isn't a platform admin literally cannot create team groups. The Admin groups page supports `scope: team` but that creates a global group with team scope — it's unclear if team-admin should even see groups at all. |
|
|
| T2 | **P1** | **Workflows "Adopt Global" — same silent-error class.** `sw.api.teams.availableWorkflows(teamId)` — if this fails, the catch fires a toast but the adopt panel shows "No global workflows available" — indistinguishable from "there genuinely aren't any" vs "the API errored." |
|
|
| T3 | **P1** | **Workflows is disproportionately complex.** 723 lines — inline stage editor with mode/type selectors, SLA fields, stage reordering, team role assignment per stage. This is a full workflow designer embedded in a tab. It works but it's a maintenance burden and the UX is dense. Question: should this complexity live here or be a separate workflow-designer surface? |
|
|
| T4 | **P1** | **No notification bell.** Same as Settings — custom topbar with no bell. |
|
|
| T5 | **P2** | **No user menu.** Unlike Admin (which renders UserMenu), Team Admin has no user menu in its topbar. User can't navigate to other surfaces except via the back button. |
|
|
| T6 | **P2** | **Signoff panel shows raw user_id.** Line 714: `<span>${s.user_id}</span>` — shows UUID instead of display name. Should use `sw.users.displayName(s.user_id)`. |
|
|
| T7 | **P3** | **Back button uses sessionStorage.** Same pattern as Settings (`sb_team_admin_return`). Shell topbar would fix. |
|
|
|
|
### Shell Topbar Migration
|
|
|
|
Team Admin has a simple topbar (back + title). Direct replacement:
|
|
- Shell topbar provides: home link + "Team Admin: {name}" title + bell + user menu.
|
|
- Team name from `sw.api.teams.get(teamId)` → `sw.shell.topbar.setTitle('Team Admin: ' + team.name)`.
|
|
- Delete the custom topbar entirely.
|
|
|
|
---
|
|
|
|
## 4. Docs Surface
|
|
|
|
**Files:** `src/js/sw/surfaces/docs/` (1 file, 313 lines)
|
|
**Template:** `surfaces/docs.html` — mounts into `#docs-mount`
|
|
**Topbar:** Imports and renders `shell/topbar.js` (the SDK Topbar component). **Only surface that uses the shell Topbar.**
|
|
|
|
### Features
|
|
|
|
| Feature | Status | Notes |
|
|
|---------|--------|-------|
|
|
| Document list sidebar | ✅ OK | Fetches from `/api/v1/docs`, renders nav links. |
|
|
| Markdown rendering | ✅ OK | Uses `sw.markdown.renderSync()` + post-renderers (mermaid, katex). |
|
|
| Document outline | ✅ OK | Parses H1-H4 from markdown, renders table of contents. |
|
|
| Search | ✅ OK | Filters documents in sidebar. |
|
|
| URL updates | ✅ OK | `history.replaceState` on doc change. |
|
|
| Topbar | ✅ OK | Uses shell `Topbar` component — has title, bell, user menu. |
|
|
|
|
### Issues Found
|
|
|
|
| # | Severity | Issue |
|
|
|---|----------|-------|
|
|
| D1 | **P2** | **Stale content.** The docs themselves may be outdated — GETTING-STARTED, EXTENSION-GUIDE, API-REFERENCE, DEPLOYMENT, PACKAGE-FORMAT were written in v0.6.1. 18 versions later, some content is likely stale. Needs a content review pass. |
|
|
| D2 | **P3** | **No docs for RBAC/Groups.** Admin Groups exists with full CRUD but there's no documentation explaining the permission model, what each permission slug means, how groups interact with teams, or how the settings cascade works. This directly causes the "groups WTF" reaction. |
|
|
| D3 | **P3** | **No docs for Workflows.** The workflow engine is complex (multi-stage, team roles, signoff gates, SLA, public entry) but has no user-facing documentation. `DESIGN-WORKFLOWS.md` exists but is a design doc, not a user guide. |
|
|
| D4 | **P3** | **Shell topbar migration.** Docs already imports `shell/topbar.js` — when shell topbar injection lands, Docs will get a double topbar. Needs migration: delete the import, let shell topbar handle it. Docs currently passes no custom slot content, so it's a pure delete. |
|
|
|
|
---
|
|
|
|
## Cross-Surface Issues
|
|
|
|
These affect multiple or all surfaces:
|
|
|
|
| # | Severity | Issue | Surfaces |
|
|
|---|----------|-------|----------|
|
|
| X1 | **P0** | **User menu not reactive.** Package install/uninstall, role changes, team membership changes — none trigger a menu refresh. User must reload the page. | All (via UserMenu component) |
|
|
| X2 | **P1** | **No notification bell on 3/4 surfaces.** Only Docs has a bell (via Topbar import). Settings, Admin, and Team Admin all lack it. | Settings, Admin, Team Admin |
|
|
| X3 | **P1** | **No user menu on 2/4 surfaces.** Settings and Team Admin have no user menu at all. Admin and Docs have one. | Settings, Team Admin |
|
|
| X4 | **P2** | **Every surface has its own topbar.** Four different topbar implementations. None use the (not-yet-existing) shell topbar injection. Shell topbar (v0.7.0) eliminates this duplication. | All |
|
|
| X5 | **P2** | **Silent error swallowing.** Multiple sections use `catch (e) { toast }` which fires a toast and leaves an empty/stale UI. Toast disappears after seconds; user is left confused. Every list endpoint needs an inline error state with retry. | Admin Workflows, Team Admin Workflows, Packages |
|
|
| X6 | **P2** | **Empty states provide no guidance.** "No groups", "No workflows", "No notifications" — no explanation of what the feature is, why it's empty, or what action to take. Every empty state should have a one-line explanation and a primary action (create, link to docs, etc.). | Admin Groups, Team Admin Groups, Workflows |
|
|
| X7 | **P3** | **Raw IDs in UI.** Team Admin signoff panel shows `user_id` UUIDs. Any surface showing IDs should resolve via `sw.users.displayName()`. | Team Admin Workflows |
|
|
|
|
---
|
|
|
|
## Recommendations
|
|
|
|
### Immediate (fold into v0.7.0)
|
|
|
|
1. **User menu reactivity** — emit `package.changed` and `auth.changed` events over WS + local custom events. UserMenu listens and re-fetches surface list. This is the single most impactful fix.
|
|
|
|
2. **Shell topbar migration for Settings + Team Admin** — both have simple topbars that the shell topbar directly replaces. Docs deletes its Topbar import. Admin keeps its custom topbar but adds NotificationBell.
|
|
|
|
3. **Remove Team Admin Groups tab** — it's 37 lines of dead-end. Team-scoped group management should either (a) be added properly with create/edit/delete or (b) removed until it's properly designed. Showing "No groups" with no path forward is worse than not showing the tab.
|
|
|
|
4. **Error states** — replace `catch { toast }` with inline error + retry UI on every list endpoint. Systematic pass across all four surfaces.
|
|
|
|
5. **Empty state copy** — every "No X" message gets a one-line explanation + primary action button or doc link.
|
|
|
|
### Deferred (v0.7.1+ / runner coverage)
|
|
|
|
6. **Admin Groups documentation** — write a "Permissions & Groups" doc for the docs surface. Explain the RBAC model, list all permission slugs with descriptions, explain group scoping.
|
|
|
|
7. **Workflow user guide** — write a "Workflows" doc. Entry modes, stage types, team roles, signoff gates, SLA.
|
|
|
|
8. **Team Admin Workflows simplification** — the 723-line inline stage editor is the most complex piece of UI in the entire application. Consider extracting to a dedicated workflow-designer surface or at minimum breaking into separate files.
|
|
|
|
9. **Docs content refresh** — review all 5 docs for accuracy at v0.6.18+.
|
|
|
|
10. **Settings Teams section** — either add useful actions (link to team admin, show team role, leave team) or remove the tab.
|
|
|
|
---
|
|
|
|
## Asset Inventory
|
|
|
|
| Surface | Lines (total) | Sections | Custom Topbar | Bell | UserMenu | Error Handling |
|
|
|---------|--------------|----------|---------------|------|----------|---------------|
|
|
| Settings | 868 | 6 | Yes (back+icon) | ❌ | ❌ | Toast only |
|
|
| Admin | 2,522 | 12 | Yes (tabs+menu) | ❌ | ✅ | Toast only |
|
|
| Team Admin | 1,119 | 6 | Yes (back+title) | ❌ | ❌ | Toast only |
|
|
| Docs | 313 | 1 | Shell Topbar ✅ | ✅ | ✅ | Inline error ✅ |
|
|
|
|
Docs is the gold standard. The other three need to converge toward its pattern.
|