# siddharth-khattar/redacta architecture

> Architecture diagram of the GitHub repository siddharth-khattar/redacta, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddharth-khattar/redacta
- Repository: https://github.com/siddharth-khattar/redacta

## Overview

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: [`frontend/src/components/RedactionWorkspace.tsx`](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/RedactionWorkspace.tsx) (Workspace), [`frontend/src/App.tsx`](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/App.tsx) (App), [`frontend/src/engine/orchestrator.ts`](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/orchestrator.ts) (Orchestrator), [`frontend/src/engine/providers/registry.ts`](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/providers/registry.ts) (Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_app["App<br/>shell<br/>[App.tsx]"]
  node_landing["Landing page<br/>entry page<br/>[LandingPage.tsx]"]
  node_workspacepage["Workspace page<br/>product page<br/>[WorkspacePage.tsx]"]
  node_workspace["Workspace<br/>layout"]
  node_promptpanel["Prompt panel<br/>input panel<br/>[PromptPanel.tsx]"]
  node_pdfpanel["PDF panel<br/>document panel<br/>[PdfPanel.tsx]"]
  node_processingpanel["Processing panel<br/>status panel"]
  node_resultpanel["Result panel<br/>output panel<br/>[ResultPanel.tsx]"]
  node_downloadbar["Download bar<br/>action bar<br/>[DownloadBar.tsx]"]
  node_header["Header<br/>chrome<br/>[Header.tsx]"]
  node_apimodal["API key modal<br/>settings modal<br/>[ApiKeyModal.tsx]"]
end

subgraph group_engine["Engine layer"]
  node_redactionapi["Redaction API<br/>adapter<br/>[redaction.ts]"]
  node_orchestrator["Orchestrator<br/>pipeline<br/>[orchestrator.ts]"]
  node_pdfengine[("PDF engine<br/>mupdf wasm<br/>[pdf.ts]")]
  node_prompts["Prompts<br/>prompt set<br/>[index.ts]"]
  node_providers["Providers<br/>provider layer<br/>[registry.ts]"]
  node_pricing["Pricing<br/>metadata service<br/>[pricing.ts]"]
end

subgraph group_storage["Local persistence"]
  node_apikeys[("API keys<br/>browser storage<br/>[useProviderKeys.ts]")]
  node_pdfstore[("PDF store<br/>local blob store<br/>[pdf-store.ts]")]
end

subgraph group_external["External services"]
  node_gemini(("Gemini<br/>AI service"))
  node_openai(("OpenAI<br/>AI service"))
  node_openrouter(("OpenRouter<br/>pricing API"))
end

node_app -->|"routes to"| node_landing
node_app -->|"routes to"| node_workspacepage
node_app -->|"opens"| node_apimodal
node_workspacepage -->|"renders"| node_workspace
node_workspace -->|"contains"| node_promptpanel
node_workspace -->|"contains"| node_pdfpanel
node_workspace -->|"contains"| node_processingpanel
node_workspace -->|"contains"| node_resultpanel
node_workspace -->|"contains"| node_downloadbar
node_app -->|"uses"| node_header
node_redactionapi -->|"calls"| node_orchestrator
node_orchestrator -->|"extracts/applies"| node_pdfengine
node_orchestrator -->|"loads"| node_prompts
node_orchestrator -->|"invokes"| node_providers
node_providers -->|"connects"| node_gemini
node_providers -->|"connects"| node_openai
node_pricing -.->|"fetches from"| node_openrouter
node_apikeys -->|"supplies keys to"| node_providers
node_pdfstore -->|"restores PDFs for"| node_workspacepage
node_workspace -->|"uses"| node_redactionapi
node_app -->|"depends on"| node_pdfstore
node_app -->|"depends on"| node_apikeys

click node_app "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/App.tsx"
click node_landing "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/pages/LandingPage.tsx"
click node_workspacepage "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/pages/WorkspacePage.tsx"
click node_workspace "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/RedactionWorkspace.tsx"
click node_promptpanel "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/PromptPanel.tsx"
click node_pdfpanel "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/PdfPanel.tsx"
click node_processingpanel "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/ProcessingPanel.tsx"
click node_resultpanel "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/ResultPanel.tsx"
click node_downloadbar "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/DownloadBar.tsx"
click node_header "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/Header.tsx"
click node_apimodal "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/ApiKeyModal.tsx"
click node_redactionapi "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/api/redaction.ts"
click node_orchestrator "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/orchestrator.ts"
click node_pdfengine "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/pdf.ts"
click node_prompts "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/prompts/index.ts"
click node_providers "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/providers/registry.ts"
click node_pricing "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/pricing.ts"
click node_apikeys "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/hooks/useProviderKeys.ts"
click node_pdfstore "https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/lib/pdf-store.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_landing,node_workspacepage,node_workspace,node_promptpanel,node_pdfpanel,node_processingpanel,node_resultpanel,node_downloadbar,node_header,node_apimodal toneBlue
class node_redactionapi,node_orchestrator,node_pdfengine,node_prompts,node_providers,node_pricing toneAmber
class node_apikeys,node_pdfstore toneMint
class node_gemini,node_openai,node_openrouter toneRose
```

## Components

### Frontend app

Browser-only React workspace, pages, and UI chrome.

- [App](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/App.tsx): shell · Wires routing, theme behavior, and the API key modal. · `frontend/src/App.tsx`
- [Landing page](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/pages/LandingPage.tsx): entry page · Marketing and onboarding surface with upload CTA and trust messaging. · `frontend/src/pages/LandingPage.tsx`
- [Workspace page](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/pages/WorkspacePage.tsx): product page · Main PDF redaction workspace where prompts, processing, and results live. · `frontend/src/pages/WorkspacePage.tsx`
- [Workspace](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/RedactionWorkspace.tsx): layout · Composes the main panels into the interactive redaction flow. · `frontend/src/components/RedactionWorkspace.tsx`
- [Prompt panel](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/PromptPanel.tsx): input panel · Collects the user instruction and model choices. · `frontend/src/components/PromptPanel.tsx`
- [PDF panel](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/PdfPanel.tsx): document panel · Loads and previews PDFs in the browser. · `frontend/src/components/PdfPanel.tsx`
- [Processing panel](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/ProcessingPanel.tsx): status panel · Shows analysis and redaction progress. · `frontend/src/components/ProcessingPanel.tsx`
- [Result panel](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/ResultPanel.tsx): output panel · Presents the analyzed result and post-processing controls. · `frontend/src/components/ResultPanel.tsx`
- [Download bar](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/DownloadBar.tsx): action bar · Exposes final download and export actions. · `frontend/src/components/DownloadBar.tsx`
- [Header](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/Header.tsx): chrome · Top-level navigation and product chrome. · `frontend/src/components/Header.tsx`
- [API key modal](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/components/ApiKeyModal.tsx): settings modal · Collects and updates provider API keys. · `frontend/src/components/ApiKeyModal.tsx`

### Engine layer

Client-side document processing and AI orchestration.

- [Redaction API](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/api/redaction.ts): adapter · UI-facing adapter that invokes the redaction engine. · `frontend/src/api/redaction.ts`
- [Orchestrator](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/orchestrator.ts): pipeline · Coordinates extraction, provider analysis, and redaction application. · `frontend/src/engine/orchestrator.ts`
- [PDF engine](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/pdf.ts): mupdf wasm · Handles extraction, image detection, and redaction application in-browser. · `frontend/src/engine/pdf.ts`
- [Prompts](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/prompts/index.ts): prompt set · System prompts for redaction and pseudonymisation. · `frontend/src/engine/prompts/index.ts`
- [Providers](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/providers/registry.ts): provider layer · Provider abstraction plus Gemini and OpenAI clients. · `frontend/src/engine/providers/registry.ts`
- [Pricing](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/engine/pricing.ts): metadata service · Fetches token pricing with cached OpenRouter fallback data. · `frontend/src/engine/pricing.ts`

### Local persistence

Browser storage used for keys and PDF blobs.

- [API keys](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/hooks/useProviderKeys.ts): browser storage · Per-provider keys stored locally in the browser. · `frontend/src/hooks/useProviderKeys.ts`
- [PDF store](https://github.com/siddharth-khattar/redacta/blob/main/frontend/src/lib/pdf-store.ts): local blob store · Persists PDF data across routes using IndexedDB-style local storage. · `frontend/src/lib/pdf-store.ts`

### External services

Third-party APIs reached directly from the browser.

- **Gemini**: AI service · Direct client-side inference target for AI-assisted identification.
- **OpenAI**: AI service · Direct client-side inference target for AI-assisted identification.
- **OpenRouter**: pricing API · Auxiliary live pricing source used for model cost metadata.

## Connections

- 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.
