डेवलपर गाइड

एक स्थानीय विकास वातावरण कैसे सेट करें और SnapOtter में कोड योगदान कैसे करें।

पूर्वापेक्षाएँ

• Node.js 22.22+
• pnpm 9+ (corepack enable && corepack prepare pnpm@latest --activate)
• Docker (स्थानीय Postgres + Redis, कंटेनर बिल्ड, और AI फ़ीचर के लिए आवश्यक)
• Git

Python 3.11+ केवल तभी आवश्यक है जब आप AI/ML साइडकार (बैकग्राउंड हटाना, अपस्केलिंग, OCR) पर काम कर रहे हों।

सेटअप

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

यह दो डेव सर्वर शुरू करता है:

सेवा	URL	नोट्स
फ़्रंटएंड	http://localhost:1351	Vite डेव सर्वर, /api को प्रॉक्सी करता है
बैकएंड	http://localhost:13490	Fastify API (प्रॉक्सी के माध्यम से एक्सेस)

अपने ब्राउज़र में http://localhost:1351 खोलें। admin / admin के साथ लॉगिन करें। पहले लॉगिन पर आपको पासवर्ड बदलने के लिए कहा जाएगा।

प्रोजेक्ट संरचना

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

कमांड

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

कोड परंपराएँ

• डबल कोट्स, सेमीकोलन, 2-स्पेस इंडेंटेशन (Biome द्वारा लागू)
• सभी वर्कस्पेस में ES modules
• semantic-release के लिए Conventional commits
• सभी API इनपुट सत्यापन के लिए Zod
• Biome, TypeScript, या एडिटर कॉन्फ़िग फ़ाइलों में कोई बदलाव नहीं। कोड ठीक करें, लिंटर नहीं।

डेटाबेस

Drizzle ORM (pg-core) के माध्यम से PostgreSQL 17. स्थानीय डेव के लिए Postgres और Redis का चलना आवश्यक है - उन्हें इसके साथ शुरू करें:

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

यह आपको पोर्ट 5432 पर Postgres और पोर्ट 6379 पर Redis देता है। फिर माइग्रेशन जनरेट और लागू करें:

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

स्कीमा apps/api/src/db/schema.ts में परिभाषित है। टेबल: users, sessions, settings, jobs, apiKeys, pipelines, teams, userFiles, roles, auditLog।

एक नया टूल जोड़ना

हर टूल एक ही पैटर्न का अनुसरण करता है। यहाँ एक न्यूनतम उदाहरण है।

1. बैकएंड रूट

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

फिर इसे apps/api/src/routes/tools/index.ts में रजिस्टर करें।

2. फ़्रंटएंड सेटिंग्स कंपोनेंट

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>
  );
}

फिर इसे 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 }],

डिस्प्ले मोड: "side-by-side", "before-after", "live-preview", "no-comparison", "interactive-crop", "interactive-eraser", "no-dropzone"।

3. i18n प्रविष्टि

packages/shared/src/i18n/en.ts में जोड़ें:

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

4. टेस्ट

अपने एक्शन बटन में एक data-testid एट्रिब्यूट जोड़ें (जैसा ऊपर दिखाया गया है) ताकि e2e टेस्ट इसे विश्वसनीय रूप से लक्षित कर सकें।

Docker बिल्ड

पूर्ण प्रोडक्शन इमेज को स्थानीय रूप से बनाएँ:

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

तेज़ रीबिल्ड के लिए BuildKit कैश माउंट का उपयोग करें:

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

रिलीज़ संस्करण डोमेन

SnapOtter में जानबूझकर तीन संस्करण डोमेन हैं। रिलीज़ के दौरान एक डोमेन को दूसरे में कॉपी न करें:

• एप्लिकेशन रिलीज़ संस्करण रूट मेनिफेस्ट, सभी निजी कार्यक्षेत्र पैकेज और APP_VERSION को कवर करता है। Semantic-release यह मान प्रदान करता है, और pnpm version:sync <version> एप्लिकेशन रिलीज़ से पहले प्रत्येक कार्यक्षेत्र को अपडेट करता है।
• OpenAPI info.version स्थिर सार्वजनिक API-प्रमुख अनुबंध है। संगत एप्लिकेशन रिलीज़ के लिए सभी स्थानीयकृत विनिर्देश <major>.0.0 पर बने रहते हैं और केवल तभी बदलते हैं जब API अनुबंध एक नए प्रमुख संस्करण में चला जाता है।
• docker/feature-manifest.json, imageVersion: 2.0.0 को अपरिवर्तनीय विरासत सुविधा-बंडल भंडारण युग के रूप में रखता है। वे v2 संग्रह पथ एप्लिकेशन पैकेज संस्करण नहीं हैं। सटीक OCR रनटाइम प्रारूप v3 का उपयोग करता है और इसके एप्लिकेशन रिलीज़ उद्गम को अलग से रिकॉर्ड करता है।

tests/unit/infra/release-version-policy.test.ts इन सीमाओं को लागू करता है। एक नए संस्करण डोमेन या माइग्रेशन को उस अनुबंध और प्रासंगिक आर्टिफैक्ट माइग्रेशन डिज़ाइन को एक साथ अपडेट करना होगा। स्वतंत्र API और लीगेसी-बंडल मान config/release-version-policy.json में रहते हैं; एप्लिकेशन संस्करण सिंक्रोनाइज़ेशन को कभी भी उस नीति फ़ाइल को परोक्ष रूप से दोबारा नहीं लिखना चाहिए।

एनवायरनमेंट वेरिएबल

पूर्ण सूची के लिए Configuration guide देखें। विकास के लिए मुख्य वेरिएबल:

वेरिएबल	डिफ़ॉल्ट	विवरण
AUTH_ENABLED	true	प्रमाणीकरण सक्षम/अक्षम करें
DEFAULT_USERNAME	admin	डिफ़ॉल्ट एडमिन उपयोगकर्ता नाम
DEFAULT_PASSWORD	admin	डिफ़ॉल्ट एडमिन पासवर्ड
SKIP_MUST_CHANGE_PASSWORD	false	अनिवार्य पासवर्ड बदलाव छोड़ें (केवल CI/डेव)
RATE_LIMIT_PER_MIN	1000	प्रति मिनट API दर सीमा (0 = अक्षम)
MAX_UPLOAD_SIZE_MB	100	MB में अधिकतम अपलोड आकार (0 = असीमित)