remanth1/your-pdf

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.