chore: add plan files and gitignore for MVP feature

2026-03-24 19:46:26 +03:00
parent 6d415ac97d
commit dc9bd3bba4
11 changed files with 676 additions and 0 deletions
@@ -0,0 +1,41 @@
+# Dependencies
+node_modules/
+
+# Build output
+build/
+.svelte-kit/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Database
+data/
+*.db
+*.db-journal
+
+# Uploads
+static/uploads/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/
+
+# Prisma
+prisma/migrations/*.db
+
+# Test coverage
+coverage/
+
+# Logs
+*.log
@@ -0,0 +1,23 @@
+# Feature Context: Web App Launcher — MVP
+
+## Current State
+Fresh repository — no code yet. Only PLAN_PROMPT.md and .gitignore exist.
+
+## Temporary Workarounds
+- None yet
+
+## Cross-Phase Dependencies
+- Phase 2 depends on Phase 1 (project scaffolding, Prisma setup)
+- Phase 3 depends on Phase 2 (user/group models, auth service)
+- Phase 4 depends on Phase 2 (app model, services layer)
+- Phase 5 depends on Phase 2 (board/section/widget models) and Phase 4 (app widget references apps)
+- Phase 6 depends on Phases 3-5 (admin needs auth, app, board entities)
+- Phase 7 depends on Phase 1 (Tailwind, shadcn-svelte) and Phase 5 (board layout to polish)
+- Phase 8 depends on all prior phases
+
+## Implementation Notes
+- Big Bang strategy: intermediate phases may not build/pass tests. Only Phase 8 must result in a fully working build.
+- SQLite with Prisma — single file DB at `data/launcher.db`
+- All env config via environment variables; `.env.example` provided as template
+- Svelte 5 runes mode: use `$state`, `$derived`, `$effect` — NOT legacy stores for component state
+- shadcn-svelte uses Bits UI primitives — each component is a local file, not a library import
@@ -0,0 +1,56 @@
+# Feature: Web App Launcher — MVP
+
+**Branch:** `feature/mvp-web-app-launcher`
+**Base branch:** `master`
+**Created:** 2026-03-24
+**Status:** 🟡 In Progress
+**Strategy:** Big Bang
+**Mode:** Automated
+**Execution:** Orchestrator
+
+## Summary
+Build a self-hosted web application launcher/dashboard for a TrueNAS server environment. The MVP includes local auth + guest mode, app CRUD with healthchecks, a single default board with sections and app widgets, an admin panel, dark theme with ambient backgrounds, and Docker deployment with Gitea CI.
+
+## Build & Test Commands
+- **Build:** `npm run build`
+- **Test:** `npm test`
+- **Lint:** `npm run lint`
+- **Type Check:** `npm run check`
+
+## Tech Stack
+- **Framework:** SvelteKit (Svelte 5 runes mode) + TypeScript strict
+- **UI:** Tailwind CSS v4 + shadcn-svelte (Bits UI) + Lucide Svelte + Simple Icons
+- **Data:** Prisma ORM + SQLite + Superforms + Zod
+- **Auth:** bcrypt + JWT (HTTP-only cookies) + refresh token rotation
+- **Background Jobs:** node-cron
+- **DevOps:** Docker (multi-stage) + docker-compose + Gitea Actions
+
+## Phases
+
+- [ ] Phase 1: Project Scaffolding & Tooling [backend] → [subplan](./phase-1-scaffolding.md)
+- [ ] Phase 2: Database Schema & Services Layer [backend] → [subplan](./phase-2-database-services.md)
+- [ ] Phase 3: Authentication System [fullstack] → [subplan](./phase-3-authentication.md)
+- [ ] Phase 4: App Registry & Healthcheck [fullstack] → [subplan](./phase-4-app-healthcheck.md)
+- [ ] Phase 5: Board, Section & Widget System [fullstack] → [subplan](./phase-5-board-widgets.md)
+- [ ] Phase 6: Admin Panel [fullstack] → [subplan](./phase-6-admin-panel.md)
+- [ ] Phase 7: UI Polish & Ambient Backgrounds [frontend] → [subplan](./phase-7-ui-polish.md)
+- [ ] Phase 8: Integration, Testing & Deployment [fullstack] → [subplan](./phase-8-integration-deploy.md)
+
+## Phase Progress Log
+
+| Phase | Domain | Status | Review | Build | Committed |
+|-------|--------|--------|--------|-------|-----------|
+| Phase 1: Scaffolding | backend | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 2: Database & Services | backend | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 3: Authentication | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 4: App & Healthcheck | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 5: Board & Widgets | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 6: Admin Panel | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 7: UI Polish | frontend | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+| Phase 8: Integration & Deploy | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
+
+## Final Review
+- [ ] Comprehensive code review
+- [ ] Full build passes
+- [ ] Full test suite passes
+- [ ] Merged to `master`
@@ -0,0 +1,63 @@
+# Phase 1: Project Scaffolding & Tooling
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Initialize the SvelteKit project with the full toolchain: TypeScript strict, Svelte 5, Tailwind CSS v4, shadcn-svelte, Prisma + SQLite, Vitest, ESLint, Prettier. Create the Docker and CI configuration.
+
+## Tasks
+
+- [ ] Task 1: Initialize SvelteKit project with TypeScript, Svelte 5 adapter-node
+- [ ] Task 2: Install and configure Tailwind CSS v4
+- [ ] Task 3: Install and configure shadcn-svelte (Bits UI primitives)
+- [ ] Task 4: Install Prisma, configure SQLite provider, create initial empty schema
+- [ ] Task 5: Install Vitest and configure for SvelteKit
+- [ ] Task 6: Configure ESLint + Prettier for Svelte/TS
+- [ ] Task 7: Install runtime dependencies: lucide-svelte, simple-icons, superforms, zod, bcrypt, jsonwebtoken, node-cron, openid-client
+- [ ] Task 8: Create `.env.example` with all required env vars
+- [ ] Task 9: Create `Dockerfile` (multi-stage build)
+- [ ] Task 10: Create `docker-compose.yml`
+- [ ] Task 11: Create `.gitea/workflows/ci.yml` (lint, type-check, test, Docker build)
+- [ ] Task 12: Create `app.css` with Tailwind base + CSS custom properties for theming
+- [ ] Task 13: Create `app.d.ts` with SvelteKit type augmentation (Locals, Session)
+
+## Files to Modify/Create
+- `package.json` — project config with all dependencies and scripts
+- `svelte.config.js` — SvelteKit config with adapter-node
+- `vite.config.ts` — Vite config with Vitest
+- `tsconfig.json` — TypeScript strict config
+- `tailwind.config.ts` — Tailwind v4 config
+- `src/app.css` — Tailwind imports + theme variables
+- `src/app.d.ts` — SvelteKit type augmentation
+- `src/app.html` — HTML template
+- `prisma/schema.prisma` — empty schema with SQLite datasource
+- `.env.example` — template env vars
+- `Dockerfile` — multi-stage Node build
+- `docker-compose.yml` — single-service deployment
+- `.gitea/workflows/ci.yml` — CI pipeline
+- `eslint.config.js` — ESLint flat config
+- `.prettierrc` — Prettier config
+
+## Acceptance Criteria
+- `npm install` succeeds
+- Project structure matches SvelteKit conventions
+- All config files are valid
+- Dockerfile builds (structure-wise, not the app itself yet)
+
+## Notes
+- Use `@sveltejs/adapter-node` for Docker deployment
+- Svelte 5 runes mode is the default in latest SvelteKit — no special config needed
+- Tailwind v4 uses the new CSS-based config approach
+- ⚠️ Big Bang: build will not pass yet — no routes or components exist
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,62 @@
+# Phase 2: Database Schema & Services Layer
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** backend
+
+## Objective
+Define the full Prisma database schema, run migrations, and build the core server-side services layer with shared Zod validation schemas and TypeScript type definitions.
+
+## Tasks
+
+- [ ] Task 1: Define Prisma schema with all models: User, Group, UserGroup, App, AppStatus, Board, Section, Widget, Permission, SystemSettings
+- [ ] Task 2: Run `prisma migrate dev` to create initial migration
+- [ ] Task 3: Create TypeScript type definitions in `src/lib/types/` (auth, app, board, widget, user, group, permission)
+- [ ] Task 4: Create shared Zod validation schemas in `src/lib/utils/validators.ts`
+- [ ] Task 5: Create API response envelope utility in `src/lib/server/utils/response.ts`
+- [ ] Task 6: Implement `authService.ts` — password hashing, JWT sign/verify, refresh token management
+- [ ] Task 7: Implement `userService.ts` — CRUD, findByEmail, role management
+- [ ] Task 8: Implement `groupService.ts` — CRUD, user-group membership
+- [ ] Task 9: Implement `appService.ts` — CRUD, search, status updates
+- [ ] Task 10: Implement `boardService.ts` — CRUD with sections and widgets, default board
+- [ ] Task 11: Implement `permissionService.ts` — check/grant/revoke permissions, hierarchical resolution
+- [ ] Task 12: Create `src/lib/utils/constants.ts` — shared constants (roles, status values, defaults)
+- [ ] Task 13: Create `prisma/seed.ts` — seed admin user, default groups, default board, sample apps
+
+## Files to Modify/Create
+- `prisma/schema.prisma` — full schema definition
+- `prisma/seed.ts` — seed script
+- `src/lib/types/*.ts` — type definitions
+- `src/lib/utils/validators.ts` — Zod schemas
+- `src/lib/utils/constants.ts` — constants
+- `src/lib/server/utils/response.ts` — API envelope
+- `src/lib/server/services/authService.ts`
+- `src/lib/server/services/userService.ts`
+- `src/lib/server/services/groupService.ts`
+- `src/lib/server/services/appService.ts`
+- `src/lib/server/services/boardService.ts`
+- `src/lib/server/services/permissionService.ts`
+
+## Acceptance Criteria
+- Prisma schema validates and migration runs
+- All services export clean async functions with proper types
+- Zod schemas match Prisma models
+- Seed script creates demo data
+- No circular dependencies between services
+
+## Notes
+- SystemSettings is a singleton row — use upsert pattern
+- Permission resolution: User-level > Group-level > Default
+- Widget config is JSON — use Prisma `Json` type
+- OAuth fields in SystemSettings should be encrypted at rest (handle in Phase 3)
+- ⚠️ Big Bang: services won't be wired to routes yet
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,70 @@
+# Phase 3: Authentication System
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Implement the full local authentication flow: login, registration, session management with JWT + refresh tokens in HTTP-only cookies, auth middleware in hooks.server.ts, and guest mode support.
+
+## Tasks
+
+- [ ] Task 1: Implement `src/lib/server/utils/jwt.ts` — sign, verify, refresh token generation
+- [ ] Task 2: Implement `src/lib/server/utils/password.ts` — bcrypt hash/compare
+- [ ] Task 3: Implement `src/hooks.server.ts` — auth middleware, session injection into `event.locals`
+- [ ] Task 4: Create `src/routes/login/+page.server.ts` — login form action (Superforms + Zod)
+- [ ] Task 5: Create `src/routes/login/+page.svelte` — login page UI
+- [ ] Task 6: Create `src/routes/register/+page.server.ts` — registration form action (respects admin toggle)
+- [ ] Task 7: Create `src/routes/register/+page.svelte` — registration page UI
+- [ ] Task 8: Create `src/routes/auth/refresh/+server.ts` — token refresh endpoint
+- [ ] Task 9: Create `src/routes/+layout.server.ts` — root layout load: inject user session
+- [ ] Task 10: Create `src/routes/+layout.svelte` — root layout shell (minimal, polished in Phase 7)
+- [ ] Task 11: Implement `src/lib/server/middleware/authenticate.ts` — reusable auth check helper
+- [ ] Task 12: Implement `src/lib/server/middleware/authorize.ts` — role-based access check
+- [ ] Task 13: Implement `src/lib/server/middleware/guestAccess.ts` — guest mode board visibility
+- [ ] Task 14: Create `src/routes/+page.svelte` — root page (redirect to default board or login)
+- [ ] Task 15: Create logout endpoint/action — invalidate refresh token, clear cookies
+
+## Files to Modify/Create
+- `src/hooks.server.ts` — auth middleware
+- `src/lib/server/utils/jwt.ts` — JWT utilities
+- `src/lib/server/utils/password.ts` — password utilities
+- `src/lib/server/middleware/authenticate.ts`
+- `src/lib/server/middleware/authorize.ts`
+- `src/lib/server/middleware/guestAccess.ts`
+- `src/routes/login/+page.svelte`
+- `src/routes/login/+page.server.ts`
+- `src/routes/register/+page.svelte`
+- `src/routes/register/+page.server.ts`
+- `src/routes/auth/refresh/+server.ts`
+- `src/routes/+layout.server.ts`
+- `src/routes/+layout.svelte`
+- `src/routes/+page.svelte`
+- `src/app.d.ts` — augment `Locals` with user session type
+
+## Acceptance Criteria
+- Users can register (when enabled) and log in with email/password
+- JWT access token + refresh token issued in HTTP-only cookies
+- `hooks.server.ts` validates tokens on every request and injects user into `event.locals`
+- Refresh token rotation works (old token invalidated)
+- Logout clears cookies and invalidates refresh token
+- Guest mode: unauthenticated users can access guest-accessible boards
+- Protected routes redirect to login
+- Form validation with Superforms + Zod shows errors inline
+
+## Notes
+- Access token expiry: 15 minutes; Refresh token expiry: 7 days
+- Store refresh tokens in DB (User model) for server-side invalidation
+- OAuth is deferred to Phase 2 of the project (post-MVP)
+- Registration toggle is read from SystemSettings
+- ⚠️ Big Bang: login page will be functional but unstyled/minimal until Phase 7
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,65 @@
+# Phase 4: App Registry & Healthcheck
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Build the app (service) registry with CRUD operations, the icon resolution system, healthcheck scheduler with node-cron, and status APIs. Create the app management UI.
+
+## Tasks
+
+- [ ] Task 1: Create `src/routes/api/apps/+server.ts` — GET (list), POST (create)
+- [ ] Task 2: Create `src/routes/api/apps/[id]/+server.ts` — GET, PATCH, DELETE
+- [ ] Task 3: Create `src/routes/api/apps/[id]/status/+server.ts` — GET healthcheck status
+- [ ] Task 4: Implement `src/lib/server/services/healthcheckService.ts` — perform HTTP health checks
+- [ ] Task 5: Implement `src/lib/server/jobs/healthcheckScheduler.ts` — node-cron scheduled pings
+- [ ] Task 6: Implement `src/lib/server/utils/iconResolver.ts` — resolve icon by type (Lucide, Simple Icons, Dashboard Icons CDN, upload path)
+- [ ] Task 7: Create `src/routes/apps/+page.server.ts` — load app list
+- [ ] Task 8: Create `src/routes/apps/+page.svelte` — app registry list page
+- [ ] Task 9: Create `src/lib/components/app/AppCard.svelte` — app card with status indicator
+- [ ] Task 10: Create `src/lib/components/app/AppForm.svelte` — create/edit app form (Superforms)
+- [ ] Task 11: Create `src/lib/components/app/AppIconPicker.svelte` — icon selection UI
+- [ ] Task 12: Create `src/lib/components/app/AppHealthBadge.svelte` — status badge (online/offline/degraded/unknown)
+- [ ] Task 13: Create `src/routes/api/health/+server.ts` — app health endpoint for Docker healthcheck
+- [ ] Task 14: Handle custom icon uploads — file upload endpoint + static serving from `static/uploads/`
+
+## Files to Modify/Create
+- `src/routes/api/apps/+server.ts`
+- `src/routes/api/apps/[id]/+server.ts`
+- `src/routes/api/apps/[id]/status/+server.ts`
+- `src/routes/api/health/+server.ts`
+- `src/lib/server/services/healthcheckService.ts`
+- `src/lib/server/jobs/healthcheckScheduler.ts`
+- `src/lib/server/utils/iconResolver.ts`
+- `src/routes/apps/+page.server.ts`
+- `src/routes/apps/+page.svelte`
+- `src/lib/components/app/AppCard.svelte`
+- `src/lib/components/app/AppForm.svelte`
+- `src/lib/components/app/AppIconPicker.svelte`
+- `src/lib/components/app/AppHealthBadge.svelte`
+
+## Acceptance Criteria
+- Apps can be created, read, updated, deleted via API
+- Healthcheck scheduler runs on configured intervals per app
+- Status is correctly derived: online/offline/degraded/unknown
+- Icon resolver correctly maps all icon types to renderable output
+- App list page displays apps with status badges
+- Docker health endpoint returns 200 when server is running
+
+## Notes
+- Healthcheck runs in-process via node-cron (no external job runner)
+- Default healthcheck: HTTP HEAD to app URL, expect 200, 5s timeout, 60s interval
+- Store last N status records in AppStatus for history (sparklines are post-MVP)
+- Custom icon uploads go to `static/uploads/` (Docker volume mount)
+- ⚠️ Big Bang: pages will be functional but minimally styled until Phase 7
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,74 @@
+# Phase 5: Board, Section & Widget System
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Build the board/section/widget system — the core UI of the dashboard. Implement CRUD APIs, the board view page with collapsible sections and app widgets in a responsive grid, and the board editor.
+
+## Tasks
+
+- [ ] Task 1: Create `src/routes/api/boards/+server.ts` — GET (list, filtered by permissions), POST
+- [ ] Task 2: Create `src/routes/api/boards/[id]/+server.ts` — GET, PATCH, DELETE
+- [ ] Task 3: Create `src/routes/api/boards/[id]/sections/+server.ts` — GET, POST
+- [ ] Task 4: Create `src/routes/api/boards/[id]/sections/[sid]/+server.ts` — GET, PATCH, DELETE
+- [ ] Task 5: Create `src/routes/api/boards/[id]/sections/[sid]/widgets/+server.ts` — GET, POST, PATCH, DELETE
+- [ ] Task 6: Create `src/routes/boards/+page.server.ts` — load board list
+- [ ] Task 7: Create `src/routes/boards/+page.svelte` — board list page
+- [ ] Task 8: Create `src/routes/boards/[boardId]/+page.server.ts` — load board with sections, widgets, app data
+- [ ] Task 9: Create `src/routes/boards/[boardId]/+page.svelte` — board view page
+- [ ] Task 10: Create `src/routes/boards/[boardId]/edit/+page.server.ts` — board editor data + actions
+- [ ] Task 11: Create `src/routes/boards/[boardId]/edit/+page.svelte` — board editor page
+- [ ] Task 12: Create `src/lib/components/board/Board.svelte` — board container
+- [ ] Task 13: Create `src/lib/components/board/BoardHeader.svelte` — board title, description, actions
+- [ ] Task 14: Create `src/lib/components/board/BoardCard.svelte` — board card for list view
+- [ ] Task 15: Create `src/lib/components/section/Section.svelte` — section container
+- [ ] Task 16: Create `src/lib/components/section/SectionHeader.svelte` — section title with collapse toggle
+- [ ] Task 17: Create `src/lib/components/section/SectionCollapsible.svelte` — collapsible wrapper
+- [ ] Task 18: Create `src/lib/components/widget/AppWidget.svelte` — app widget displaying icon, name, status
+- [ ] Task 19: Create `src/lib/components/widget/WidgetContainer.svelte` — generic widget wrapper
+- [ ] Task 20: Create `src/lib/components/widget/WidgetGrid.svelte` — responsive grid layout for widgets
+
+## Files to Modify/Create
+- `src/routes/api/boards/+server.ts`
+- `src/routes/api/boards/[id]/+server.ts`
+- `src/routes/api/boards/[id]/sections/+server.ts`
+- `src/routes/api/boards/[id]/sections/[sid]/+server.ts`
+- `src/routes/api/boards/[id]/sections/[sid]/widgets/+server.ts`
+- `src/routes/boards/+page.server.ts`
+- `src/routes/boards/+page.svelte`
+- `src/routes/boards/[boardId]/+page.server.ts`
+- `src/routes/boards/[boardId]/+page.svelte`
+- `src/routes/boards/[boardId]/edit/+page.server.ts`
+- `src/routes/boards/[boardId]/edit/+page.svelte`
+- `src/lib/components/board/*.svelte`
+- `src/lib/components/section/*.svelte`
+- `src/lib/components/widget/*.svelte`
+
+## Acceptance Criteria
+- Boards can be created, listed, viewed, edited, deleted
+- Sections within boards support CRUD and ordering
+- Widgets within sections support CRUD and ordering
+- Board view renders sections with collapsible behavior
+- App widgets show icon, name, status dot, and link to app URL
+- Responsive grid adapts to screen size
+- Default board is accessible from root page
+
+## Notes
+- MVP supports only AppWidget type; schema should have `type` field for future widget types
+- Widget config is JSON: `{ appId: string }` for AppWidget
+- Section collapse uses Svelte `slide` transition
+- Board editor is a form-based editor (drag-and-drop is post-MVP Phase 2)
+- Permission filtering on board list uses permissionService
+- ⚠️ Big Bang: functional but minimally styled until Phase 7
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,71 @@
+# Phase 6: Admin Panel
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Build the admin panel with user management, group management, app management, board management, and system settings configuration.
+
+## Tasks
+
+- [ ] Task 1: Create `src/routes/admin/+layout.server.ts` — admin auth guard (role check)
+- [ ] Task 2: Create `src/routes/admin/+layout.svelte` — admin layout with nav
+- [ ] Task 3: Create `src/routes/api/users/+server.ts` — GET (list), POST (create user)
+- [ ] Task 4: Create `src/routes/api/users/[id]/+server.ts` — GET, PATCH, DELETE
+- [ ] Task 5: Create `src/routes/api/groups/+server.ts` — GET (list), POST (create group)
+- [ ] Task 6: Create `src/routes/api/groups/[id]/+server.ts` — GET, PATCH, DELETE
+- [ ] Task 7: Create `src/routes/api/admin/settings/+server.ts` — GET, PATCH system settings
+- [ ] Task 8: Create `src/routes/admin/users/+page.server.ts` — load users
+- [ ] Task 9: Create `src/routes/admin/users/+page.svelte` — user management page
+- [ ] Task 10: Create `src/routes/admin/groups/+page.server.ts` — load groups
+- [ ] Task 11: Create `src/routes/admin/groups/+page.svelte` — group management page
+- [ ] Task 12: Create `src/routes/admin/settings/+page.server.ts` — load/update settings
+- [ ] Task 13: Create `src/routes/admin/settings/+page.svelte` — system settings page
+- [ ] Task 14: Create `src/lib/components/admin/UserTable.svelte` — user list with actions
+- [ ] Task 15: Create `src/lib/components/admin/GroupTable.svelte` — group list with actions
+- [ ] Task 16: Create `src/lib/components/admin/SettingsForm.svelte` — settings form
+- [ ] Task 17: Create `src/lib/components/admin/PermissionEditor.svelte` — permission assignment UI
+- [ ] Task 18: Create `src/routes/api/search/+server.ts` — global search endpoint (searches apps + boards)
+
+## Files to Modify/Create
+- `src/routes/admin/+layout.server.ts`
+- `src/routes/admin/+layout.svelte`
+- `src/routes/admin/users/+page.server.ts`
+- `src/routes/admin/users/+page.svelte`
+- `src/routes/admin/groups/+page.server.ts`
+- `src/routes/admin/groups/+page.svelte`
+- `src/routes/admin/settings/+page.server.ts`
+- `src/routes/admin/settings/+page.svelte`
+- `src/routes/api/users/+server.ts`
+- `src/routes/api/users/[id]/+server.ts`
+- `src/routes/api/groups/+server.ts`
+- `src/routes/api/groups/[id]/+server.ts`
+- `src/routes/api/admin/settings/+server.ts`
+- `src/routes/api/search/+server.ts`
+- `src/lib/components/admin/*.svelte`
+
+## Acceptance Criteria
+- Admin-only routes are protected (non-admin users get 403/redirect)
+- Users can be created, edited, deleted, assigned to groups
+- Groups can be created, edited, deleted
+- System settings can be viewed and updated (auth mode, registration, theme defaults, healthcheck defaults)
+- Search API returns matching apps and boards filtered by user permissions
+- All forms use Superforms + Zod validation
+
+## Notes
+- Admin role is checked in `+layout.server.ts` — redirect non-admins
+- User creation by admin sets password directly (no email verification in MVP)
+- OAuth config fields in settings are stored but non-functional until post-MVP Phase 2
+- Permission editor UI: simple select dropdowns for entity + target + level
+- ⚠️ Big Bang: functional but minimally styled until Phase 7
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,86 @@
+# Phase 7: UI Polish & Ambient Backgrounds
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** frontend
+
+## Objective
+Polish the entire UI: implement the root layout with sidebar and header, dark/light/system theme with HSL customization, ambient animated backgrounds, page transitions, animations, skeleton loading states, and responsive design.
+
+## Tasks
+
+- [ ] Task 1: Create `src/lib/components/layout/MainLayout.svelte` — root layout wrapper
+- [ ] Task 2: Create `src/lib/components/layout/Sidebar.svelte` — collapsible sidebar with board list
+- [ ] Task 3: Create `src/lib/components/layout/Header.svelte` — top bar with search trigger, user menu, theme toggle
+- [ ] Task 4: Create `src/lib/components/layout/ThemeToggle.svelte` — dark/light/system toggle
+- [ ] Task 5: Create `src/lib/stores/theme.svelte.ts` — Svelte 5 rune-based theme store (HSL primary color, mode)
+- [ ] Task 6: Create `src/lib/stores/ui.svelte.ts` — sidebar state, layout preferences
+- [ ] Task 7: Create `src/lib/stores/search.svelte.ts` — search dialog state
+- [ ] Task 8: Update `src/app.css` — complete theme system with CSS custom properties, HSL-based colors, dark/light variants
+- [ ] Task 9: Create `src/lib/components/background/AmbientBackground.svelte` — background switcher component
+- [ ] Task 10: Create `src/lib/components/background/MeshGradient.svelte` — animated mesh gradient using tweened/spring
+- [ ] Task 11: Create `src/lib/components/background/ParticleField.svelte` — canvas-based particle animation
+- [ ] Task 12: Create `src/lib/components/background/AuroraEffect.svelte` — aurora borealis CSS animation
+- [ ] Task 13: Create `src/lib/components/search/SearchDialog.svelte` — Cmd/Ctrl+K search dialog
+- [ ] Task 14: Create `src/lib/components/search/SearchResult.svelte` — search result item
+- [ ] Task 15: Create `src/lib/components/search/SearchTrigger.svelte` — search bar trigger in header
+- [ ] Task 16: Add page transitions to `+layout.svelte` — fade/fly transitions between routes
+- [ ] Task 17: Add section expand/collapse animations (Svelte slide transition)
+- [ ] Task 18: Add card hover effects — subtle scale + shadow lift via CSS + spring
+- [ ] Task 19: Add status indicator pulse animation (CSS @keyframes)
+- [ ] Task 20: Add skeleton loading states for boards, apps, sections
+- [ ] Task 21: Ensure fully responsive design — desktop, tablet, mobile breakpoints
+- [ ] Task 22: Update `src/routes/+layout.svelte` — integrate MainLayout, AmbientBackground, theme system
+- [ ] Task 23: Polish login and register pages with consistent styling
+- [ ] Task 24: Polish all existing pages (apps, boards, admin) with consistent component styling
+
+## Files to Modify/Create
+- `src/lib/components/layout/MainLayout.svelte`
+- `src/lib/components/layout/Sidebar.svelte`
+- `src/lib/components/layout/Header.svelte`
+- `src/lib/components/layout/ThemeToggle.svelte`
+- `src/lib/stores/theme.svelte.ts`
+- `src/lib/stores/ui.svelte.ts`
+- `src/lib/stores/search.svelte.ts`
+- `src/app.css` — update
+- `src/lib/components/background/AmbientBackground.svelte`
+- `src/lib/components/background/MeshGradient.svelte`
+- `src/lib/components/background/ParticleField.svelte`
+- `src/lib/components/background/AuroraEffect.svelte`
+- `src/lib/components/search/SearchDialog.svelte`
+- `src/lib/components/search/SearchResult.svelte`
+- `src/lib/components/search/SearchTrigger.svelte`
+- `src/routes/+layout.svelte` — update
+- Various existing component files — add animations, polish styling
+
+## Acceptance Criteria
+- Dark/Light/System theme works with smooth CSS transitions
+- HSL-based primary color customization works
+- At least one ambient background (mesh gradient) animates smoothly
+- Sidebar is collapsible and shows board list
+- Header has search trigger, user menu, theme toggle
+- Cmd/Ctrl+K opens search dialog
+- Page transitions are smooth
+- Section collapse is animated
+- Card hover has scale + shadow effect
+- Status dots pulse when online
+- Skeleton loaders appear during data fetches
+- Layout is responsive at desktop (>1024px), tablet (768-1024px), mobile (<768px)
+
+## Notes
+- Use Svelte 5 runes for stores, NOT legacy `writable`/`readable`
+- Use `svelte/motion` (tweened, spring) for ambient animations
+- AmbientBackground should be configurable and toggleable
+- Search dialog uses the `/api/search` endpoint from Phase 6
+- Keep animations performant — prefer CSS transforms/opacity over layout-triggering properties
+- Use Tailwind utility classes as primary styling approach
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Filled in by the implementation agent after completing this phase. -->
@@ -0,0 +1,65 @@
+# Phase 8: Integration, Testing & Deployment
+
+**Status:** ⬜ Not Started
+**Parent plan:** [PLAN.md](./PLAN.md)
+**Domain:** fullstack
+
+## Objective
+Integrate all phases into a fully working application. Fix all build errors, add test coverage, verify Docker deployment, and finalize the CI pipeline. This is the Big Bang convergence phase — everything must work after this.
+
+## Tasks
+
+- [ ] Task 1: Fix all TypeScript/build errors across the entire codebase
+- [ ] Task 2: Verify `npm run build` succeeds with adapter-node output
+- [ ] Task 3: Verify `npm run check` (svelte-check) passes
+- [ ] Task 4: Verify `npm run lint` passes
+- [ ] Task 5: Write unit tests for services (authService, appService, boardService, etc.)
+- [ ] Task 6: Write unit tests for utilities (jwt, password, iconResolver, validators)
+- [ ] Task 7: Write integration tests for API endpoints (auth, apps, boards, admin)
+- [ ] Task 8: Write component tests for key Svelte components (AppWidget, Board, Section)
+- [ ] Task 9: Verify test coverage ≥ 80%
+- [ ] Task 10: Update `prisma/seed.ts` with comprehensive demo data
+- [ ] Task 11: Verify Docker build succeeds (`docker build .`)
+- [ ] Task 12: Verify `docker-compose up` starts the app correctly
+- [ ] Task 13: Verify healthcheck endpoint works in Docker
+- [ ] Task 14: Finalize `.gitea/workflows/ci.yml` — ensure all CI steps pass
+- [ ] Task 15: Create `.env.example` with documentation for all env vars
+- [ ] Task 16: End-to-end smoke test: register → login → view board → add app → verify healthcheck
+
+## Files to Modify/Create
+- Various source files — fix build errors
+- `src/lib/server/services/__tests__/*.test.ts` — service unit tests
+- `src/lib/server/utils/__tests__/*.test.ts` — utility unit tests
+- `src/routes/api/**/*.test.ts` — API integration tests
+- `src/lib/components/**/*.test.ts` — component tests
+- `prisma/seed.ts` — update
+- `Dockerfile` — verify/fix
+- `docker-compose.yml` — verify/fix
+- `.gitea/workflows/ci.yml` — finalize
+- `.env.example` — update
+
+## Acceptance Criteria
+- `npm run build` succeeds
+- `npm run check` passes with no errors
+- `npm run lint` passes
+- `npm test` passes with ≥ 80% coverage
+- Docker image builds and runs successfully
+- App is fully functional: auth, apps, boards, admin, search, theme
+- Healthcheck scheduler runs on startup
+- CI pipeline runs all checks successfully
+
+## Notes
+- This is the Big Bang convergence — all previous phases may have left broken imports, missing types, or incomplete wiring. This phase resolves ALL of that.
+- Priority order: build errors → type errors → lint errors → tests → Docker → CI
+- If coverage is below 80%, prioritize testing critical paths: auth flow, app CRUD, board rendering
+- The seed script should create a realistic demo: admin user, 2 regular users, 8-10 sample apps, 1 board with 3 sections
+
+## Review Checklist
+- [ ] All tasks completed
+- [ ] Code follows project conventions
+- [ ] No unintended side effects
+- [ ] Build passes
+- [ ] Tests pass (new + existing)
+
+## Handoff to Next Phase
+<!-- Final phase — no handoff needed -->