How abenezeratnafu/better-media works
1. Repository shape
This is a TypeScript monorepo centered on a media-processing framework. The root packages split into four architectural layers: core contracts, better-media orchestration/runtime, adapters for infrastructure, and plugins for pipeline behavior. There are also framework examples (express, nestjs, nextjs) and a separate platform app that serves docs/blog content.
2. Core is the boundary layer
packages/core defines the stable interfaces and shared types only. It contains contracts for storage, database, jobs, plugins, runtime context, hook names/modes, and media metadata. This is the main architectural boundary: everything else plugs into these interfaces rather than depending on concrete infrastructure.
3. Framework orchestrates the pipeline
packages/better-media is the executable framework layer. Its internal modules suggest the runtime flow: file-loader, lifecycle-engine, pipeline-executor, secure-context, streaming-router, job-runner, webhook emission, and a small PostgreSQL helper. This package wires adapters and plugins together and coordinates the upload lifecycle, but does not own the infrastructure implementations.
4. Primary data flow
The typical flow is: an application receives media input, the framework loads/normalizes the file, runs plugin hooks, persists metadata/state through the database adapter, stores the binary through the storage adapter, and emits events/webhooks as needed. For background work, the framework serializes a job payload containing file key, metadata, hook name, and plugin name, then hands it to the job system.
5. Plugin pipeline
Plugins are the functional units of the framework and are organized by hook-based lifecycle execution. The repo includes validation, virus scanning, media processing, audio streaming, and video streaming plugins. Each plugin has its own runtime helpers and options types, and can run either synchronously during the request or asynchronously in the background.
6. Background jobs are optional and adapter-driven
packages/adapters/jobs and packages/adapters/jobs-bullmq show that background execution is abstracted behind a job adapter. The framework itself does not implement queue polling or scheduling; a worker process owns that. The BullMQ package includes a worker helper, reinforcing that background processing is an external runtime concern rather than part of the core framework loop.
7. Storage is a pluggable persistence boundary
Storage adapters live under packages/adapters/storages. The repo supports memory, filesystem, S3, and GCS backends. This is the main binary-blob persistence boundary, and the examples indicate the filesystem adapter is compatible with local multipart ingest flows while S3/GCS support cloud or object-store deployments.
8. Database is a separate metadata boundary
Database adapters live under packages/adapters/databases and include in-memory, Kysely-based SQL, and MongoDB implementations. The core package also has database schema/migration utilities, so persistent media state and lifecycle records are modeled separately from raw file storage. The architecture keeps metadata persistence independent from blob storage.
9. Infrastructure plugins and runtime add-ons
The validation-plugin includes validators for file type, size, dimensions, filename, checksum uniqueness, and security scanning. The virus-scan plugin has concrete scanners for ClamAV and VirusTotal. These plugins indicate the framework is designed to insert policy/security checks into the upload lifecycle before or alongside processing/storage.
10. Integration examples define the app boundary
The examples/express, examples/nestjs, and examples/nextjs apps demonstrate how host applications integrate the framework in different runtimes. They show API routes, workers, and framework modules rather than a single built-in server, which means the repo is a library/platform architecture, not a standalone application.
11. Public documentation site is separate from runtime
platform is a Next.js app that serves the website, documentation, blog, and search API. It is content/marketing infrastructure for the project, not part of the media pipeline itself. Still, its docs mirror the architecture in the codebase, so it reflects how the system is intended to be deployed and used.
12. Tooling and release model
The repo uses pnpm workspaces, Turbo, tsup builds, Jest tests, ESLint/Prettier, GitHub Actions, Changesets, and Husky. These tools support a multi-package library release workflow, which matches the modular architecture: packages are versioned and shipped independently but share a common TypeScript build and test system.
Main entry points: core Core contracts · pipeline-executor.ts Pipeline executor · src Framework entry · lifecycle-engine.ts Lifecycle engine
Components 31
Core boundary
Stable contracts, shared types, and schema utilities.
- Core contracts · Stable plugin, storage, job, and database contracts plus shared metadata and hook types.
packages/core - DB schema · Database schema, migration planning, naming, SQL, and Postgres helpers.
packages/core/src/database - Adapter lookup · Utilities for selecting or resolving the active adapter implementation.
packages/core/src/adapter
Framework runtime
Executable orchestration layer that wires files, hooks, jobs, storage, and events.
- Framework entry · Main package exports and CLI entry point for the media framework.
packages/better-media/src - File loader · Normalizes incoming media input before lifecycle execution.
packages/better-media/src/core/file-loader.ts - Lifecycle engine · Coordinates hook order and lifecycle state across plugins and persistence.
packages/better-media/src/core/lifecycle-engine.ts - Pipeline executor · Executes plugin pipeline steps and bridges sync and async processing.
packages/better-media/src/core/pipeline-executor.ts - Secure context · Builds a constrained execution context for plugins and framework internals.
packages/better-media/src/core/secure-context.ts - Stream router · Routes streaming reads and helpers for media delivery flows.
packages/better-media/src/stream/streaming-router.ts - Job runner · Turns lifecycle work into job payloads and hands them to the configured job adapter.
packages/better-media/src/jobs/job-runner.ts - Webhook emitter · Emits lifecycle events and webhook notifications after framework actions.
packages/better-media/src/events/webhook-emitter.ts - Postgres helper · Small PostgreSQL integration helper used by the runtime package.
packages/better-media/src/db/postgres.ts
Adapters
Pluggable infrastructure implementations for storage, database, and jobs.
- Memory storage · In-memory blob storage backend for tests and lightweight deployments.
packages/adapters/storages/storage-memory - Filesystem storage · Local filesystem backend for multipart and on-disk media flows.
packages/adapters/storages/storage-filesystem - S3 storage · Object-storage backend for S3 deployments.
packages/adapters/storages/storage-s3 - GCS storage · Object-storage backend for Google Cloud Storage deployments.
packages/adapters/storages/storage-gcs - Memory DB · In-memory metadata store for development and testing.
packages/adapters/databases/db-memory - SQL DB · Kysely-based relational metadata adapter.
packages/adapters/databases/db-kysely - Mongo DB · MongoDB metadata adapter for document persistence.
packages/adapters/databases/mongodb-adapter - Jobs API · Abstract job adapter boundary used by the framework for background execution.
packages/adapters/jobs - BullMQ worker · BullMQ-backed worker helper that owns queue polling and execution.
packages/adapters/jobs-bullmq
Plugins
Hook-driven pipeline behavior for validation, processing, and streaming.
- Validation · File type, size, dimensions, filename, checksum, and security validation hooks.
packages/plugins/validation-plugin - Media processing · General media transformation and processing hook implementation.
packages/plugins/media-processing-plugin - Virus scan · Virus scanning hooks with ClamAV and VirusTotal scanner implementations.
packages/plugins/virus-scan-plugin - Audio streaming · Audio streaming and upload-oriented hook runtime.
packages/plugins/audio-streaming-plugin - Video processing · Video transformation and processing hook runtime.
packages/plugins/video-processing-plugin - Video streaming · Video streaming and upload-oriented hook runtime.
packages/plugins/video-streaming-plugin
Apps
Integration examples and public documentation site.
- Express example · Express host application showing API and worker integration.
examples/express - NestJS example · NestJS integration with framework module and controller wiring.
examples/nestjs - Next.js example · Next.js app routes demonstrating upload and demo endpoints.
examples/nextjs - Platform site · Public docs, blog, search API, and marketing pages.
platform
Connections 36
- Framework entry → Core contracts: uses contracts · Runtime depends on the stable core interfaces and types.
- Framework entry → File loader: loads files · Entry wiring starts media ingestion through the loader.
- File loader → Lifecycle engine: starts lifecycle · Loaded media is passed into the lifecycle orchestration flow.
- Lifecycle engine → Pipeline executor: runs hooks · Lifecycle engine delegates hook execution to the pipeline runner.
- Pipeline executor → Secure context: isolates runtime · Plugins run inside a constrained secure context.
- Lifecycle engine → Job runner: offloads work · Async lifecycle steps can be serialized into background jobs.
- Job runner → Jobs API: dispatches jobs · Background work is handed to the configured job adapter boundary.
- Jobs API → BullMQ worker: implemented by · BullMQ provides the concrete worker/queue runtime.
- Lifecycle engine → Webhook emitter: emits events · Lifecycle transitions can produce webhook and event notifications.
- Framework entry → Stream router: serves streams · Runtime exposes streaming delivery paths for media access.
- Framework entry → Postgres helper: uses postgres · Framework package includes a small Postgres-specific helper.
- Framework entry → Adapter lookup: resolves adapters · Runtime selects infrastructure implementations through core adapter lookup.
- Core contracts → Memory storage: storage contract · Memory storage implements the core storage boundary.
- Core contracts → Filesystem storage: storage contract · Filesystem storage implements the core storage boundary.
- Core contracts → S3 storage: storage contract · S3 storage implements the core storage boundary.
- Core contracts → GCS storage: storage contract · GCS storage implements the core storage boundary.
- Core contracts → Memory DB: db contract · Memory database implements the metadata boundary.
- Core contracts → SQL DB: db contract · Kysely adapter implements the metadata boundary.
- Core contracts → Mongo DB: db contract · MongoDB adapter implements the metadata boundary.
- Core contracts → Jobs API: job contract · Job adapter interface is defined at the core boundary.
- Core contracts → Validation: plugin contract · Plugins are typed against shared core plugin interfaces.
- Core contracts → Media processing: plugin contract · Plugins are typed against shared core plugin interfaces.
- Core contracts → Virus scan: plugin contract · Plugins are typed against shared core plugin interfaces.
- Core contracts → Audio streaming: plugin contract · Plugins are typed against shared core plugin interfaces.
- Core contracts → Video processing: plugin contract · Plugins are typed against shared core plugin interfaces.
- Core contracts → Video streaming: plugin contract · Plugins are typed against shared core plugin interfaces.
- Pipeline executor → Validation: invokes · Validation can run as an early lifecycle hook.
- Pipeline executor → Media processing: invokes · Media processing executes as part of the hook pipeline.
- Pipeline executor → Virus scan: invokes · Virus scanning participates in the pipeline as policy enforcement.
- Pipeline executor → Audio streaming: invokes · Audio streaming plugin participates in streaming-oriented hooks.
- Pipeline executor → Video processing: invokes · Video processing plugin participates in transformation hooks.
- Pipeline executor → Video streaming: invokes · Video streaming plugin participates in delivery hooks.
- Express example → Framework entry: integrates · Express example shows host app integration with the framework.
- NestJS example → Framework entry: integrates · NestJS example shows module-based framework integration.
- Next.js example → Framework entry: integrates · Next.js example shows route-level framework integration.
- Platform site → Core contracts: documents · Docs site reflects the public architecture and reference model.