From dc9bd3bba4f740c0197d1e5128058ca20429b4f4 Mon Sep 17 00:00:00 2001 From: "alexei.dolgolyov" Date: Tue, 24 Mar 2026 19:46:26 +0300 Subject: [PATCH] chore: add plan files and gitignore for MVP feature --- .gitignore | 41 +++++++++ plans/mvp-web-app-launcher/CONTEXT.md | 23 +++++ plans/mvp-web-app-launcher/PLAN.md | 56 ++++++++++++ .../phase-1-scaffolding.md | 63 ++++++++++++++ .../phase-2-database-services.md | 62 +++++++++++++ .../phase-3-authentication.md | 70 +++++++++++++++ .../phase-4-app-healthcheck.md | 65 ++++++++++++++ .../phase-5-board-widgets.md | 74 ++++++++++++++++ .../phase-6-admin-panel.md | 71 +++++++++++++++ .../mvp-web-app-launcher/phase-7-ui-polish.md | 86 +++++++++++++++++++ .../phase-8-integration-deploy.md | 65 ++++++++++++++ 11 files changed, 676 insertions(+) create mode 100644 .gitignore create mode 100644 plans/mvp-web-app-launcher/CONTEXT.md create mode 100644 plans/mvp-web-app-launcher/PLAN.md create mode 100644 plans/mvp-web-app-launcher/phase-1-scaffolding.md create mode 100644 plans/mvp-web-app-launcher/phase-2-database-services.md create mode 100644 plans/mvp-web-app-launcher/phase-3-authentication.md create mode 100644 plans/mvp-web-app-launcher/phase-4-app-healthcheck.md create mode 100644 plans/mvp-web-app-launcher/phase-5-board-widgets.md create mode 100644 plans/mvp-web-app-launcher/phase-6-admin-panel.md create mode 100644 plans/mvp-web-app-launcher/phase-7-ui-polish.md create mode 100644 plans/mvp-web-app-launcher/phase-8-integration-deploy.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..71bd183 --- /dev/null +++ b/.gitignore @@ -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 diff --git a/plans/mvp-web-app-launcher/CONTEXT.md b/plans/mvp-web-app-launcher/CONTEXT.md new file mode 100644 index 0000000..5149cd1 --- /dev/null +++ b/plans/mvp-web-app-launcher/CONTEXT.md @@ -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 diff --git a/plans/mvp-web-app-launcher/PLAN.md b/plans/mvp-web-app-launcher/PLAN.md new file mode 100644 index 0000000..1d06710 --- /dev/null +++ b/plans/mvp-web-app-launcher/PLAN.md @@ -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` diff --git a/plans/mvp-web-app-launcher/phase-1-scaffolding.md b/plans/mvp-web-app-launcher/phase-1-scaffolding.md new file mode 100644 index 0000000..ef41b92 --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-1-scaffolding.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-2-database-services.md b/plans/mvp-web-app-launcher/phase-2-database-services.md new file mode 100644 index 0000000..f008bb3 --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-2-database-services.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-3-authentication.md b/plans/mvp-web-app-launcher/phase-3-authentication.md new file mode 100644 index 0000000..4820338 --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-3-authentication.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-4-app-healthcheck.md b/plans/mvp-web-app-launcher/phase-4-app-healthcheck.md new file mode 100644 index 0000000..cb04b0a --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-4-app-healthcheck.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-5-board-widgets.md b/plans/mvp-web-app-launcher/phase-5-board-widgets.md new file mode 100644 index 0000000..7eb5304 --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-5-board-widgets.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-6-admin-panel.md b/plans/mvp-web-app-launcher/phase-6-admin-panel.md new file mode 100644 index 0000000..839985d --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-6-admin-panel.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-7-ui-polish.md b/plans/mvp-web-app-launcher/phase-7-ui-polish.md new file mode 100644 index 0000000..6b6ee53 --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-7-ui-polish.md @@ -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 + diff --git a/plans/mvp-web-app-launcher/phase-8-integration-deploy.md b/plans/mvp-web-app-launcher/phase-8-integration-deploy.md new file mode 100644 index 0000000..424f813 --- /dev/null +++ b/plans/mvp-web-app-launcher/phase-8-integration-deploy.md @@ -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 +