insta-recipe/docs/CODE_STYLE.md

Code Style Guide

Last Updated: 2026-02-15T00:00:00.000Z
JIRA: RECIPE-0001

---

Language & Version

Primary Language: TypeScript
Version: 5.9.3
Framework: SvelteKit 2.48.5 with Svelte 5.43.8
Node.js: 22+ (LTS)

---

Naming Conventions

Files & Directories

SvelteKit Route Files

• Route pages: +page.svelte
• Route servers: +server.ts
• Route layouts: +layout.svelte
• Type definitions: $types.ts (auto-generated)

Example:

src/routes/api/queue/
├── [id]/
│   ├── +server.ts
│   └── retry/
│       └── +server.ts
├── stream/
│   └── +server.ts
└── +server.ts

Library Files

• PascalCase for classes and managers: QueueManager.ts, PushNotificationService.ts
• kebab-case for utilities and configs: tandoor-config.ts, instagram-url.ts
• lowercase for general modules: browser.ts, extraction.ts, parser.ts

Examples from codebase:

• src/lib/server/queue/QueueManager.ts
• src/lib/server/tandoor-config.ts
• src/lib/client/PushNotificationManager.ts

Test Files

Pattern: <name>.spec.ts or <name>.test.ts

Examples:

• queue-manager.spec.ts
• instagram-url-validation.spec.ts
• page.svelte.spec.ts

Variables & Functions

Variables

• camelCase for local variables and parameters
• SCREAMING_SNAKE_CASE for constants

Examples:

// From QueueManager.ts
private items: Map<string, QueueItem> = new Map();
private subscribers: Set<QueueUpdateCallback> = new Set();

// From parser.ts
const RECIPE_DETECTION_PROMPT = "...";
const RECIPE_EXTRACTION_PROMPT = "...";

// Local variables
const now = new Date().toISOString();
const unsubscribe = queueManager.subscribe(callback);

Functions

• camelCase for function names
• Descriptive action verbs: enqueue, extractRecipe, uploadRecipeImage

Examples:

// From QueueManager.ts
enqueue(url: string): QueueItem { ... }
dequeue(): QueueItem | null { ... }
updateStatus(id: string, status: QueueItemStatus): void { ... }

// From extraction.ts
export async function extractTextAndThumbnail(
  url: string,
  onProgress?: ProgressCallback
): Promise<ExtractedContent> { ... }

// From parser.ts
export async function extractRecipe(text: string): Promise<Recipe> { ... }

Types & Interfaces

Interfaces & Types

• PascalCase for interface names
• Prefix with I is NOT used
• Exported types use export type or export interface

Examples:

// From queue/types.ts
export interface QueueItem {
	id: string;
	url: string;
	status: QueueItemStatus;
	enqueuedAt: string;
	// ...
}

export interface QueueStatusUpdate {
	type: string;
	itemId: string;
	status: QueueItemStatus;
	// ...
}

export type QueueItemStatus = 'pending' | 'in_progress' | 'completed' | 'failed';

// From extraction.ts
export interface ExtractedContent {
	text: string;
	thumbnailUrl?: string;
}

export type ProgressCallback = (event: ProgressEvent) => void;

Zod Schemas

• PascalCase with Schema suffix
• Inferred types without suffix

Examples:

// From parser.ts
const RecipeSchema = z.object({
	name: z.string(),
	description: z.string(),
	servings: z.number()
	// ...
});

export type Recipe = z.infer<typeof RecipeSchema>;

// From tandoor.ts
const TandoorRecipeSchema = z.object({
	// ...
});

export type TandoorRecipe = z.infer<typeof TandoorRecipeSchema>;

Classes

Class Names

• PascalCase for class names
• Descriptive suffixes: Manager, Service, Processor, Handler

Examples:

// From QueueManager.ts
export class QueueManager {
	private items: Map<string, QueueItem> = new Map();
	// ...
}

// From QueueProcessor.ts
export class QueueProcessor {
	private processing: Set<string> = new Set();
	// ...
}

// From PushNotificationService.ts
class PushNotificationService {
	private subscriptions: Map<string, PushSubscription> = new Map();
	// ...
}

Singleton Export Pattern

// Class definition
export class QueueManager {
	// Implementation
}

// Singleton instance export
export const queueManager = new QueueManager();

---

Indentation & Formatting

General Rules

• Indentation: 2 spaces (enforced by Prettier)
• No tabs
• Max line length: 100 characters (soft limit, not enforced)
• Trailing commas: Yes (multiline)
• Semicolons: Yes (always)
• Single quotes: Yes (enforced by Prettier)

Code Examples

Function Declarations

// From QueueManager.ts
enqueue(url: string): QueueItem {
  const now = new Date().toISOString();
  const item: QueueItem = {
    id: uuidv4(),
    url,
    status: 'pending',
    enqueuedAt: now,
    createdAt: now,
    updatedAt: now,
    phases: [
      { name: 'extraction', status: 'pending' },
      { name: 'parsing', status: 'pending' },
      { name: 'uploading', status: 'pending' }
    ],
    logs: [],
    progressEvents: [],
    retryCount: 0,
    maxRetries: 3
  };

  this.items.set(item.id, item);
  return item;
}

Async Functions

// From extraction.ts
export async function extractTextAndThumbnail(
	url: string,
	onProgress?: ProgressCallback
): Promise<ExtractedContent> {
	const browser = await getBrowser();
	const context = await createBrowserContext(browser);
	const page = await context.newPage();

	try {
		await page.goto(url, { waitUntil: 'networkidle' });
		// ...
	} finally {
		await context.close();
	}
}

Object Destructuring

// From route handlers
export const POST: RequestHandler = async ({ request }) => {
	const { url } = await request.json();
	// ...
};

export const GET: RequestHandler = async ({ params }) => {
	const { id } = params;
	// ...
};

---

Import Patterns

Import Order

1. External dependencies (Node.js built-ins, npm packages)
2. SvelteKit imports ($lib, $app, $env)
3. Relative imports (./ , ../)
4. Type imports (separate from value imports when beneficial)

Example:

// From QueueProcessor.ts

// External dependencies
import { v4 as uuidv4 } from 'uuid';

// SvelteKit imports
import { queueManager } from './QueueManager';
import { extractTextAndThumbnail } from '$lib/server/extraction';
import { extractRecipe } from '$lib/server/parser';
import { uploadRecipeWithIngredientsDTO, uploadRecipeImage } from '$lib/server/tandoor';
import { pushNotificationService } from '$lib/server/notifications/PushNotificationService';
import { queueConfig } from './config';

// Type imports
import type { ProgressEvent } from '$lib/server/extraction';
import type { QueueItem } from './types';

Import Styles

Named Imports (Preferred)

import { json } from '@sveltejs/kit';
import { queueManager } from '$lib/server/queue/QueueManager';
import { validateInstagramUrl } from '$lib/server/validation/instagram-url';

Type-Only Imports

import type { RequestHandler } from './$types';
import type { QueueItem, QueueItemStatus } from './types';

Default Imports

import OpenAI from 'openai';
import fs from 'fs';
import path from 'path';

Export Patterns

Named Exports (Preferred)

// Export functions
export async function extractRecipe(text: string): Promise<Recipe> { ... }

// Export classes
export class QueueManager { ... }

// Export constants
export const queueConfig = { ... };

// Export types
export type Recipe = z.infer<typeof RecipeSchema>;
export interface QueueItem { ... }

Singleton Pattern Export

// Define class
export class QueueManager { ... }

// Export singleton instance
export const queueManager = new QueueManager();

---

Comments & Documentation

JSDoc Style

Used extensively for public APIs and exported functions.

Function Documentation:

/**
 * Add URL to processing queue
 *
 * @param url - Instagram URL to process
 * @returns Newly created queue item
 *
 * @example
 * ```typescript
 * const item = queueManager.enqueue('https://instagram.com/p/abc123');
 * console.log('Queued with ID:', item.id);
 * ```
 */
enqueue(url: string): QueueItem {
  // Implementation
}

Class Documentation:

/**
 * Singleton queue manager for processing Instagram URLs
 *
 * Features:
 * - FIFO queue with unique IDs
 * - Status tracking and updates
 * - Progress event accumulation
 * - Retry support for failed items
 * - Pub/sub for real-time updates
 *
 * @example
 * ```typescript
 * import { queueManager } from './QueueManager';
 *
 * // Add item to queue
 * const item = queueManager.enqueue('https://instagram.com/p/abc123');
 * ```
 */
export class QueueManager {
	// Implementation
}

Module-Level Documentation:

/**
 * Queue Manager - Core queue operations and event management
 *
 * Manages an in-memory queue of Instagram URL processing jobs.
 * Provides CRUD operations and pub/sub mechanism for queue updates.
 *
 * Architecture: Domain Layer (Hexagonal Architecture)
 * - Port: Defines queue operations interface
 * - Implementation: In-memory Map-based storage
 */

Inline Comments

Single-line Comments

// Set restrictive permissions
fs.chmodSync(authFile, 0o600);

// FIFO order - get oldest pending item
const pendingItems = Array.from(this.items.values()).filter((item) => item.status === 'pending');

Block Comments (Avoided)

Single-line comments preferred. Block comments used only for large comment blocks or temporarily disabling code during development.

TODO Comments

// TODO: Add retry logic with exponential backoff
// FIXME: Handle race condition when multiple workers dequeue

---

TypeScript Patterns

Type Safety

Strict Mode Enabled

// tsconfig.json
{
	"compilerOptions": {
		"strict": true,
		"forceConsistentCasingInFileNames": true
	}
}

Type Annotations

// Explicit return types for public functions
export async function extractRecipe(text: string): Promise<Recipe> { ... }

// Explicit parameter types
function processItem(item: QueueItem, config: QueueConfig): void { ... }

// Type inference for local variables (acceptable)
const items = queueManager.getAll(); // Type inferred

Union Types

export type QueueItemStatus = 'pending' | 'in_progress' | 'completed' | 'failed';

export type ProcessingPhase = 'extraction' | 'parsing' | 'uploading';

export type ProgressEventType = 'status' | 'method' | 'retry' | 'error' | 'thumbnail' | 'complete';

Generics

// Generic function
async function fetchFromTandoor<T>(
	url: string,
	options: Partial<RequestInit> = { method: 'GET' }
): Promise<{ ok: boolean; data?: T; error?: string }> {
	// Implementation
}

---

Svelte 5 Patterns

Runes (Reactivity)

$state (Reactive Variables)

<script lang="ts">
  let count = $state(0);
  let items = $state<QueueItem[]>([]);
</script>

$props (Component Props)

<script lang="ts">
  let {
    recipe = null,
    tandoorEnabled = false,
    onRetry,
    onImportToTandoor
  } = $props<{
    recipe: Recipe | null;
    tandoorEnabled: boolean;
    onRetry: () => void;
    onImportToTandoor: () => void;
  }>();
</script>

$derived (Computed Values)

<script lang="ts">
  let count = $state(0);
  let double = $derived(count * 2);
</script>

$effect (Side Effects)

<script lang="ts">
  let url = $state('');

  $effect(() => {
    console.log('URL changed:', url);
  });
</script>

Component Structure

<script lang="ts">
  // Imports
  import { onMount } from 'svelte';

  // Props
  let { items } = $props<{ items: Item[] }>();

  // State
  let loading = $state(false);

  // Derived state
  let count = $derived(items.length);

  // Functions
  function handleClick() {
    // ...
  }

  // Effects
  $effect(() => {
    // Side effects
  });
</script>

<!-- Template -->
<div>
  <!-- Markup -->
</div>

<!-- Styles -->
<style>
  /* Component-scoped styles */
</style>

---

Error Handling

Custom Error Classes

// From api/errors.ts
export class ValidationError extends Error {
	constructor(message: string) {
		super(message);
		this.name = 'ValidationError';
	}
}

export class NotFoundError extends Error {
	constructor(resource: string) {
		super(`${resource} not found`);
		this.name = 'NotFoundError';
	}
}

export class ConflictError extends Error {
	constructor(message: string) {
		super(message);
		this.name = 'ConflictError';
	}
}

Try-Catch Pattern

export const POST: RequestHandler = async ({ request }) => {
	try {
		const { url } = await request.json();

		if (!url) {
			throw new ValidationError('URL is required');
		}

		const item = queueManager.enqueue(url);
		return json(item, { status: 201 });
	} catch (error) {
		return handleApiError(error);
	}
};

---

Linting Configuration

ESLint

Config: eslint.config.js

• Base: @eslint/js recommended
• TypeScript: typescript-eslint recommended
• Svelte: eslint-plugin-svelte recommended
• Formatting: eslint-config-prettier

Rules:

{
  rules: {
    "no-undef": 'off'  // TypeScript handles this
  }
}

Prettier

Config: .prettierrc

{
	"useTabs": false,
	"singleQuote": true,
	"trailingComma": "es5",
	"printWidth": 100,
	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"]
}

---

Testing Conventions

Test Structure

import { describe, it, expect, beforeEach, afterEach } from 'vitest';

describe('QueueManager', () => {
	let manager: QueueManager;

	beforeEach(() => {
		manager = new QueueManager();
	});

	it('should enqueue items', () => {
		const item = manager.enqueue('https://instagram.com/p/test');
		expect(item.status).toBe('pending');
	});

	it('should dequeue items in FIFO order', () => {
		manager.enqueue('url1');
		manager.enqueue('url2');

		const first = manager.dequeue();
		expect(first?.url).toBe('url1');
	});
});

Mock Pattern

vi.mock('$lib/server/extraction', () => ({
	extractTextAndThumbnail: vi.fn().mockResolvedValue({
		text: 'Mock text',
		thumbnailUrl: 'https://example.com/thumb.jpg'
	})
}));

---

File Headers

Module Documentation Pattern

Every major module includes a header comment:

/**
 * Module Name - Brief Description
 *
 * Detailed description of the module's purpose and functionality.
 *
 * Architecture: Layer Name (Hexagonal Architecture)
 * - Port: Description of port interface
 * - Implementation: Description of concrete implementation
 */

Example:

/**
 * Queue Manager - Core queue operations and event management
 *
 * Manages an in-memory queue of Instagram URL processing jobs.
 * Provides CRUD operations and pub/sub mechanism for queue updates.
 *
 * Architecture: Domain Layer (Hexagonal Architecture)
 * - Port: Defines queue operations interface
 * - Implementation: In-memory Map-based storage
 */

---

Additional Conventions

Environment Variables

import { env } from '$env/dynamic/private';

const apiKey = env.OPENAI_API_KEY;
const tandoorUrl = env.TANDOOR_URL || null;

Date Handling

ISO8601 strings throughout the application:

const now = new Date().toISOString();
// Output: "2026-02-15T12:30:45.123Z"

Null vs Undefined

• null: Intentional absence of value
• undefined: Not yet initialized or optional parameters
• Prefer null for API responses and data structures

Async/Await

Always preferred over Promise chains:

// Preferred
async function fetchData() {
	const response = await fetch(url);
	const data = await response.json();
	return data;
}

// Avoid
function fetchData() {
	return fetch(url)
		.then((response) => response.json())
		.then((data) => data);
}

---

Document Version: 1.0
Enforced By: ESLint, Prettier, TypeScript
Generated by: Initializer Agent