chore: initial project scaffold

Set up Mangalord with a Rust/axum backend, SvelteKit frontend, Postgres,
and Docker Compose deployment. Establishes the architecture and TDD
patterns the project will extend:

- Hexagonal-ish backend layering (domain / repo / storage / api) with
  a pluggable Storage trait (LocalStorage today, S3 as a future impl).
- Initial migration: users, mangas, chapters, bookmarks.
- Vertical slice for mangas (list, search, create, get) with
  #[sqlx::test] integration coverage and storage unit tests.
- SvelteKit frontend using Svelte 5 runes, typed API client, Vitest
  unit tests and Playwright e2e with route mocking.
- CLAUDE.md documenting layering, TDD/git/SemVer workflow rules, and
  extension points (tags, fulltext search, OCR, S3, auth).
- Project-scoped .claude/settings.json with permission allowlist for
  the toolchain (git, cargo, npm/vite, docker, psql, gh, doc fetches).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

frontend/.gitignore

@@ -0,0 +1,7 @@
+node_modules
+.svelte-kit
+build
+test-results
+playwright-report
+.env
+.env.local

frontend/Dockerfile

@@ -0,0 +1,17 @@
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+COPY --from=builder /app/build ./build
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+EXPOSE 3000
+CMD ["node", "build"]

frontend/e2e/manga-list.spec.ts

@@ -0,0 +1,57 @@
+import { test, expect } from '@playwright/test';
+
+// These E2E tests run against the dev server (vite on :5173) which proxies
+// /api to the backend. Set E2E_BASE_URL to point at a different deployment.
+//
+// A live backend (and Postgres) must be reachable. Routes mock the network
+// where possible to keep journeys deterministic.
+
+test('home page renders the Mangalord heading and search input', async ({ page }) => {
+    // Mock the list endpoint so the test doesn't depend on DB state.
+    await page.route('**/api/mangas*', async (route) => {
+        await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify([])
+        });
+    });
+
+    await page.goto('/');
+    await expect(page.getByRole('link', { name: 'Mangalord' })).toBeVisible();
+    await expect(page.getByTestId('search-input')).toBeVisible();
+    await expect(page.getByTestId('empty')).toContainText('No mangas yet');
+});
+
+test('search updates the manga list', async ({ page }) => {
+    let lastSearch: string | null = null;
+    await page.route('**/api/mangas*', async (route) => {
+        const url = new URL(route.request().url());
+        lastSearch = url.searchParams.get('search');
+        const body =
+            lastSearch === 'berserk'
+                ? [
+                      {
+                          id: 'b1',
+                          title: 'Berserk',
+                          author: 'Kentaro Miura',
+                          description: null,
+                          cover_image_path: null,
+                          created_at: '2026-01-01T00:00:00Z',
+                          updated_at: '2026-01-01T00:00:00Z'
+                      }
+                  ]
+                : [];
+        await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify(body)
+        });
+    });
+
+    await page.goto('/');
+    await page.getByTestId('search-input').fill('berserk');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await expect(page.getByTestId('manga-list')).toContainText('Berserk');
+    expect(lastSearch).toBe('berserk');
+});

frontend/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "mangalord-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.48.0",
+    "@sveltejs/adapter-node": "^5.2.0",
+    "@sveltejs/kit": "^2.7.0",
+    "@sveltejs/vite-plugin-svelte": "^4.0.0",
+    "@testing-library/jest-dom": "^6.6.0",
+    "@testing-library/svelte": "^5.2.0",
+    "@types/node": "^22.7.0",
+    "jsdom": "^25.0.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "tslib": "^2.7.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0"
+  }
+}

frontend/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+    testDir: 'e2e',
+    timeout: 30_000,
+    use: {
+        baseURL: process.env.E2E_BASE_URL ?? 'http://localhost:5173',
+        trace: 'retain-on-failure'
+    },
+    webServer: process.env.E2E_BASE_URL
+        ? undefined
+        : {
+              command: 'npm run dev',
+              port: 5173,
+              reuseExistingServer: !process.env.CI,
+              timeout: 120_000
+          }
+});

frontend/src/app.d.ts

@@ -0,0 +1,11 @@
+declare global {
+    namespace App {
+        // interface Error {}
+        // interface Locals {}
+        // interface PageData {}
+        // interface PageState {}
+        // interface Platform {}
+    }
+}
+
+export {};

frontend/src/app.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <link rel="icon" href="%sveltekit.assets%/favicon.ico" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Mangalord</title>
+        %sveltekit.head%
+    </head>
+    <body data-sveltekit-preload-data="hover">
+        <div style="display: contents">%sveltekit.body%</div>
+    </body>
+</html>

frontend/src/lib/api/client.ts

@@ -0,0 +1,33 @@
+// All backend calls go through this module. Components and routes import
+// the typed helpers below — they do not call fetch directly.
+
+const BASE = (typeof import.meta !== 'undefined' && import.meta.env?.VITE_API_BASE) || '/api';
+
+export class ApiError extends Error {
+    constructor(
+        public readonly status: number,
+        message: string
+    ) {
+        super(message);
+        this.name = 'ApiError';
+    }
+}
+
+export async function request<T>(path: string, init?: RequestInit): Promise<T> {
+    const res = await fetch(`${BASE}${path}`, init);
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new ApiError(res.status, text || `${res.status} ${res.statusText}`);
+    }
+    return (await res.json()) as T;
+}
+
+export type Manga = {
+    id: string;
+    title: string;
+    author: string | null;
+    description: string | null;
+    cover_image_path: string | null;
+    created_at: string;
+    updated_at: string;
+};

frontend/src/lib/api/mangas.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { listMangas, createManga, getManga } from './mangas';
+
+function ok(body: unknown): Response {
+    return new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { 'content-type': 'application/json' }
+    });
+}
+
+function fail(status: number, body = ''): Response {
+    return new Response(body, { status });
+}
+
+describe('mangas api client', () => {
+    let fetchSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('listMangas hits /mangas with no params by default', async () => {
+        fetchSpy.mockResolvedValueOnce(ok([]));
+        await listMangas();
+        expect(fetchSpy).toHaveBeenCalledTimes(1);
+        const url = fetchSpy.mock.calls[0][0] as string;
+        expect(url).toMatch(/\/mangas$/);
+    });
+
+    it('listMangas encodes search, limit, offset', async () => {
+        fetchSpy.mockResolvedValueOnce(ok([]));
+        await listMangas({ search: 'one piece', limit: 10, offset: 20 });
+        const url = fetchSpy.mock.calls[0][0] as string;
+        expect(url).toContain('search=one+piece');
+        expect(url).toContain('limit=10');
+        expect(url).toContain('offset=20');
+    });
+
+    it('createManga POSTs JSON', async () => {
+        fetchSpy.mockResolvedValueOnce(
+            ok({
+                id: 'abc',
+                title: 'Berserk',
+                author: 'Miura',
+                description: null,
+                cover_image_path: null,
+                created_at: '2026-01-01T00:00:00Z',
+                updated_at: '2026-01-01T00:00:00Z'
+            })
+        );
+        const m = await createManga({ title: 'Berserk', author: 'Miura' });
+        expect(m.title).toBe('Berserk');
+        const init = fetchSpy.mock.calls[0][1] as RequestInit;
+        expect(init.method).toBe('POST');
+        expect(init.headers).toMatchObject({ 'content-type': 'application/json' });
+        expect(JSON.parse(init.body as string)).toEqual({ title: 'Berserk', author: 'Miura' });
+    });
+
+    it('getManga throws ApiError on non-2xx', async () => {
+        fetchSpy.mockResolvedValue(fail(404, 'not found'));
+        await expect(getManga('missing')).rejects.toMatchObject({
+            name: 'ApiError',
+            status: 404
+        });
+    });
+});

frontend/src/lib/api/mangas.ts

@@ -0,0 +1,36 @@
+import { request, type Manga } from './client';
+
+export type ListOptions = {
+    search?: string;
+    limit?: number;
+    offset?: number;
+};
+
+export async function listMangas(opts: ListOptions = {}): Promise<Manga[]> {
+    const params = new URLSearchParams();
+    if (opts.search) params.set('search', opts.search);
+    if (opts.limit != null) params.set('limit', String(opts.limit));
+    if (opts.offset != null) params.set('offset', String(opts.offset));
+    const qs = params.toString();
+    return request<Manga[]>(`/mangas${qs ? `?${qs}` : ''}`);
+}
+
+export async function getManga(id: string): Promise<Manga> {
+    return request<Manga>(`/mangas/${encodeURIComponent(id)}`);
+}
+
+export type NewManga = {
+    title: string;
+    author?: string | null;
+    description?: string | null;
+};
+
+export async function createManga(input: NewManga): Promise<Manga> {
+    return request<Manga>('/mangas', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(input)
+    });
+}
+
+export type { Manga };

frontend/src/routes/+layout.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+    let { children } = $props();
+</script>
+
+<header>
+    <nav>
+        <a href="/">Mangalord</a>
+        <a href="/upload">Upload</a>
+        <a href="/bookmarks">Bookmarks</a>
+    </nav>
+</header>
+
+<main>
+    {@render children()}
+</main>
+
+<style>
+    header {
+        padding: 1rem;
+        border-bottom: 1px solid #ddd;
+    }
+    nav a {
+        margin-right: 1rem;
+    }
+    main {
+        padding: 1rem;
+        max-width: 64rem;
+        margin: 0 auto;
+    }
+</style>

frontend/src/routes/+page.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+    import { onMount } from 'svelte';
+    import { listMangas, type Manga } from '$lib/api/mangas';
+
+    let mangas: Manga[] = $state([]);
+    let search = $state('');
+    let loading = $state(true);
+    let error: string | null = $state(null);
+
+    async function load() {
+        loading = true;
+        error = null;
+        try {
+            mangas = await listMangas({ search: search.trim() || undefined });
+        } catch (e) {
+            error = (e as Error).message;
+        } finally {
+            loading = false;
+        }
+    }
+
+    onMount(load);
+</script>
+
+<h1>Mangas</h1>
+
+<form
+    onsubmit={(e) => {
+        e.preventDefault();
+        load();
+    }}
+>
+    <input
+        type="search"
+        bind:value={search}
+        placeholder="Search by title or author"
+        data-testid="search-input"
+    />
+    <button type="submit">Search</button>
+</form>
+
+{#if loading}
+    <p data-testid="loading">Loading…</p>
+{:else if error}
+    <p data-testid="error" role="alert">{error}</p>
+{:else if mangas.length === 0}
+    <p data-testid="empty">No mangas yet. <a href="/upload">Upload one</a>.</p>
+{:else}
+    <ul data-testid="manga-list">
+        {#each mangas as m (m.id)}
+            <li>
+                <a href="/manga/{m.id}">{m.title}</a>
+                {#if m.author}<span> — {m.author}</span>{/if}
+            </li>
+        {/each}
+    </ul>
+{/if}

frontend/svelte.config.js

@@ -0,0 +1,12 @@
+import adapter from '@sveltejs/adapter-node';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+    preprocess: vitePreprocess(),
+    kit: {
+        adapter: adapter({ out: 'build' })
+    }
+};
+
+export default config;

frontend/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "./.svelte-kit/tsconfig.json",
+    "compilerOptions": {
+        "allowJs": true,
+        "checkJs": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "skipLibCheck": true,
+        "sourceMap": true,
+        "strict": true,
+        "moduleResolution": "bundler",
+        "types": ["@testing-library/jest-dom", "vitest/globals"]
+    }
+}

frontend/vite.config.ts

@@ -0,0 +1,20 @@
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    plugins: [sveltekit()],
+    server: {
+        port: 5173,
+        proxy: {
+            '/api': {
+                target: process.env.BACKEND_URL ?? 'http://localhost:8080',
+                changeOrigin: true
+            }
+        }
+    },
+    test: {
+        environment: 'jsdom',
+        include: ['src/**/*.test.ts'],
+        globals: false
+    }
+});