# jikenlabs/oxid architecture

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

- Interactive diagram: https://gitdiagram.com/jikenlabs/oxid
- Repository: https://github.com/jikenlabs/oxid

## Overview

Oxid provides document ingestion, conversion and PDF-oriented analysis through a Rust server, alongside a TypeScript web-component viewer. A typical user opens a document in the viewer; the server exposes document and page operations, and the viewer presents rendered pages and interactive tools. The documented product also includes headless conversion, multiple storage connectors, document comparison, forms, annotations, PII detection, redaction and signatures. Some route-to-engine links are shown as unverified because the sampled route excerpt does not include their invocation sites.

Main entry points: [`backend/src/api/routes.rs`](https://github.com/jikenlabs/oxid/blob/main/backend/src/api/routes.rs) (HTTP API), [`frontend/src/viewer.ts`](https://github.com/jikenlabs/oxid/blob/main/frontend/src/viewer.ts) (Viewer workflow), [`backend/src/connectors/mod.rs`](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/mod.rs) (Connector registry), [`backend/src/engine/converter/mod.rs`](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/mod.rs) (Format dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and API"]
  node_api["HTTP API<br/>[routes.rs]"]
  node_auth["API keys and quotas<br/>[auth.rs]"]
  node_config["Application config<br/>[config.rs]"]
  node_cache[("Render cache<br/>[cache.rs]")]
  node_security["Security validation<br/>[security.rs]"]
end

subgraph group_storage["Document storage"]
  node_storage[("Local document storage<br/>[mod.rs]")]
  node_connector_registry["Connector registry<br/>[mod.rs]"]
  node_connector_traits["Connector contract<br/>[traits.rs]"]
  node_filesystem["Filesystem connector<br/>[filesystem.rs]"]
  node_s3["S3 connector<br/>[s3.rs]"]
  node_cmis["CMIS connector<br/>[cmis.rs]"]
end

subgraph group_conversion["Conversion and rendering"]
  node_converter["Format dispatch<br/>[mod.rs]"]
  node_office["Office conversion<br/>[office.rs]"]
  node_cad["CAD conversion<br/>[cad.rs]"]
  node_dicom["DICOM conversion<br/>[dicom.rs]"]
  node_pdf["PDF processing<br/>[pdf.rs]"]
end

subgraph group_operations["Document operations"]
  node_annotations["Annotations<br/>[annotations.rs]"]
  node_comparison["Document comparison<br/>[comparison.rs]"]
  node_forms["Form handling<br/>[forms.rs]"]
  node_pii["PII detection<br/>[pii.rs]"]
  node_redaction["Redaction<br/>[redaction.rs]"]
  node_signature["Digital signatures<br/>[signature.rs]"]
  node_builder["Document builder<br/>[builder.rs]"]
end

subgraph group_viewer["Web viewer"]
  node_web_component["Web component<br/>[oxid-element.ts]"]
  node_viewer["Viewer workflow<br/>[viewer.ts]"]
  node_template["Viewer template<br/>[template.ts]"]
  node_annotation_ui["Annotation layer"]
  node_comparison_ui["Comparison UI<br/>[comparison-ui.ts]"]
  node_builder_ui["Builder UI"]
  node_form_ui["Form layer<br/>[form-layer.ts]"]
  node_text_layer["Text layer<br/>[text-layer.ts]"]
end

node_user(("Document user"))

node_user -->|"opens viewer"| node_web_component
node_web_component -->|"creates viewer"| node_viewer
node_web_component -->|"uses markup"| node_template
node_viewer -->|"uses layer"| node_annotation_ui
node_viewer -->|"uses UI"| node_comparison_ui
node_viewer -->|"renders builder"| node_builder_ui
node_viewer -->|"renders forms"| node_form_ui
node_viewer -->|"uses renderer"| node_text_layer
node_viewer -.->|"requests documents"| node_api
node_user -->|"requests conversion"| node_api
node_api -->|"reads cache"| node_cache
node_api -->|"gets document path"| node_storage
node_api -.->|"checks quotas"| node_auth
node_api -.->|"uses settings"| node_config
node_api -.->|"validates inputs"| node_security
node_connector_registry -->|"dispatches connectors"| node_connector_traits
node_connector_registry -->|"registers connector"| node_filesystem
node_connector_registry -->|"registers connector"| node_s3
node_connector_registry -->|"registers connector"| node_cmis
node_api -.->|"uses storage connectors"| node_connector_registry
node_api -.->|"converts documents"| node_converter
node_converter -->|"dispatches Office"| node_office
node_converter -.->|"dispatches CAD"| node_cad
node_converter -.->|"dispatches DICOM"| node_dicom
node_api -.->|"renders pages"| node_pdf
node_api -.->|"handles annotations"| node_annotations
node_api -.->|"compares documents"| node_comparison
node_api -.->|"handles forms"| node_forms
node_api -.->|"scans for PII"| node_pii
node_api -.->|"applies redactions"| node_redaction
node_api -.->|"handles signatures"| node_signature
node_api -.->|"builds documents"| node_builder
node_forms -->|"uses conversion"| node_converter
node_pii -->|"reads PDF text"| node_pdf

click node_api "https://github.com/jikenlabs/oxid/blob/main/backend/src/api/routes.rs"
click node_auth "https://github.com/jikenlabs/oxid/blob/main/backend/src/auth.rs"
click node_config "https://github.com/jikenlabs/oxid/blob/main/backend/src/config.rs"
click node_cache "https://github.com/jikenlabs/oxid/blob/main/backend/src/cache.rs"
click node_security "https://github.com/jikenlabs/oxid/blob/main/backend/src/security.rs"
click node_storage "https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/mod.rs"
click node_connector_registry "https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/mod.rs"
click node_connector_traits "https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/traits.rs"
click node_filesystem "https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/filesystem.rs"
click node_s3 "https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/s3.rs"
click node_cmis "https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/cmis.rs"
click node_converter "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/mod.rs"
click node_office "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/office.rs"
click node_cad "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/cad.rs"
click node_dicom "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/dicom.rs"
click node_pdf "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/pdf.rs"
click node_annotations "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/annotations.rs"
click node_comparison "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/comparison.rs"
click node_forms "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/forms.rs"
click node_pii "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/pii.rs"
click node_redaction "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/redaction.rs"
click node_signature "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/signature.rs"
click node_builder "https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/builder.rs"
click node_web_component "https://github.com/jikenlabs/oxid/blob/main/frontend/src/oxid-element.ts"
click node_viewer "https://github.com/jikenlabs/oxid/blob/main/frontend/src/viewer.ts"
click node_template "https://github.com/jikenlabs/oxid/blob/main/frontend/src/template.ts"
click node_annotation_ui "https://github.com/jikenlabs/oxid/blob/main/frontend/src/annotation-layer.ts"
click node_comparison_ui "https://github.com/jikenlabs/oxid/blob/main/frontend/src/comparison-ui.ts"
click node_builder_ui "https://github.com/jikenlabs/oxid/blob/main/frontend/src/document-builder-ui.ts"
click node_form_ui "https://github.com/jikenlabs/oxid/blob/main/frontend/src/form-layer.ts"
click node_text_layer "https://github.com/jikenlabs/oxid/blob/main/frontend/src/text-layer.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_api,node_auth,node_config,node_cache,node_security,node_user toneBlue
class node_storage,node_connector_registry,node_connector_traits,node_filesystem,node_s3,node_cmis toneAmber
class node_converter,node_office,node_cad,node_dicom,node_pdf toneMint
class node_annotations,node_comparison,node_forms,node_pii,node_redaction,node_signature,node_builder toneRose
class node_web_component,node_viewer,node_template,node_annotation_ui,node_comparison_ui,node_builder_ui,node_form_ui,node_text_layer toneIndigo
```

## Components

### Server and API

- [HTTP API](https://github.com/jikenlabs/oxid/blob/main/backend/src/api/routes.rs): `backend/src/api/routes.rs`
- [API keys and quotas](https://github.com/jikenlabs/oxid/blob/main/backend/src/auth.rs): `backend/src/auth.rs`
- [Application config](https://github.com/jikenlabs/oxid/blob/main/backend/src/config.rs): `backend/src/config.rs`
- [Render cache](https://github.com/jikenlabs/oxid/blob/main/backend/src/cache.rs): `backend/src/cache.rs`
- [Security validation](https://github.com/jikenlabs/oxid/blob/main/backend/src/security.rs): `backend/src/security.rs`

### Document storage

- [Local document storage](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/mod.rs): `backend/src/connectors/mod.rs`
- [Connector registry](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/mod.rs): `backend/src/connectors/mod.rs`
- [Connector contract](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/traits.rs): `backend/src/connectors/traits.rs`
- [Filesystem connector](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/filesystem.rs): `backend/src/connectors/filesystem.rs`
- [S3 connector](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/s3.rs): `backend/src/connectors/s3.rs`
- [CMIS connector](https://github.com/jikenlabs/oxid/blob/main/backend/src/connectors/cmis.rs): `backend/src/connectors/cmis.rs`

### Conversion and rendering

- [Format dispatch](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/mod.rs): `backend/src/engine/converter/mod.rs`
- [Office conversion](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/office.rs): `backend/src/engine/converter/office.rs`
- [CAD conversion](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/cad.rs): `backend/src/engine/converter/cad.rs`
- [DICOM conversion](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/converter/dicom.rs): `backend/src/engine/converter/dicom.rs`
- [PDF processing](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/pdf.rs): `backend/src/engine/pdf.rs`

### Document operations

- [Annotations](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/annotations.rs): `backend/src/engine/annotations.rs`
- [Document comparison](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/comparison.rs): `backend/src/engine/comparison.rs`
- [Form handling](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/forms.rs): `backend/src/engine/forms.rs`
- [PII detection](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/pii.rs): `backend/src/engine/pii.rs`
- [Redaction](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/redaction.rs): `backend/src/engine/redaction.rs`
- [Digital signatures](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/signature.rs): `backend/src/engine/signature.rs`
- [Document builder](https://github.com/jikenlabs/oxid/blob/main/backend/src/engine/builder.rs): `backend/src/engine/builder.rs`

### Web viewer

- [Web component](https://github.com/jikenlabs/oxid/blob/main/frontend/src/oxid-element.ts): `frontend/src/oxid-element.ts`
- [Viewer workflow](https://github.com/jikenlabs/oxid/blob/main/frontend/src/viewer.ts): `frontend/src/viewer.ts`
- [Viewer template](https://github.com/jikenlabs/oxid/blob/main/frontend/src/template.ts): `frontend/src/template.ts`
- [Annotation layer](https://github.com/jikenlabs/oxid/blob/main/frontend/src/annotation-layer.ts): `frontend/src/annotation-layer.ts`
- [Comparison UI](https://github.com/jikenlabs/oxid/blob/main/frontend/src/comparison-ui.ts): `frontend/src/comparison-ui.ts`
- [Builder UI](https://github.com/jikenlabs/oxid/blob/main/frontend/src/document-builder-ui.ts): `frontend/src/document-builder-ui.ts`
- [Form layer](https://github.com/jikenlabs/oxid/blob/main/frontend/src/form-layer.ts): `frontend/src/form-layer.ts`
- [Text layer](https://github.com/jikenlabs/oxid/blob/main/frontend/src/text-layer.ts): `frontend/src/text-layer.ts`

### Other components

- **Document user**

## Connections

- Document user → Web component: opens viewer
- Web component → Viewer workflow: creates viewer (evidence: `frontend/src/oxid-element.ts`)
- Web component → Viewer template: uses markup (evidence: `frontend/src/oxid-element.ts`)
- Viewer workflow → Annotation layer: uses layer (evidence: `frontend/src/viewer.ts`)
- Viewer workflow → Comparison UI: uses UI (evidence: `frontend/src/viewer.ts`)
- Viewer workflow → Builder UI: renders builder (evidence: `frontend/src/viewer.ts`)
- Viewer workflow → Form layer: renders forms (evidence: `frontend/src/viewer.ts`)
- Viewer workflow → Text layer: uses renderer (evidence: `frontend/src/viewer.ts`)
- Viewer workflow → HTTP API: requests documents
- Document user → HTTP API: requests conversion
- HTTP API → Render cache: reads cache (evidence: `backend/src/api/routes.rs`)
- HTTP API → Local document storage: gets document path (evidence: `backend/src/api/routes.rs`)
- HTTP API → API keys and quotas: checks quotas (evidence: `backend/src/api/routes.rs`)
- HTTP API → Application config: uses settings (evidence: `backend/src/api/routes.rs`)
- HTTP API → Security validation: validates inputs (evidence: `backend/src/api/routes.rs`)
- Connector registry → Connector contract: dispatches connectors (evidence: `backend/src/connectors/mod.rs`)
- Connector registry → Filesystem connector: registers connector (evidence: `backend/src/connectors/mod.rs`)
- Connector registry → S3 connector: registers connector (evidence: `backend/src/connectors/mod.rs`)
- Connector registry → CMIS connector: registers connector (evidence: `backend/src/connectors/mod.rs`)
- HTTP API → Connector registry: uses storage connectors (evidence: `backend/src/api/routes.rs`)
- HTTP API → Format dispatch: converts documents (evidence: `backend/src/api/routes.rs`)
- Format dispatch → Office conversion: dispatches Office (evidence: `backend/src/engine/converter/mod.rs`)
- Format dispatch → CAD conversion: dispatches CAD (evidence: `backend/src/engine/converter/mod.rs`)
- Format dispatch → DICOM conversion: dispatches DICOM (evidence: `backend/src/engine/converter/mod.rs`)
- HTTP API → PDF processing: renders pages (evidence: `backend/src/api/routes.rs`)
- HTTP API → Annotations: handles annotations (evidence: `backend/src/api/routes.rs`)
- HTTP API → Document comparison: compares documents (evidence: `backend/src/api/routes.rs`)
- HTTP API → Form handling: handles forms (evidence: `backend/src/api/routes.rs`)
- HTTP API → PII detection: scans for PII (evidence: `backend/src/api/routes.rs`)
- HTTP API → Redaction: applies redactions (evidence: `backend/src/api/routes.rs`)
- HTTP API → Digital signatures: handles signatures (evidence: `backend/src/api/routes.rs`)
- HTTP API → Document builder: builds documents (evidence: `backend/src/api/routes.rs`)
- Form handling → Format dispatch: uses conversion (evidence: `backend/src/engine/forms.rs`)
- PII detection → PDF processing: reads PDF text (evidence: `backend/src/engine/pii.rs`)
