Entwicklerleitfaden

Wie man eine lokale Entwicklungsumgebung einrichtet und Code zu SnapOtter beiträgt.

Voraussetzungen

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (erforderlich für lokales Postgres + Redis, Container-Builds und AI-Features)
• Git

Python 3.11+ wird nur benötigt, wenn du am AI/ML-Sidecar arbeitest (Hintergrundentfernung, Hochskalierung, OCR).

Setup

git clone https://github.com/snapotter-hq/snapotter.git
cd snapotter
docker compose -f docker-compose.dev.yml up -d   # start Postgres + Redis
pnpm install
pnpm dev

Dies startet zwei Dev-Server:

Dienst	URL	Hinweise
Frontend	http://localhost:1351	Vite-Dev-Server, proxyt /api
Backend	http://localhost:13490	Fastify-API (über Proxy erreichbar)

Öffne http://localhost:1351 in deinem Browser. Melde dich mit admin / admin an. Bei der ersten Anmeldung wirst du aufgefordert, das Passwort zu ändern.

Projektstruktur

apps/
  api/              Fastify backend
  web/              Vite + React frontend
  docs/             VitePress documentation (this site)
packages/
  shared/           Constants, types, i18n strings
  image-engine/     Sharp-based image operations
  media-engine/     FFmpeg spawn + progress parsing
  doc-engine/       qpdf, LibreOffice, ghostscript wrappers
  ai/               Python sidecar bridge for ML models
tests/
  unit/             Vitest unit tests
  integration/      Vitest integration tests (full API)
  e2e/              Playwright end-to-end specs
  fixtures/         Small test images

Befehle

pnpm dev                # start frontend + backend
pnpm build              # build all workspaces
pnpm typecheck          # TypeScript check across monorepo
pnpm lint               # Biome lint + format check
pnpm lint:fix           # auto-fix lint + format
pnpm test               # unit + integration tests
pnpm test:unit          # unit tests only
pnpm test:integration   # integration tests only
pnpm test:e2e           # Playwright e2e tests
pnpm test:coverage      # tests with coverage report

Code-Konventionen

• Doppelte Anführungszeichen, Semikolons, Einrückung mit 2 Leerzeichen (durch Biome erzwungen)
• ES-Module in allen Workspaces
• Conventional Commits für semantic-release
• Zod für alle API-Eingabevalidierungen
• Keine Änderungen an Biome-, TypeScript- oder Editor-Konfigurationsdateien. Behebe den Code, nicht den Linter.

Datenbank

PostgreSQL 17 über Drizzle ORM (pg-core). Die lokale Entwicklung erfordert ein laufendes Postgres und Redis - starte sie mit:

docker compose -f docker-compose.dev.yml up -d

Dies stellt dir Postgres auf Port 5432 und Redis auf Port 6379 bereit. Generiere und wende dann die Migrationen an:

cd apps/api
npx drizzle-kit generate   # generate a migration from schema changes
npx drizzle-kit migrate    # apply pending migrations

Das Schema ist in apps/api/src/db/schema.ts definiert. Tabellen: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Ein neues Tool hinzufügen

Jedes Tool folgt demselben Muster. Hier ein minimales Beispiel.

1. Backend-Route

Erstelle apps/api/src/routes/tools/my-tool.ts:

import { z } from "zod";
import type { FastifyInstance } from "fastify";
import { createToolRoute } from "../tool-factory.js";

const settingsSchema = z.object({
  intensity: z.number().min(0).max(100).default(50),
});

export function registerMyTool(app: FastifyInstance) {
  createToolRoute(app, {
    toolId: "my-tool",
    settingsSchema,
    async process(inputBuffer, settings, filename) {
      // Use sharp or other libraries to process the image
      const sharp = (await import("sharp")).default;
      const result = await sharp(inputBuffer)
        // ... your processing logic
        .toBuffer();

      return {
        buffer: result,
        filename: filename.replace(/\.[^.]+$/, ".png"),
        contentType: "image/png",
      };
    },
  });
}

Registriere es dann in apps/api/src/routes/tools/index.ts.

2. Frontend-Einstellungskomponente

Erstelle apps/web/src/components/tools/my-tool-settings.tsx:

import { useState } from "react";
import { useToolProcessor } from "@/hooks/use-tool-processor";
import { useFileStore } from "@/stores/file-store";

export function MyToolSettings() {
  const { files } = useFileStore();
  const { processFiles, processing, error, downloadUrl } =
    useToolProcessor("my-tool");

  const [intensity, setIntensity] = useState(50);

  const handleProcess = () => {
    processFiles(files, { intensity });
  };

  return (
    <div className="space-y-4">
      {/* your controls here */}
      <button
        type="button"
        onClick={handleProcess}
        disabled={files.length === 0 || processing}
        data-testid="my-tool-submit"
        className="w-full py-2.5 rounded-lg bg-primary text-primary-foreground font-medium disabled:opacity-50"
      >
        Process
      </button>
    </div>
  );
}

Registriere es dann in der Frontend-Tool-Registry unter apps/web/src/lib/tool-registry.tsx:

// Add the lazy import
const MyToolSettings = lazy(() =>
  import("@/components/tools/my-tool-settings").then((m) => ({
    default: m.MyToolSettings,
  })),
);

// Add to the toolRegistry Map
["my-tool", { displayMode: "before-after", Settings: MyToolSettings }],

Anzeigemodi: "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone".

3. i18n-Eintrag

Füge zu packages/shared/src/i18n/en.ts hinzu:

"my-tool": {
  name: "My Tool",
  description: "Short description of what this tool does",
},

4. Tests

Füge deinem Aktions-Button ein data-testid-Attribut hinzu (wie oben gezeigt), damit e2e-Tests ihn zuverlässig ansteuern können.

5. Visuelle Baselines

Die Screenshot-Tests erlauben null geänderte Pixel, und ein neues Tool ändert, was sie rendern: die Tool-Zahlen auf der Startseite und im Katalog, eine neue Karte im Raster und eine eigene Seite, an der tests/e2e/gui-visual-tools.spec.ts mit "snapshot doesn't exist" scheitert, bis sie eine Baseline hat. Aktualisiere die Baselines im selben PR wie das Tool, damit der nächtliche visuelle Vergleich grün bleibt.

Die CI erzeugt sowohl die linux- (ubuntu-latest) als auch die darwin-Baselines (macos-latest). Pushe deinen Branch und starte die Aktualisierung darauf:

gh workflow run update-visual-baselines.yml --ref <your-branch> -f update_snapshots=changed

Jeder Betriebssystem-Zweig lädt ein Artefakt visual-baselines-linux-<run-id>-<attempt> bzw. visual-baselines-darwin-<run-id>-<attempt> hoch und öffnet einen Draft-PR (chore/visual-baselines-linux-... und chore/visual-baselines-darwin-...) gegen main mit den neu erzeugten PNGs. In der Beschreibung jedes Draft-PRs steht ein gh run download-Befehl; führe beide im Wurzelverzeichnis deines Checkouts aus, um die PNGs in deinen Branch zu holen, committe sie und schließe die Draft-PRs. Nimm stattdessen update_snapshots=all, wenn changed einen Screenshot verpasst, der sich deiner Erwartung nach ändern sollte. Zum Starten brauchst du Schreibrechte am Repository; liegt dein Branch in einem Fork, schreib in den PR, dass er eine Baseline-Aktualisierung braucht, und ein Maintainer startet sie.

Auf einem Mac kannst du die darwin-Baselines für schnelleres Iterieren auch lokal aktualisieren:

pnpm playwright test --project=chromium-visual --project=mobile-chromium --project=tablet-chromium --update-snapshots=changed

Öffne in jedem Fall jedes neue oder geänderte PNG, bevor du es committest: Eine Baseline hält fest, was gerendert wurde, kaputt oder nicht.

Ein Release braucht nichts davon. Die App-Version ist in jedem Screenshot, der sie zeigt, maskiert, daher ändert ein Versionssprung keine Baseline.

Docker-Builds

Baue das vollständige Produktions-Image lokal:

docker build -f docker/Dockerfile -t snapotter:latest .

Verwende BuildKit-Cache-Mounts für schnellere Rebuilds:

DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile -t snapotter:latest .

Release-Versionsdomänen

SnapOtter verfügt absichtlich über drei Versionsdomänen. Kopieren Sie während einer Veröffentlichung nicht eine Domäne in eine andere:

• Die Anwendungsfreigabeversion deckt das Root-Manifest, alle privaten Arbeitsbereichspakete und APP_VERSION ab. Semantic-release stellt diesen Wert bereit und pnpm version:sync <version> aktualisiert jeden Arbeitsbereich vor einer Anwendungsfreigabe.
• OpenAPI info.version ist der stabile öffentliche API-Großvertrag. Alle lokalisierten Spezifikationen bleiben für kompatible Anwendungsversionen auf <major>.0.0 und ändern sich nur, wenn der API-Vertrag auf eine neue Hauptversion umgestellt wird.
• docker/feature-manifest.json behält imageVersion: 2.0.0 als unveränderliche Legacy-Feature-Bundle-Speicherepoche bei. Bei diesen v2-Archivpfaden handelt es sich nicht um Anwendungspaketversionen. Accurate OCR verwendet das Laufzeitformat v3 und zeichnet die Herkunft der Anwendungsversion separat auf.

tests/unit/infra/release-version-policy.test.ts erzwingt diese Grenzen. Eine neue Versionsdomäne oder Migration muss diesen Vertrag und das relevante Artefaktmigrationsdesign zusammen aktualisieren. Die unabhängigen API- und Legacy-Bundle-Werte befinden sich in config/release-version-policy.json; Die Synchronisierung der Anwendungsversion darf diese Richtliniendatei niemals implizit neu schreiben.

Umgebungsvariablen

Die vollständige Liste findest du im Konfigurationsleitfaden. Wichtige für die Entwicklung:

Variable	Standard	Beschreibung
AUTH_ENABLED	true	Authentifizierung aktivieren/deaktivieren
DEFAULT_USERNAME	admin	Standard-Admin-Benutzername
DEFAULT_PASSWORD	admin	Standard-Admin-Passwort
SKIP_MUST_CHANGE_PASSWORD	false	Erzwungene Passwortänderung überspringen (nur CI/Dev)
RATE_LIMIT_PER_MIN	1000	API-Ratenlimit pro Minute (0 = deaktiviert)
MAX_UPLOAD_SIZE_MB	100	Maximale Upload-Größe in MB (0 = unbegrenzt)