web-app-launcher/plans/mvp-web-app-launcher/phase-1-scaffolding.md

Phase 1: Project Scaffolding & Tooling

Status: ✅ Complete Parent plan: 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, bcryptjs, jsonwebtoken, node-cron
• 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

Phase 1 scaffolding is complete. All tooling is configured and npm install succeeds.

What's ready for Phase 2:

• Prisma is installed with SQLite datasource configured at prisma/schema.prisma — add models there.
• @prisma/client is a devDependency; run npx prisma generate after adding models.
• DATABASE_URL defaults to file:../data/launcher.db (see .env.example).
• SvelteKit project structure is in place: src/routes/+page.svelte, src/app.html, src/app.css, src/app.d.ts.
• App.Locals type augmentation defines user and session — align with the User model in Phase 2.
• shadcn-svelte is configured via components.json — add UI components with npx shadcn-svelte@latest add <component>.
• src/lib/utils/cn.ts provides the cn() class-merge utility used by shadcn-svelte components.

Known gaps (expected for Big Bang strategy):

• npm run build will fail until SvelteKit routes and server hooks are wired up.
• npm run check will fail until .svelte-kit/ is generated via svelte-kit sync.
• No tests exist yet — npm test will pass vacuously (no test files).