# remanth1/your-pdf architecture

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

- Interactive diagram: https://gitdiagram.com/remanth1/your-pdf
- Repository: https://github.com/remanth1/your-pdf

## Overview

#### Purpose and Runtime Shape
This is a file-format conversion service scaffold plus an existing Vite-based frontend. Users submit files for conversion; a durable job system dispatches work to a Node.js worker, which selects a converter adapter and stores outputs. PostgreSQL and Redis are required infrastructure. The root frontend is the implemented user-facing app; `apps/web` is a separate, mostly scaffolded Next.js frontend.

#### User-Facing Frontend
The active frontend starts through the root Vite application, with client bootstrap/server entry points at `src/start.ts` and `src/server.ts`. Route composition is defined in `src/router.tsx` and `src/routes/__root.tsx`; individual converter pages include `src/routes/pdf-to-word.tsx`, `src/routes/word-to-pdf.tsx`, and `src/routes/ocr-pdf.tsx`.

Reusable conversion UX centers on file intake, job state, and results:
- `src/components/Dropzone.tsx`
- `src/components/JobPanel.tsx`
- `src/components/ToolShell.tsx`

Client job submission/polling behavior is encapsulated in `src/hooks/useConversionJob.ts` and `src/hooks/useJobPolling.ts`.

#### HTTP and Job Boundary
The Next.js app exposes an alternate API surface for asynchronous job lifecycle management:
- `apps/web/app/api/jobs/route.ts` creates/lists jobs.
- `apps/web/app/api/jobs/[id]/route.ts` retrieves a job’s state.
- `apps/web/app/[tool]/page.tsx` provides dynamic tool pages.

This boundary should accept uploads and conversion parameters, persist job metadata, enqueue only a job identifier/payload, and return status/result references rather than execute expensive conversions synchronously.

#### Background Processing Pipeline
The worker is the conversion execution authority:
- `apps/worker/src/worker.ts` is the worker process entry point.
- `apps/worker/src/queue.ts` owns Redis-backed job consumption.
- `apps/worker/src/job-runner.ts` orchestrates validation, converter invocation, state transitions, and failure handling.
- `apps/worker/src/storage.ts` handles input/output object persistence.
- `apps/worker/src/cleanup.ts` manages expiration/removal of temporary artifacts.

Operational concerns are separated into `apps/worker/src/config.ts`, `apps/worker/src/logger.ts`, `apps/worker/src/metrics.ts`, and `apps/worker/src/security.ts`.

#### Conversion Abstraction and Execution
`packages/converters` defines the shared backend conversion contract and registry:
- `packages/converters/src/types.ts`
- `packages/converters/src/registry.ts`
- `packages/converters/src/index.ts`

Adapters wrap installed native command-line tools rather than exposing them directly to API/UI code:
- `packages/converters/src/adapters/ffmpeg.ts` for media.
- `packages/converters/src/adapters/imagemagick.ts` for images.
- `packages/converters/src/adapters/libreoffice.ts` for office documents.
- `packages/converters/src/adapters/pdf-tools.ts` for PDF operations.

`packages/converters/src/process.ts` is the process-execution boundary and should enforce timeouts, resource controls, and sanitized arguments.

#### Shared Domain and Persistence
The job/conversion domain types are shared across services:
- `packages/shared/src/jobs.ts`
- `packages/shared/src/conversion.ts`
- `packages/shared/src/index.ts`

PostgreSQL schema ownership is centralized in `db/schema.sql`; Redis provides queueing and likely transient coordination. Local development provisions both through `docker-compose.yml`. The core flow is: frontend upload/request → API creates database job and Redis message → worker fetches input and runs adapter → worker stores output and updates job record → frontend polls and presents completion/download.

#### Client-Side and Specialized Conversion Paths
The root app also contains browser-oriented conversion implementations, separate from the worker architecture:
- `src/lib/converters/pdf-basic.ts`
- `src/lib/converters/image-basic.ts`
- `src/lib/converters/tabular.ts`
- `src/lib/converters/ocr-pdf.ts`

These support lightweight or privacy-oriented client processing, while CPU-heavy, native-tool, document, and media transformations belong behind the queued worker boundary. PDF.js assets under `public/pdfjs` support browser PDF handling; AI PDF analysis is isolated at `src/lib/ai/pdf-insights.ts`.

Main entry points: [`apps/worker/src/job-runner.ts`](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/job-runner.ts) (Job runner), [`apps/web/app/api/jobs/route.ts`](https://github.com/remanth1/your-pdf/blob/main/apps/web/app/api/jobs/route.ts) (Jobs API), [`src/router.tsx`](https://github.com/remanth1/your-pdf/blob/main/src/router.tsx) (Converter routes), [`apps/worker/src/queue.ts`](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/queue.ts) (Queue consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Active Vite Frontend"]
  node_vite_entry["Vite app entry<br/>frontend bootstrap<br/>[start.ts]"]
  node_routes["Converter routes<br/>route composition<br/>[router.tsx]"]
  node_conversion_ui["Conversion UI<br/>reusable UI<br/>[ToolShell.tsx]"]
  node_client_job_hooks["Job client hooks<br/>submission and polling"]
  node_browser_converters["Browser converters<br/>client conversion<br/>[pdf-basic.ts]"]
  node_pdf_insights["AI PDF insights<br/>client AI feature<br/>[pdf-insights.ts]"]
end

subgraph group_api["Next.js Job API"]
  node_job_api["Jobs API<br/>job lifecycle API<br/>[route.ts]"]
  node_tool_pages["Dynamic tool pages<br/>Next.js frontend<br/>[page.tsx]"]
end

subgraph group_worker["Conversion Worker"]
  node_worker_entry["Worker process<br/>Node.js entry<br/>[worker.ts]"]
  node_redis_consumer["Queue consumer<br/>Redis job consumer<br/>[queue.ts]"]
  node_job_runner["Job runner<br/>conversion orchestrator<br/>[job-runner.ts]"]
  node_object_storage[("Artifact storage<br/>input/output storage<br/>[storage.ts]")]
  node_cleanup["Artifact cleanup<br/>retention worker<br/>[cleanup.ts]"]
end

subgraph group_shared["Shared Backend Packages"]
  node_converter_registry["Converter registry<br/>conversion contract<br/>[registry.ts]"]
  node_process_boundary{{"Native process boundary<br/>controlled execution<br/>[process.ts]"}}
  node_native_adapters["Native tool adapters<br/>converter adapters<br/>[ffmpeg.ts]"]
  node_job_domain["Shared job domain<br/>domain types<br/>[jobs.ts]"]
end

subgraph group_infra["Persistence and Queue"]
  node_postgres[("PostgreSQL<br/>job metadata store<br/>[schema.sql]")]
  node_redis["Redis<br/>durable job queue<br/>[docker-compose.yml]"]
end

node_vite_entry -->|"renders"| node_routes
node_routes -->|"uses"| node_conversion_ui
node_conversion_ui -->|"submits and polls"| node_client_job_hooks
node_routes -.->|"lightweight local conversions"| node_browser_converters
node_browser_converters -.->|"PDF analysis"| node_pdf_insights
node_client_job_hooks -->|"create/status requests"| node_job_api
node_tool_pages -->|"uses"| node_job_api
node_job_api -->|"creates and reads jobs"| node_postgres
node_job_api -->|"enqueues job payload"| node_redis
node_job_api -->|"uses"| node_job_domain
node_worker_entry -->|"starts"| node_redis_consumer
node_redis_consumer -->|"consumes"| node_redis
node_redis_consumer -->|"dispatches"| node_job_runner
node_job_runner -->|"fetches input and stores output"| node_object_storage
node_job_runner -->|"updates job state"| node_postgres
node_job_runner -->|"selects converter"| node_converter_registry
node_job_runner -->|"uses"| node_job_domain
node_converter_registry -->|"resolves adapter"| node_native_adapters
node_native_adapters -->|"executes through"| node_process_boundary
node_cleanup -->|"expires artifacts"| node_object_storage

click node_vite_entry "https://github.com/remanth1/your-pdf/blob/main/src/start.ts"
click node_routes "https://github.com/remanth1/your-pdf/blob/main/src/router.tsx"
click node_conversion_ui "https://github.com/remanth1/your-pdf/blob/main/src/components/ToolShell.tsx"
click node_client_job_hooks "https://github.com/remanth1/your-pdf/blob/main/src/hooks/useConversionJob.ts"
click node_browser_converters "https://github.com/remanth1/your-pdf/blob/main/src/lib/converters/pdf-basic.ts"
click node_pdf_insights "https://github.com/remanth1/your-pdf/blob/main/src/lib/ai/pdf-insights.ts"
click node_job_api "https://github.com/remanth1/your-pdf/blob/main/apps/web/app/api/jobs/route.ts"
click node_tool_pages "https://github.com/remanth1/your-pdf/blob/main/apps/web/app/%5Btool%5D/page.tsx"
click node_worker_entry "https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/worker.ts"
click node_redis_consumer "https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/queue.ts"
click node_job_runner "https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/job-runner.ts"
click node_object_storage "https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/storage.ts"
click node_cleanup "https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/cleanup.ts"
click node_converter_registry "https://github.com/remanth1/your-pdf/blob/main/packages/converters/src/registry.ts"
click node_process_boundary "https://github.com/remanth1/your-pdf/blob/main/packages/converters/src/process.ts"
click node_native_adapters "https://github.com/remanth1/your-pdf/blob/main/packages/converters/src/adapters/ffmpeg.ts"
click node_job_domain "https://github.com/remanth1/your-pdf/blob/main/packages/shared/src/jobs.ts"
click node_postgres "https://github.com/remanth1/your-pdf/blob/main/db/schema.sql"
click node_redis "https://github.com/remanth1/your-pdf/blob/main/docker-compose.yml"

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_vite_entry,node_routes,node_conversion_ui,node_client_job_hooks,node_browser_converters,node_pdf_insights toneBlue
class node_job_api,node_tool_pages toneAmber
class node_worker_entry,node_redis_consumer,node_job_runner,node_object_storage,node_cleanup toneMint
class node_converter_registry,node_process_boundary,node_native_adapters,node_job_domain toneRose
class node_postgres,node_redis toneIndigo
```

## Components

### Active Vite Frontend

Implemented user-facing conversion application.

- [Vite app entry](https://github.com/remanth1/your-pdf/blob/main/src/start.ts): frontend bootstrap · `src/start.ts`
- [Converter routes](https://github.com/remanth1/your-pdf/blob/main/src/router.tsx): route composition · Includes PDF, Word, and OCR tool pages. · `src/router.tsx`
- [Conversion UI](https://github.com/remanth1/your-pdf/blob/main/src/components/ToolShell.tsx): reusable UI · Dropzone, job panel, and tool shell. · `src/components/ToolShell.tsx`
- [Job client hooks](https://github.com/remanth1/your-pdf/blob/main/src/hooks/useConversionJob.ts): submission and polling · `src/hooks/useConversionJob.ts`
- [Browser converters](https://github.com/remanth1/your-pdf/blob/main/src/lib/converters/pdf-basic.ts): client conversion · Lightweight and privacy-oriented processing paths. · `src/lib/converters/pdf-basic.ts`
- [AI PDF insights](https://github.com/remanth1/your-pdf/blob/main/src/lib/ai/pdf-insights.ts): client AI feature · `src/lib/ai/pdf-insights.ts`

### Next.js Job API

Alternate asynchronous job lifecycle surface.

- [Jobs API](https://github.com/remanth1/your-pdf/blob/main/apps/web/app/api/jobs/route.ts): job lifecycle API · Creates, lists, and retrieves asynchronous jobs. · `apps/web/app/api/jobs/route.ts`
- [Dynamic tool pages](https://github.com/remanth1/your-pdf/blob/main/apps/web/app/%5Btool%5D/page.tsx): Next.js frontend · Mostly scaffolded alternate UI. · `apps/web/app/[tool]/page.tsx`

### Conversion Worker

Queued server-side conversion execution.

- [Worker process](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/worker.ts): Node.js entry · `apps/worker/src/worker.ts`
- [Queue consumer](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/queue.ts): Redis job consumer · `apps/worker/src/queue.ts`
- [Job runner](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/job-runner.ts): conversion orchestrator · Validates, transitions state, invokes converters, and handles failures. · `apps/worker/src/job-runner.ts`
- [Artifact storage](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/storage.ts): input/output storage · `apps/worker/src/storage.ts`
- [Artifact cleanup](https://github.com/remanth1/your-pdf/blob/main/apps/worker/src/cleanup.ts): retention worker · `apps/worker/src/cleanup.ts`

### Shared Backend Packages

- [Converter registry](https://github.com/remanth1/your-pdf/blob/main/packages/converters/src/registry.ts): conversion contract · Selects adapters through a shared conversion interface. · `packages/converters/src/registry.ts`
- [Native process boundary](https://github.com/remanth1/your-pdf/blob/main/packages/converters/src/process.ts): controlled execution · Enforces sanitized arguments, timeouts, and resource controls. · `packages/converters/src/process.ts`
- [Native tool adapters](https://github.com/remanth1/your-pdf/blob/main/packages/converters/src/adapters/ffmpeg.ts): converter adapters · FFmpeg, ImageMagick, LibreOffice, and PDF tools. · `packages/converters/src/adapters/ffmpeg.ts`
- [Shared job domain](https://github.com/remanth1/your-pdf/blob/main/packages/shared/src/jobs.ts): domain types · `packages/shared/src/jobs.ts`

### Persistence and Queue

- [PostgreSQL](https://github.com/remanth1/your-pdf/blob/main/db/schema.sql): job metadata store · `db/schema.sql`
- [Redis](https://github.com/remanth1/your-pdf/blob/main/docker-compose.yml): durable job queue · `docker-compose.yml`

## Connections

- Vite app entry → Converter routes: renders
- Converter routes → Conversion UI: uses
- Conversion UI → Job client hooks: submits and polls
- Converter routes → Browser converters: lightweight local conversions
- Browser converters → AI PDF insights: PDF analysis
- Job client hooks → Jobs API: create/status requests
- Dynamic tool pages → Jobs API: uses
- Jobs API → PostgreSQL: creates and reads jobs
- Jobs API → Redis: enqueues job payload
- Jobs API → Shared job domain: uses
- Worker process → Queue consumer: starts
- Queue consumer → Redis: consumes
- Queue consumer → Job runner: dispatches
- Job runner → Artifact storage: fetches input and stores output
- Job runner → PostgreSQL: updates job state
- Job runner → Converter registry: selects converter
- Job runner → Shared job domain: uses
- Converter registry → Native tool adapters: resolves adapter
- Native tool adapters → Native process boundary: executes through
- Artifact cleanup → Artifact storage: expires artifacts