diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..c8cf005 --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,233 @@ +# PRD: Mosaic Stack Dashboard & Platform Implementation + +## Metadata + +- Owner: Jason Woltje +- Date: 2026-02-22 +- Status: in-progress +- Best-Guess Mode: true + +## Problem Statement + +The Mosaic Stack web UI has a basic navigation and simple widget-based dashboard that doesn't match the production-ready design vision. The reference design (dashboard.html) defines a comprehensive command center UI with sidebar navigation, topbar, terminal panel, and multiple page layouts. The current implementation uses mismatched design tokens (raw Tailwind colors vs CSS variables), has no collapsible sidebar, no global terminal, and lacks the polished design system from the reference. + +## Objectives + +1. Implement the dashboard.html reference design as the production UI foundation +2. Establish a consistent CSS design token system that supports multiple themes +3. Build a responsive, accessible app shell with collapsible sidebar and full-width header +4. Create a theme system supporting installable theme packages +5. Build all dashboard pages (Dashboard, Projects, Workspace, Kanban, Files, Logs, Settings, Profile) +6. Implement real backend integration (no mock data) +7. Support multi-tenant configuration with RBAC +8. Implement federation (master-master and master-slave) +9. Build global terminal, project chat, and master chat session +10. Configure telemetry with opt-out support + +## Scope + +### In Scope (Milestone 0.0.15 — Dashboard Shell & Design System) + +1. CSS design token system overhaul (colors, fonts, spacing, radii from dashboard.html) +2. App shell layout: sidebar + full-width header + main content area +3. Full-width header with logo, search, system status, terminal toggle, notifications, theme toggle, user avatar dropdown +4. Collapsible sidebar with nav groups, icons, badges, active states, collapse/expand button +5. Responsive layout with hamburger button at small breakpoints, sidebar hidden by default at mobile +6. Light/dark theme matching the reference design +7. Mosaic logo icon as global loading spinner +8. Shared component updates in packages/ui (Card, Badge, Button, Dot, MetricsStrip, ProgressBar, FilterTabs, SectionHeader, Table, LogLine, Terminal panel) +9. Dashboard page: metrics strip, active orchestrator sessions, quick actions, activity feed, token budget +10. Grain overlay texture from reference design + +### In Scope (Future Milestones — Documented for Planning) + +11. Additional pages: Projects, Workspace, Kanban, File Manager, Logs & Telemetry, Settings, Profile +12. Theme system with installable theme packages +13. Widget system with installable widget packages, customizable sizes +14. Global terminal (project/orchestrator level, smart) +15. Project-level orchestrator chat +16. Master chat session (collapsible sidebar/slideout, always available) +17. Settings page for ALL environment variables, dynamically configurable via webUI +18. Multi-tenant configuration with admin user management +19. Team management with shared data spaces and chat rooms +20. RBAC for file access, resources, models +21. Federation: master-master and master-slave with key exchange +22. Federation testing: 3 instances on Coolify (woltje.com domain) +23. Agent task mapping configuration (system-level defaults, user-level overrides) +24. Telemetry: opt-out, customizable endpoint, sanitized data +25. File manager with WYSIWYG editing (system/user/project levels) +26. User-level and project-level Kanban with filtering +27. Break-glass authentication user +28. Playwright E2E tests for all pages +29. API documentation via Swagger +30. Backend endpoints for all dashboard data + +### Out of Scope + +1. Mobile native app +2. Third-party marketplace for themes/widgets (initial implementation is local package management only) +3. Production deployment to non-Coolify targets +4. Calendar system redesign (existing calendar implementation is retained) + +## User/Stakeholder Requirements + +1. The `jarvis` user must be able to log into mosaic.woltje.com via Authentik as administrator with access to all pages +2. A standard `jarvis-user` must operate at a lower permission level +3. A break-glass user must have access without Authentik authentication +4. All pages must be navigable without errors +5. Light and dark themes must work across all pages and components +6. Sidebar must be collapsible with open/close button; hidden by default at small breakpoints +7. Hamburger button visible at lower breakpoints for sidebar control +8. The Mosaic Stack logo icon must be the site-wide loading spinner +9. No mock data — all data pulled from backend APIs + +## Functional Requirements + +### FR-001: Design Token System + +- CSS custom properties for all colors, spacing, typography, radii +- Dark theme as default (`:root`), light theme via `[data-theme="light"]` +- Fonts: Outfit (body), Fira Code (monospace) +- All components must use design tokens, never hardcoded colors + +### FR-002: App Shell Layout + +- CSS Grid: sidebar column + header row + main content +- Full-width header spanning above sidebar and content +- ASSUMPTION: Header spans full width including above sidebar area. The logo is in the header, not the sidebar. Rationale: User explicitly stated "The logo will NOT be part of the sidebar." + +### FR-003: Sidebar Navigation + +- Nav groups: Overview (Dashboard), Workspace (Projects, Project Workspace, Kanban, File Manager), Operations (Logs & Telemetry, Terminal), System (Settings) +- Collapsible: icon-only mode when collapsed +- Active state indicator (left border accent) +- User card in footer with avatar, name, role, online status +- ASSUMPTION: Sidebar footer user card navigates to Profile page. Rationale: Matches reference design behavior. + +### FR-004: Header/Topbar + +- Logo + brand wordmark (left) +- Search bar with keyboard shortcut hint +- System status indicator +- Terminal toggle button +- Notification bell with badge +- Theme toggle (sun/moon icon) +- User avatar button with dropdown (Profile, Account Settings, Sign Out) + +### FR-005: Responsive Design + +- Breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px) +- Below md: sidebar hidden, hamburger button in header +- md-lg: sidebar can be toggled +- lg+: sidebar visible by default + +### FR-006: Dashboard Page + +- 6-cell metrics strip with colored top borders and trend indicators +- Active Orchestrator Sessions card with agent nodes +- Quick Actions 2x2 grid +- Activity Feed sidebar card +- Token Budget sidebar card with progress bars + +### FR-007: Loading Spinner + +- Mosaic logo icon (4 corner squares + center circle) with CSS rotation animation +- Used as global loading indicator across all pages +- Available as a shared component + +### FR-008: Theme System (Future Milestone) + +- Support multiple themes beyond default dark/light +- Themes are installable packages from Mosaic Stack repo +- Theme installation and selection from Settings page +- ASSUMPTION: Initial implementation supports dark/light from reference design. Multi-theme package system is a future milestone. Rationale: Foundation must be solid before extensibility. + +### FR-009: Terminal Panel (Future Milestone) + +- Bottom drawer panel, toggleable from header and sidebar +- Multiple tabs (Orchestrator, Shell, Build) +- Smart terminal operating at project/orchestrator level +- Global terminal for system interaction + +### FR-010: Settings Page (Future Milestone) + +- All environment variables configurable via UI +- Minimal launch env vars, rest configurable dynamically +- Settings stored in DB with RLS +- Theme selection, widget management, federation config, telemetry config + +## Non-Functional Requirements + +1. Security: All API endpoints require authentication. RBAC enforced. No PII in telemetry. Secrets never hardcoded. +2. Performance: Dashboard loads in <2s. No layout shift during theme toggle. Sidebar toggle is instant (<100ms animation). +3. Reliability: Break-glass auth ensures access when Authentik is down. +4. Observability: Telemetry with opt-out support. Wide-event logging. Customizable telemetry endpoint. + +## Acceptance Criteria + +### Milestone 0.0.15 + +1. Design tokens from dashboard.html are implemented in globals.css +2. App shell shows full-width header with logo, collapsible sidebar, main content area +3. Sidebar has all nav groups with icons, collapses to icon-only mode +4. Hamburger button appears at mobile breakpoints, sidebar hidden by default +5. Light/dark theme toggle works across all components +6. Mosaic logo spinner is used as site-wide loading indicator +7. Dashboard page shows metrics strip, orchestrator sessions, quick actions, activity feed, token budget +8. All shared components in packages/ui use design tokens (no hardcoded colors) +9. Lint, typecheck, and existing tests pass +10. Grain overlay texture from reference is applied + +### Full Project (All Milestones) + +11. jarvis user logs in via Authentik, has admin access to all pages +12. jarvis-user has standard access at lower permission level +13. Break-glass user has access without Authentik +14. Three Mosaic Stack instances on Coolify with federation testing +15. Playwright tests confirm all pages, functions, theming work +16. No errors during site navigation +17. API documented via Swagger with proper auth gating +18. Telemetry working locally with wide-event logging +19. Mosaic Telemetry properly reporting to telemetry endpoint + +## Constraints and Dependencies + +1. Next.js 16 with App Router — all pages use server/client component patterns +2. Tailwind CSS 3.4 — design tokens must integrate with Tailwind's utility class system +3. BetterAuth for authentication — must maintain existing auth flow +4. Authentik as IdP at auth.diversecanvas.com — must remain operational +5. PostgreSQL 17 with Prisma — all settings stored in DB +6. Coolify for deployment — 3 instances needed for federation testing +7. packages/ui is shared across apps — changes affect all consumers + +## Risks and Open Questions + +1. **Risk**: Changing globals.css design tokens may break existing pages (login, knowledge, calendar). Mitigation: Thorough regression testing. +2. **Risk**: packages/ui uses hardcoded Tailwind colors — migration to CSS variables needs care. Mitigation: Phase the migration, test each component. +3. **Open**: Exact federation protocol details for master-master vs master-slave data sync. +4. **Open**: Specific telemetry data points to collect. +5. **Open**: Agent task mapping configuration schema (informed by OpenClaw research). + +## Testing and Verification + +1. Baseline: `pnpm lint && pnpm build` must pass +2. Situational: Visual verification at sm/md/lg/xl breakpoints +3. Situational: Theme toggle across all pages +4. Situational: Sidebar collapse/expand at all breakpoints +5. E2E: Playwright tests for all page navigation +6. E2E: Auth flow with Authentik +7. Federation: Master-master and master-slave data access tests + +## Delivery/Milestone Intent + +| Milestone | Version | Focus | +| ----------------------- | ------- | ----------------------------------------------------------------- | +| MS15-DashboardShell | 0.0.15 | Design system + app shell + dashboard page | +| MS16-Pages | 0.0.16 | Projects, Workspace, Kanban, Settings, Profile, Files, Logs pages | +| MS17-BackendIntegration | 0.0.17 | API endpoints, real data, Swagger docs | +| MS18-ThemeWidgets | 0.0.18 | Theme package system, widget registry, dashboard customization | +| MS19-ChatTerminal | 0.0.19 | Global terminal, project chat, master chat session | +| MS20-MultiTenant | 0.0.20 | Multi-tenant, teams, RBAC, RLS enforcement, break-glass auth | +| MS21-Federation | 0.0.21 | Federation (M-M, M-S), 3 instances, key exchange, data separation | +| MS22-AgentTelemetry | 0.0.22 | Agent task mapping, telemetry, wide-event logging | +| MS23-Testing | 0.0.23 | Playwright E2E, federation tests, documentation finalization | diff --git a/docs/scratchpads/ms15-dashboard-shell.md b/docs/scratchpads/ms15-dashboard-shell.md new file mode 100644 index 0000000..1b343a0 --- /dev/null +++ b/docs/scratchpads/ms15-dashboard-shell.md @@ -0,0 +1,63 @@ +# MS15 — Dashboard Shell & Design System + +## Objective + +Implement the dashboard.html reference design across the Mosaic Stack web app. Establish the design token system, app shell layout, shared components, and dashboard page. + +## Design Reference + +`/home/jwoltje/src/mosaic-stack-website/docs/designs/round-5/claude/01/dashboard.html` + +## Key Architectural Decisions + +1. **Theme approach**: CSS custom properties via `:root` + `[data-theme="light"]`. Tailwind configured to use these variables. ThemeProvider updated to set `data-theme` attribute on ``. +2. **Logo placement**: Logo in full-width header (topbar), NOT in sidebar. User spec overrides reference design. +3. **Sidebar collapse**: Collapsible with icon-only mode. Hidden by default at mobile breakpoints. Hamburger button for small screens. +4. **Fonts**: Outfit (body) + Fira Code (mono). Loaded via `next/font/google`. +5. **Loading spinner**: Mosaic logo icon component with CSS rotation animation. +6. **Grain overlay**: Subtle noise texture via CSS pseudo-element, same as reference. +7. **Per-phase branches**: `feat/ms15-design-system`, `feat/ms15-shared-components`, `feat/ms15-dashboard-page`. + +## Phases + +### Phase 1: Foundation (Design System & App Shell) + +- MS15-FE-001: Design token system overhaul +- MS15-FE-002: App shell grid layout +- MS15-FE-003: Sidebar component +- MS15-FE-004: Topbar/Header component +- MS15-FE-005: Responsive breakpoints +- MS15-FE-006: Loading spinner (Mosaic logo) + +### Phase 2: Shared Components + +- MS15-UI-001: packages/ui token alignment +- MS15-UI-002: Card, Badge, Button, Dot updates +- MS15-UI-003: MetricsStrip, ProgressBar, FilterTabs +- MS15-UI-004: SectionHeader, Table, LogLine +- MS15-UI-005: Terminal panel component + +### Phase 3: Dashboard Page + +- MS15-DASH-001: Metrics strip +- MS15-DASH-002: Active Orchestrator Sessions +- MS15-DASH-003: Quick Actions +- MS15-DASH-004: Activity Feed +- MS15-DASH-005: Token Budget + +### Phase 4: Quality + +- MS15-QA-001: Baseline tests +- MS15-QA-002: Situational tests +- MS15-DOC-001: Documentation + +## Progress Log + +- Session started: 2026-02-22 +- Status: Bootstrap phase + +## Risks + +- Large surface area: globals.css change affects all existing pages +- packages/ui color system mismatch requires careful migration +- Existing pages (login, auth) may need adjustment after token changes diff --git a/docs/tasks.md b/docs/tasks.md index 3026d4f..f09f6b1 100644 --- a/docs/tasks.md +++ b/docs/tasks.md @@ -1,5 +1,36 @@ # Tasks +## MS15-DashboardShell (0.0.15) — Dashboard Shell & Design System + +**Orchestrator:** Claude Code (Opus 4.6) +**Started:** 2026-02-22 +**Branch:** feat/ms15-design-system (Phase 1), feat/ms15-shared-components (Phase 2), feat/ms15-dashboard-page (Phase 3) +**Milestone:** MS15-DashboardShell (0.0.15) +**PRD:** docs/PRD.md + +| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes | +| ------------- | ----------- | -------------------------------------------------------------------------------------------- | ----- | ---- | --------------------------- | ----------------------- | ----------------------------------------------- | ----- | ---------- | ------------ | -------- | ---- | ----- | +| MS15-FE-001 | not-started | Design token system overhaul (globals.css → dashboard.html tokens, dark/light, fonts) | #448 | web | feat/ms15-design-system | | MS15-FE-002,MS15-FE-003,MS15-FE-004,MS15-UI-001 | | | | 25K | | | +| MS15-FE-002 | not-started | App shell grid layout (sidebar + full-width header + main content) | #448 | web | feat/ms15-design-system | MS15-FE-001 | MS15-FE-003,MS15-FE-004,MS15-FE-005 | | | | 20K | | | +| MS15-FE-003 | not-started | Sidebar component (collapsible, nav groups, icons, badges, user card footer) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | | | | 25K | | | +| MS15-FE-004 | not-started | Topbar/Header component (logo, search, status, notifications, theme toggle, avatar dropdown) | #448 | web | feat/ms15-design-system | MS15-FE-002 | MS15-FE-005 | | | | 25K | | | +| MS15-FE-005 | not-started | Responsive layout (breakpoints, hamburger, sidebar auto-hide at mobile) | #448 | web | feat/ms15-design-system | MS15-FE-003,MS15-FE-004 | MS15-QA-001 | | | | 20K | | | +| MS15-FE-006 | not-started | Loading spinner (Mosaic logo icon with rotation animation, site-wide) | #448 | web | feat/ms15-design-system | MS15-FE-001 | | | | | 10K | | | +| MS15-UI-001 | not-started | Align packages/ui tokens with new CSS variable design system | #449 | ui | feat/ms15-shared-components | MS15-FE-001 | MS15-UI-002,MS15-UI-003,MS15-UI-004 | | | | 20K | | | +| MS15-UI-002 | not-started | Update Card, Badge, Button, Dot component variants to match reference | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | | | | 25K | | | +| MS15-UI-003 | not-started | Create MetricsStrip, ProgressBar, FilterTabs shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-001 | | | | 20K | | | +| MS15-UI-004 | not-started | Create SectionHeader, Table, LogLine shared components | #449 | ui | feat/ms15-shared-components | MS15-UI-001 | MS15-DASH-002 | | | | 15K | | | +| MS15-UI-005 | not-started | Create Terminal panel component (bottom drawer, tabs, output) | #449 | web | feat/ms15-shared-components | MS15-UI-001 | | | | | 20K | | | +| MS15-DASH-001 | not-started | Dashboard metrics strip (6 cells, colored borders, values, trends) | #450 | web | feat/ms15-dashboard-page | MS15-UI-002,MS15-UI-003 | | | | | 15K | | | +| MS15-DASH-002 | not-started | Active Orchestrator Sessions card with agent nodes | #450 | web | feat/ms15-dashboard-page | MS15-UI-004 | | | | | 20K | | | +| MS15-DASH-003 | not-started | Quick Actions 2x2 grid | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | | | | 10K | | | +| MS15-DASH-004 | not-started | Activity Feed sidebar card | #450 | web | feat/ms15-dashboard-page | MS15-UI-002 | | | | | 15K | | | +| MS15-DASH-005 | not-started | Token Budget sidebar card with progress bars | #450 | web | feat/ms15-dashboard-page | MS15-UI-003 | | | | | 10K | | | +| MS15-QA-001 | not-started | Baseline tests (lint, typecheck, build) and situational tests (responsive, themes) | #448 | web | feat/ms15-design-system | MS15-FE-005 | | | | | 15K | | | +| MS15-DOC-001 | not-started | Documentation: design system reference, component docs | #448 | docs | feat/ms15-design-system | MS15-QA-001 | | | | | 10K | | | + +--- + ## M10-Telemetry (0.0.10) — Telemetry Integration **Orchestrator:** Claude Code