How siddharth-khattar/redacta works
1. Repository shape
- This is a single-page frontend app under frontend/, built with React 19, TypeScript, and Vite.
- There is no backend service in the repo; the architecture is intentionally client-side only and deployable as static files.
2. Two primary user surfaces
- LandingPage.tsx is the marketing/onboarding entry with the upload CTA and trust messaging.
- WorkspacePage.tsx is the main product surface where PDFs are loaded, prompts are entered, AI runs, and results are reviewed/downloaded.
3. UI composition
- App.tsx wires routing, theme behavior, and the API key modal.
- The workspace is composed from reusable panels such as PromptPanel, PdfPanel, ProcessingPanel, ResultPanel, and DownloadBar, arranged by RedactionWorkspace.
- Supporting chrome includes Header, RedactaLogo, and visual effects like ScanOverlay and pixel-trail.
4. Core processing boundary: the engine layer
- The most important architectural boundary is src/engine/, which contains all document-processing and AI orchestration logic.
- UI components do not directly implement redaction logic; they call into the engine through the adapter in src/api/redaction.ts.
5. PDF processing path
- engine/pdf.ts handles MuPDF WebAssembly operations: PDF text extraction, image detection, and actual redaction application.
- This is the local, privacy-preserving processing boundary: PDFs are processed in-browser, and the output is generated before download without needing a server round trip.
6. AI-assisted identification path
- engine/orchestrator.ts coordinates the pipeline: extract document content, send prompts to an AI provider, interpret the response, then apply redaction/pseudonymisation.
- Prompt selection lives in engine/prompts/, with separate system prompts for redaction and pseudonymisation.
- The AI step is used to identify targets, not to rewrite the PDF itself.
7. Provider abstraction
- engine/providers/ contains a provider interface plus concrete Gemini and OpenAI clients.
- registry.ts defines the supported model catalog and provider selection, while shared.ts centralizes prompt/response handling.
- This keeps provider-specific transport details isolated from orchestration and UI.
8. Pricing and model metadata
- engine/pricing.ts fetches live token pricing from OpenRouter with a 6-hour cache and falls back to bundled defaults.
- Pricing and model capabilities are surfaced in the UI for cost estimation and model selection, but they are not required for the core redaction pipeline.
9. State and persistence boundaries
- API keys are managed per provider via useProviderKeys.ts and stored locally in the browser.
- PDF data persistence across routes is handled by lib/pdf-store.ts, which uses IndexedDB-style local storage semantics rather than a remote database.
- This separates transient workspace state, long-lived local settings, and document blobs.
10. Data flow through the app
- User uploads a PDF in the browser.
- The workspace extracts document structure locally.
- The selected provider analyzes the document based on the user’s plain-language instruction.
- MuPDF applies the chosen redaction or pseudonymisation.
- The UI presents results, lets the user adjust post-processing settings, and finally downloads the generated PDF.
11. External dependencies and trust boundary
- Only AI requests leave the browser, and they go directly from the client to Gemini or OpenAI using the user’s own API key.
- Pricing lookup calls OpenRouter, but that is auxiliary metadata, not part of document processing.
- The repo’s stated security model depends on in-browser processing, local key storage, and no backend proxy.
12. Build and deployment model
- The app is built with Vite and TypeScript, styled with Tailwind CSS, and validated with Biome plus TypeScript checks.
- Because the output is static frontend assets, it can be hosted on any static host such as Vercel, Netlify, or Cloudflare Pages.
- Makefile provides the main dev/build workflow; scripts/generate-og-image.mjs is an ancillary build script for social preview assets.
13. What to show in an architecture diagram
- Draw a browser-only application boundary containing UI, orchestration, provider adapters, and MuPDF WASM.
- Show separate external service arrows only for Gemini/OpenAI and OpenRouter.
- Mark local persistence layers separately: browser storage for API keys and IndexedDB-like storage for PDFs.
- Emphasize that PDF content is processed locally, while AI model inference is the only material network dependency.
Main entry points: RedactionWorkspace.tsx Workspace · App.tsx App · orchestrator.ts Orchestrator · registry.ts Providers
Components 22
Frontend app
Browser-only React workspace, pages, and UI chrome.
- App · Wires routing, theme behavior, and the API key modal.
frontend/src/App.tsx - Landing page · Marketing and onboarding surface with upload CTA and trust messaging.
frontend/src/pages/LandingPage.tsx - Workspace page · Main PDF redaction workspace where prompts, processing, and results live.
frontend/src/pages/WorkspacePage.tsx - Workspace · Composes the main panels into the interactive redaction flow.
frontend/src/components/RedactionWorkspace.tsx - Prompt panel · Collects the user instruction and model choices.
frontend/src/components/PromptPanel.tsx - PDF panel · Loads and previews PDFs in the browser.
frontend/src/components/PdfPanel.tsx - Processing panel · Shows analysis and redaction progress.
frontend/src/components/ProcessingPanel.tsx - Result panel · Presents the analyzed result and post-processing controls.
frontend/src/components/ResultPanel.tsx - Download bar · Exposes final download and export actions.
frontend/src/components/DownloadBar.tsx - Header · Top-level navigation and product chrome.
frontend/src/components/Header.tsx - API key modal · Collects and updates provider API keys.
frontend/src/components/ApiKeyModal.tsx
Engine layer
Client-side document processing and AI orchestration.
- Redaction API · UI-facing adapter that invokes the redaction engine.
frontend/src/api/redaction.ts - Orchestrator · Coordinates extraction, provider analysis, and redaction application.
frontend/src/engine/orchestrator.ts - PDF engine · Handles extraction, image detection, and redaction application in-browser.
frontend/src/engine/pdf.ts - Prompts · System prompts for redaction and pseudonymisation.
frontend/src/engine/prompts/index.ts - Providers · Provider abstraction plus Gemini and OpenAI clients.
frontend/src/engine/providers/registry.ts - Pricing · Fetches token pricing with cached OpenRouter fallback data.
frontend/src/engine/pricing.ts
Local persistence
Browser storage used for keys and PDF blobs.
External services
Third-party APIs reached directly from the browser.
- Gemini · Direct client-side inference target for AI-assisted identification.
- OpenAI · Direct client-side inference target for AI-assisted identification.
- OpenRouter · Auxiliary live pricing source used for model cost metadata.
Connections 22
- App → Landing page: routes to · Primary onboarding surface.
- App → Workspace page: routes to · Primary product surface.
- App → API key modal: opens · Manages provider key entry.
- Workspace page → Workspace: renders · Composes the redaction workspace.
- Workspace → Prompt panel: contains · User instruction and model selection.
- Workspace → PDF panel: contains · PDF upload and preview.
- Workspace → Processing panel: contains · Processing state and progress.
- Workspace → Result panel: contains · Review and post-processing results.
- Workspace → Download bar: contains · Final export controls.
- App → Header: uses · Shared chrome across the app.
- Redaction API → Orchestrator: calls · Adapter forwards UI actions into the pipeline.
- Orchestrator → PDF engine: extracts/applies · Local document processing boundary.
- Orchestrator → Prompts: loads · Selects the system prompt for the task.
- Orchestrator → Providers: invokes · Sends extracted content and instructions to a provider.
- Providers → Gemini: connects · Gemini transport implementation.
- Providers → OpenAI: connects · OpenAI transport implementation.
- Pricing → OpenRouter: fetches from · Auxiliary live pricing lookup.
- API keys → Providers: supplies keys to · Per-provider credentials are read locally.
- PDF store → Workspace page: restores PDFs for · Keeps uploaded documents available across routes.
- Workspace → Redaction API: uses · Workspace actions flow through the adapter.
- App → PDF store: depends on · Document state is preserved locally.
- App → API keys: depends on · Provider keys are managed in-browser.