Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
69 lines (44 loc) · 4.35 KB

ARCHITECTURE.md

File metadata and controls

69 lines (44 loc) · 4.35 KB
Raw

System Architecture

This document describes the technical architecture and design principles of the Vouch platform.

Monorepo Strategy

Vouch is architected as a pnpm monorepo managed by Turborepo. This allows for unified type safety, shared logic, and efficient build processes across multiple client and server applications.

Core Structure

  • apps/web: A Next.js 15 application using the App Router. It serves as the primary dashboard for users to manage their analysis history and run new reports via URL.
  • apps/api: A high-performance TypeScript API built with Hono and running on the Bun runtime. It handles all AI processing, authentication, and database operations.
  • apps/extension: A Manifest V3 Chrome Extension that provides the sidebar interface for real-time browsing analysis.
  • packages/sdk: A shared package containing the API client and authentication helpers used by both the web and extension apps to maintain a synchronized state.
  • packages/types: A central location for all domain models and API request/response types, ensuring end-to-end type safety.

Backend Architecture

The backend is designed for high concurrency and low latency, leveraging the Bun runtime's speed and Hono's lightweight routing.

AI Service Pipeline

The AI engine is built on Google Gemini 1.5 Flash. It follows a modular service pattern:

  1. Verification Service: Handles claim extraction and fact-checking. It utilizes Google Search grounding to verify claims against live web data, significantly reducing model hallucinations.
  2. Analysis Service: Performs deep linguistic analysis to detect bias direction, manipulative language, and the presentation of opinions as objective facts.
  3. Chat Service: Maintains a context-aware conversational state, allowing users to ask follow-up questions about the current article's content.

Real-time Communication

Vouch uses Server-Sent Events (SSE) for streaming AI responses. This provides a superior user experience compared to standard polling or long-lived fetch requests, as it allows the UI to render AI "thoughts" and tokens as they are generated by the model.

Data Layer

  • ORM: Prisma is used for type-safe database interactions.
  • Database: PostgreSQL (Neon) stores user profiles, persistent analysis history, and session tokens.
  • Caching: Upstash Redis is utilized for rate limiting and caching frequently accessed verification results.

Extension Architecture

The Chrome Extension is a Manifest V3 application built with React 18 and Vite.

Core Components

  • Sidebar (SidePanel API): A persistent UI that stays with the user as they navigate across tabs, providing a continuous research workspace.
  • Content Scripts: Responsible for extracting page content using the Mozilla Readability algorithm and injecting live highlights back into the original webpage.
  • Context Menu: Provides the "Vouch This" entry point, allowing users to trigger targeted analysis on highlighted text.

Cross-Application Synchronization

A key challenge in Vouch was synchronizing the authentication state between the standalone web dashboard and the browser extension.

Linking Mechanism

  1. The user logs into the web dashboard.
  2. The user generates a secure 6-digit link code in their dashboard settings.
  3. The extension captures this code and exchanges it via the API for a valid JWT session.
  4. The packages/sdk maintains this session across both environments, ensuring that an analysis started in the extension is immediately visible in the web dashboard.

Design Goals and Technical Benchmarks

The architecture of Vouch is optimized to meet the following technical performance and reliability standards:

  • AI Precision: Cites 5+ live web sources per verified claim through real-time search grounding, minimizing factual inaccuracies.
  • Analysis Depth: Quantifies bias as a numeric score (0-100) with granular detection of sentence-level manipulation.
  • Persistence: Maintains per-article chat history with a 72-hour expiry for guests and permanent storage for authenticated users.
  • Low Latency: Optimized data pipelines enable a single right-click to trigger a fully sourced fact report in under 3 seconds.
  • Engineering Integrity: Achieves 100% end-to-end type safety using Zod and TypeScript across all monorepo packages.
  • Zero-Config UX: Operates on any webpage with zero user-provided context by leveraging advanced DOM extraction and metadata analysis.