Backend Express Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• backend/api/index.ts
• README.md
• CHANGELOG.md
• extension/src/background/api-client.ts
• backend/lib/tests/openrouter.test.ts
• tasks/todo.md

Introduction

The Oddity 1 backend is a Node.js API built using the Express framework. It provides the core intelligence layer for the Chrome extension, handling AI-driven text annotation, user preference management, and integration with third-party services like Supabase and OpenRouter. The architecture is designed to be deployable on Vercel, utilizing a modular routing structure to manage different functional domains such as document sketches, PDF processing, and Google Docs integrations.

The backend acts as a bridge between the frontend extension and the Large Language Models (LLMs), providing structured data generation, caching mechanisms with a 30-day TTL, and rate limiting based on user subscription tiers.

Sources: README.md:16-20, CHANGELOG.md:85-92, backend/api/index.ts:1-35

Core System Components

The architecture consists of several specialized layers that handle request processing, security, and external integrations.

Middleware and Security

The application employs global and route-specific middleware to ensure secure and efficient data handling:

• CORS Configuration: Restricts access to specific origins, primarily app.oddity1.com and the Chrome extension ID.
• Authentication: Uses authMiddleware via Supabase to protect sensitive routes.
• Body Parsing: Implements standard JSON parsing with a 2MB limit, while extending the limit to 4.5MB for PDF conversion tasks to accommodate larger binary payloads.
• Process Guards: Implements registerProcessGuards to manage application lifecycle and fatal errors.

Sources: backend/api/index.ts:37-65, CHANGELOG.md:100-103

Service Integrations

The backend integrates with multiple external providers to fulfill its feature set:

• Supabase: Handles authentication (Email/OAuth), profile storage, and database management.
• OpenRouter/OpenAI: Generates structured annotations with varying intensity levels.
• Stripe: Manages subscriptions and webhooks for payment processing.
• Marker API: Handles PDF-to-HTML conversion.

Sources: README.md:27-32, CHANGELOG.md:118-124, tasks/todo.md:180-185

Data Flow and API Structure

The following diagram illustrates the request lifecycle from the Extension to the Backend and external LLM providers.

API Endpoints Summary

Endpoint	Method	Auth	Description
/api/annotate	POST	Yes	Generates AI annotations (cached by content hash).
/api/sketch	POST	Yes	Generates a structured summary or rebuttal of text.
/api/annotations	GET/POST/PUT	Yes	Manages user-generated (manual) annotations.
/api/convert-pdf	POST	Yes	Converts PDF binary to HTML via Marker API.
/api/user/preferences	GET/PUT	Yes	Manages user settings (intensity, font, etc.).
/api/health	GET	No	Basic server status check.

Sources: README.md:215-227, backend/api/index.ts:70-93

Annotation and Sketch Logic

The backend processes two primary types of AI requests: Annotations and Sketches.

Annotation Generation

Annotations are generated using system prompts defined in backend/config/prompts.json. The system supports two primary modes:

1. Overview: Generates a high-level summary and structural map of the text.
2. Depth: Provides critical analysis, caveats, and provocations based on a chosen personality (Terry, Jerry, or Sally).

The API supports Server-Sent Events (SSE) for progressive rendering. If a stream fails before completion, the system falls back to a buffered JSON generation to ensure reliability.

Sources: backend/config/prompts.json:1-10, backend/lib/tests/openrouter.test.ts:122-135, extension/src/background/api-client.ts:135-150

Sketch Pad System

The Sketch Pad system allows users to interact with text through custom prompts or pre-defined modes. It includes a strict "non-invention" guard when no user reactions are provided, ensuring the LLM grounds its output solely in the source text.

Sources: backend/lib/tests/openrouter.test.ts:250-265, extension/src/background/api-client.ts:240-250

Caching and Performance

To optimize inference speed and reduce LLM costs, the backend implements a database-level caching strategy:

• Key Strategy: AI annotations are keyed by (content_hash, intensity).
• TTL: Cache entries have a 30-day Time-To-Live (TTL).
• Session Cache: The extension service worker maintains a chrome.storage.session cache for instant revisits within the same session.

Sources: README.md:239-242, tasks/todo.md:144-150, extension/src/background/index.ts:370-385

Conclusion

The Backend Express Architecture provides a robust, scalable foundation for the Oddity 1 ecosystem. By centralizing complex AI logic, authentication, and caching on the server, the system maintains high performance while ensuring secure and consistent user experiences across different web environments and document types.