Hypermedia Pipeline
Hypermedia Pipeline
How core.hypermedia handles media and document processing, conversion, compression, and OCR at scale.
> Status: Architecture defined. Implementation pending.
Overview
core.hypermedia is the processing engine for all media and document files in the UNVRSL ecosystem. When an app needs to convert a PDF, compress an image, transcode a video, or extract text via OCR, it delegates to core.hypermedia through core.console.
The fundamental architectural principle: PHP-FPM never processes files. All heavy work (FFmpeg, ImageMagick, OCR, LibreOffice) happens in isolated worker processes that pull jobs from a durable queue. The web tier only creates jobs and returns status.
Architecture Diagram
┌─────────────────────────────────────────────────────────────────────┐
│ Client (Browser / App) │
│ │
│ 1. Upload file via core.storage (direct-to-S3) │
│ 2. Request processing: POST /v1/hypermedia/process │
│ 3. Poll or subscribe for status updates │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ core.console (API Gateway) │
│ │
│ - Validate API key │
│ - Check hypermedia quota (via core.auth) │
│ - Route to core.hypermedia │
└──────────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ core.hypermedia (Web Tier) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────────────────┐ │
│ │ Job Creator │ │ Status API │ │ Scheduler Controller │ │
│ │ - validate │ │ - job state │ │ - queue depth monitor │ │
│ │ - estimate │ │ - progress │ │ - provision/terminate │ │
│ │ cost │ │ - results │ │ cloud workers │ │
│ │ - enqueue │ │ │ │ - config-driven │ │
│ └──────┬───────┘ └──────────────┘ └───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ SQL Database │ │
│ │ processing_jobs, job_outputs, processing_profiles, │ │
│ │ workers, worker_metrics │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Durable Queue (Redis) │ │
│ │ queues: images, documents, ocr, media, bulk │ │
│ └──────────────────────────┬───────────────────────────────────┘ │
└─────────────────────────────┼───────────────────────────────────────┘
│
┌───────────────┼───────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Worker VPS │ │ Burst Worker │ │ Burst Worker │
│ (always-on) │ │ (cloud VM) │ │ (cloud VM) │
│ │ │ │ │ │
│ images, │ │ video, │ │ OCR batch, │
│ small docs │ │ large PDFs │ │ bulk processing │
└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘
│ │ │
└────────────────┼────────────────────┘
▼
┌──────────────────────────┐
│ core.storage (S3) │
│ originals + derived │
└──────────────────────────┘Key Responsibilities
- Document conversion — PDF ↔ text, DOCX → HTML, legacy format conversion via LibreOffice
- Image processing — resize, compress, format conversion (WebP, AVIF), thumbnail generation
- Media transcoding — audio/video conversion via FFmpeg
- OCR & text extraction — classical OCR (PaddleOCR/Surya) with AI OCR escalation for complex documents
- OpenXML processing — native .docx/.xlsx/.pptx handling via PHPOffice libraries
Processing Flow
App → POST /v1/hypermedia/process
{ object_id, operations: ["pdf_preview", "ocr", "thumbnail"] }
│
▼
core.hypermedia web tier
│
├── Validate: object exists, user has access, quota available
├── Estimate cost (credits per operation × file size)
├── Create processing_job rows (one per operation)
├── Enqueue jobs to appropriate queues
└── Return { job_ids, estimated_credits, status: "queued" }
│
▼
Workers pull jobs from queues
│
├── Download source from S3 (via core.storage presigned URL)
├── Process (FFmpeg, ImageMagick, OCR, etc.)
├── Upload derived files to S3
├── Update job status + outputs
└── Report completion
│
▼
App polls GET /v1/hypermedia/jobs/{job_id}
│
└── { status: "completed", outputs: [{ type: "thumbnail", object_id: 99 }] }Design Principles
- Queue is the scaling boundary. Web tier enqueues; workers dequeue. Adding workers scales throughput linearly. No worker knows about other workers.
- Workers are disposable. Any worker can die at any point. The queue's visibility timeout ensures another worker retries the job.
- Idempotent processing. Processing the same job twice must not corrupt data. Each conversion has a deterministic output prefix; database uniqueness constraints prevent duplicates.
- Quota before work. Cost is estimated and verified before enqueueing. Users never receive a surprise bill for a 3-hour video transcode.
- Separate queues per workload. Images, documents, OCR, and video have different resource profiles. Mixing them in one queue lets a 10-minute FFmpeg job block a 200ms thumbnail.
- Default to VPS, burst to cloud. The baseline worker runs on the existing VPS. Cloud instances are provisioned only when the queue grows beyond configurable thresholds.
Pages
- Database Schemas — processing_jobs, job_outputs, profiles, workers
- Worker Architecture — Queue design, job lifecycle, state machine
- Processing Pipelines — Image, document, OCR, media, OpenXML pipelines
- Scheduler — Dynamic cloud instance management
Quota Enforcement
Each processing operation consumes hypermedia credits from the user's quota via core.auth. Credits are estimated at job creation and charged on completion. If a job fails, credits are refunded.
| Operation | Credit Cost Basis |
| Image resize/compress | Per image + output size |
| PDF preview/extract | Per page |
| OCR (classical) | Per page |
| OCR (AI) | Per page (higher cost) |
| Video/audio transcode | Per minute of output |
| Document conversion | Per document |
Related
- Storage Architecture — File upload/download, pools, browser direct upload
- Console Architecture — API gateway routing
- Auth Architecture — Quota system, session validation