Guide du développeur

Comment configurer un environnement de développement local et contribuer au code de SnapOtter.

Prérequis

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (requis pour Postgres + Redis en local, les builds de conteneur et les fonctionnalités d'IA)
• Git

Python 3.11+ n'est nécessaire que si vous travaillez sur le sidecar IA/ML (suppression d'arrière-plan, agrandissement, OCR).

Configuration

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

Cela démarre deux serveurs de développement :

Service	URL	Notes
Frontend	http://localhost:1351	Serveur de développement Vite, proxifie /api
Backend	http://localhost:13490	API Fastify (accédée via le proxy)

Ouvrez http://localhost:1351 dans votre navigateur. Connectez-vous avec admin / admin. Il vous sera demandé de changer le mot de passe à la première connexion.

Structure du projet

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

Commandes

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

Conventions de code

• Guillemets doubles, points-virgules, indentation de 2 espaces (imposés par Biome)
• Modules ES dans tous les workspaces
• Commits conventionnels pour semantic-release
• Zod pour toute validation d'entrée de l'API
• Aucune modification des fichiers de configuration de Biome, TypeScript ou de l'éditeur. Corrigez le code, pas le linter.

Base de données

PostgreSQL 17 via Drizzle ORM (pg-core). Le développement local nécessite que Postgres et Redis soient en cours d'exécution - démarrez-les avec :

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

Cela vous donne Postgres sur le port 5432 et Redis sur le port 6379. Générez ensuite et appliquez les migrations :

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

Le schéma est défini dans apps/api/src/db/schema.ts. Tables : users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog.

Ajouter un nouvel outil

Chaque outil suit le même schéma. Voici un exemple minimal.

1. Route backend

Créez 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",
      };
    },
  });
}

Puis enregistrez-la dans apps/api/src/routes/tools/index.ts.

2. Composant de paramètres frontend

Créez 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>
  );
}

Puis enregistrez-le dans le registre d'outils frontend à 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 }],

Modes d'affichage : "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone".

3. Entrée i18n

Ajoutez à packages/shared/src/i18n/en.ts :

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

4. Tests

Ajoutez un attribut data-testid à votre bouton d'action (comme montré ci-dessus) afin que les tests e2e puissent le cibler de manière fiable.

Builds Docker

Construisez l'image de production complète en local :

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

Utilisez les cache mounts de BuildKit pour des reconstructions plus rapides :

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

Domaines de la version Release

SnapOtter possède intentionnellement trois domaines de version. Ne copiez pas un domaine dans un autre lors d'une version :

• La version de l'application couvre le manifeste racine, tous les packages d'espace de travail privé et APP_VERSION. Semantic-release fournit cette valeur et pnpm version:sync <version> met à jour chaque espace de travail avant la version d'une application.
• OpenAPI info.version est le contrat public stable majeur API. Toutes les spécifications localisées restent sur <major>.0.0 pour les versions d'applications compatibles et ne changent que lorsque le contrat API passe à une nouvelle version majeure.
• docker/feature-manifest.json conserve imageVersion: 2.0.0 comme époque de stockage immuable des ensembles de fonctionnalités héritées. Ces chemins d'archives v2 ne sont pas des versions de packages d'application. Accurate OCR utilise le format d'exécution v3 et enregistre séparément la provenance de la version de l'application.

tests/unit/infra/release-version-policy.test.ts applique ces limites. Un nouveau domaine de version ou une nouvelle migration doit mettre à jour ce contrat et la conception de migration d'artefact pertinente ensemble. Les valeurs indépendantes API et du bundle hérité résident dans config/release-version-policy.json ; la synchronisation des versions d'application ne doit jamais réécrire implicitement ce fichier de stratégie.

Variables d'environnement

Consultez le Guide de configuration pour la liste complète. Les principales pour le développement :

Variable	Par défaut	Description
AUTH_ENABLED	true	Activer/désactiver l'authentification
DEFAULT_USERNAME	admin	Nom d'utilisateur admin par défaut
DEFAULT_PASSWORD	admin	Mot de passe admin par défaut
SKIP_MUST_CHANGE_PASSWORD	false	Ignorer le changement forcé de mot de passe (CI/dev uniquement)
RATE_LIMIT_PER_MIN	1000	Limite de débit de l'API par minute (0 = désactivée)
MAX_UPLOAD_SIZE_MB	100	Taille d'envoi maximale en Mo (0 = illimité)