Kuybiopen sourceApache-2.0

The backend foundation for your next content platform.

Build on NestJS with authentication, permissions, dynamic content, story versioning, media processing, and background jobs already connected. One codebase runs as an API and a separate worker, on PostgreSQL and Redis.

Stack: NestJS 12 · TypeScript 6 · PostgreSQL 16 · Redis 7 · BullMQ · Node.js 24

Stars
4 stars
Forks
3 forks
Last commit
Updated 25 days ago
How Kuybi runs
kuybi        one codebase, one image
├─ api       main.js       :4040
├─ worker    worker.js
└─ dashboard dashboard.js  :4050  optional

shared       PostgreSQL 16 · Redis 7

A modular monolith with separate API and background-worker processes, created by Moayyad Faris.

Why Kuybi exists

Every content product needs the same groundwork before its first real feature: sign-in that can be revoked, permissions that understand ownership, a content model that changes without a migration for every field, uploads that can't smuggle in the wrong file, jobs that don't get lost when Redis blinks, and logs you can follow from one request to the next.

Each piece is a reasonable afternoon on its own. Wiring them so they agree with each other (the job that only exists if the row committed, the cache that clears after the transaction, the permission check that also runs on the individual record) is where the weeks go. Kuybi is that wiring, done once, with the decisions written down.

What you can build on it

Kuybi is a backend, not a finished application. These are the products its pieces are shaped for.

Editorial and publishing platforms

Stories with categories, tags and media, a publishing workflow, and version history you can compare, roll back, branch and merge. Bring the newsroom or CMS front end; the editorial backend is in place.

Internal applications with scoped access

Roles with ownership rules (“edit your own records”), role assignments that expire, sessions an admin can revoke, and a searchable audit trail of user and admin actions.

Content and media backends for web and mobile

Define your own content types, upload straight to S3 from the client, and serve published content through a rate-limited public read API. Any web or mobile front end can sit on top.

What's already connected

Identity and access

Sessions you can revoke, permissions that understand ownership.

Revocable sessions
Short-lived JWT access tokens carry a session id and are checked against that session on every request. Refresh tokens are opaque and stored hashed. Users and admins can list sessions and revoke one device or all of them.
Account protection
Account lockout after repeated failed sign-ins, email verification, password reset by emailed token, a password policy with strength checks and password history, and forced password change.
Roles and permissions
CASL abilities on actions and subjects, with ownership conditions such as “update own story”. A route guard checks the action; services check the individual record.
Time-limited roles
A role assignment can carry an expiry date. Once it passes, the role stops granting anything; no cleanup job required.

Permissions apply to whole records. Field-scoped grants aren't supported yet, and they fail closed: a grant limited to certain fields grants nothing.

Content and publishing

Model your own content types; publish stories with real version history.

Content types you define
Create post types such as Event, Article or Product, then add field definitions. Content is validated against those definitions on every write. This is a backend modeling API; there is no visual builder.
28 field types
Text, textarea, rich text, email, URL, phone and code; number and currency; date, date-time and time; checkbox, radio, select, multi-select and toggle; file, image, gallery and video; relation, user and taxonomy references; color, JSON, repeaters and groups.
Stories and publishing
Stories with categories, tags and media, and a publishing workflow. Readers see published stories plus their own drafts; list results follow the reader's permissions.
Version history
Save snapshots, compare two versions, roll back, branch a version, merge branches and tag versions.
Public read API
Published stories and categories under /api/web/v1: no authentication, rate-limited, and only explicitly allowlisted fields in each response. Everything else stays behind the authenticated API.

Rich-text fields in post-type content are sanitized with DOMPurify when saved. Story body text is stored as submitted, so escape or sanitize it where you render it.

Media and background work

Uploads that verify what they receive; jobs that commit with your data.

Two upload paths
Direct to S3 with a presigned POST that the API verifies on completion, so file bytes never pass through the API, or a regular multipart upload through the API.
Files checked by content
The file type comes from the file's first bytes, not the client's claim. SVG and XML are rejected, oversized files are refused while streaming, and re-uploading identical content returns the existing file.
Image processing
In the worker: EXIF data stripped, the original re-encoded, four thumbnail sizes (150, 300, 600 and 1200 px) and a small blurred placeholder. Images stay private until processing finishes.
Jobs through a transactional outbox
A job that must follow a database change is written in the same transaction and relayed to BullMQ by the worker. Queues cover email, image processing, account security and cleanup, with retries, a dead-letter queue and recurring schedules.
Safe retries
Create endpoints for stories, uploads and content accept an Idempotency-Key header. A retry with the same key and body gets the original response back instead of creating a duplicate.

Delivery is at least once. Duplicate jobs are filtered by id, but a job can run again after a worker crash, so handlers must be safe to repeat.

Operations and visibility

One log line per request, honest health checks, a pipeline that refuses bad config.

Logs and errors
Structured Pino logs, one line per request, with a request id and sensitive fields redacted. Errors are RFC 9457 problem details with stable codes and per-field pointers a form can use.
Tracing, metrics and error tracking
OpenTelemetry traces over OTLP, Prometheus metrics (including outbox backlog gauges and ready-made alert rules) and Sentry for server errors.
Health checks
Separate liveness, readiness and full checks. Unhealthy answers return HTTP 503, so orchestrators can act on the status code.
Audit trail
Searchable records of user and admin actions, with statistics and a view of critical events, so you can trace who changed what.
Shipping it
Graceful shutdown for the API and worker, a multi-stage Docker image that runs as non-root, a PM2 config, and migrations as a release step. CI runs lint, typecheck, unit and integration tests with coverage floors, a dependency audit, the module-boundary check and the Docker build.

Outside development and test, configuration fails closed: the API refuses to start with a missing or weak JWT secret or a missing database password.

How it fits together

One NestJS codebase, deployed as two processes from the same image, sharing one PostgreSQL database and one Redis. Separate processes don't make it microservices: modules have enforced boundaries but deploy together.

Kuybi runtime architectureA client calls the API process, whose HTTP pipeline hands requests to feature modules. Repositories read and write PostgreSQL and cache reads in Redis. Jobs are written to an outbox table in PostgreSQL, relayed by the worker process to BullMQ queues in Redis, and run by job processors that use S3 and SMTP. Clients can also upload files directly to S3. An optional Bull Board dashboard reads the queues.API process · main.tsWorker process · worker.tsClientweb · mobileHTTP pipelinevalidation · auth · errors · request idFeature modulescontroller → service → repositoryauth · acl · stories · post-types · mediaPostgreSQLone shared schemaoutbox_messagesRedis · cacherow, list and entity tagsOutbox relaypolls ~1s · claims with SKIP LOCKEDJob processorsemail · image processing · cleanupretries · dead-letter queueRedis · BullMQ queuesemail · attachments · security · cleanupBull Boardoptional · dashboard.tsS3files and derivativesSMTPemail deliverydirect upload(presigned POST)123456
request path background path optionalCache and queues can share one Redis server; they use separate databases.
  1. Requests enter one HTTP pipeline

    Validation, authentication, permission checks, error formatting and request ids are configured once and shared by every route.

  2. Feature modules do the work

    Controllers handle HTTP, services hold behavior, repositories own data access. Modules talk to each other only through their public exports.

  3. Repositories read and write PostgreSQL

    One shared schema with real foreign keys. Transactions go through the owning repository.

  4. Redis caches repository reads

    Reads are cached under row, list and entity tags and invalidated after the transaction commits.

  5. Committed job intent reaches the worker

    Jobs are written to the outbox table inside the business transaction. The worker's relay picks them up about once a second and adds them to BullMQ, using the message id as the job id.

  6. Processors talk to the outside world

    Job processors in the worker send email over SMTP and process images in S3. Bull Board, if you run it, shows the same queues.

The patterns behind the design

Each choice has a cost. These are the ones Kuybi makes, with what you give up. The full reasoning is in the architecture decision records.

Feature modules with explicit public exports
What it does
Each module exposes an index.ts and an entities barrel; everything else is internal. Lint fails on imports of another module's internals, and CI fails on dependency cycles.
Why it matters
Dependencies between features are deliberate and visible in one file, so a module can change its internals without breaking its neighbors.
Tradeoff
Adding a cross-module dependency means editing a public API first, which is slower in the moment.
Controller → service → repository
What it does
Controllers translate HTTP, services hold the business rules, repositories are the only code that touches TypeORM.
Why it matters
Business behavior can be tested without HTTP, and data access lives in one predictable place per entity.
Tradeoff
More files per feature than a controller that queries the database directly.
Dependency injection
What it does
NestJS providers wire services to repositories and to adapters such as S3 and email through constructor injection.
Why it matters
Dependencies are explicit, and tests can swap an adapter for a fake without patching modules.
Tradeoff
Wiring problems show up when the app boots, not when it compiles.
Repository-owned data access and caching
What it does
Repositories cache reads through one contract (row, list and entity tags) and invalidate after commit.
Why it matters
Reads, writes and invalidation sit in the same layer, so a write can't forget to clear the cache it affects.
Tradeoff
Queries that bypass the repository also bypass the cache rules, which is why lint forbids them.
Transactional outbox
What it does
The business change and the intent to run a job are saved in the same transaction; the worker relays committed messages to BullMQ.
Why it matters
No job for a row that rolled back, and no committed row that silently lost its job because Redis was briefly down.
Tradeoff
About a second of extra latency before a job starts, an outbox table to monitor, and at-least-once delivery that still needs idempotent handlers.
In-process domain events
What it does
Modules publish typed events through an EventBus; subscribers react without importing the publisher.
Why it matters
Cross-module reactions, such as revoking sessions when credentials are reset, don't create dependencies between modules.
Tradeoff
Events live and die with the request: they aren't durable, replayable or visible to other services. Work that must survive a crash goes through the outbox. A broker is an open decision.
Separate API and worker processes
What it does
The same image starts as an HTTP API or as a worker that runs queue processors, schedules and the outbox relay.
Why it matters
Image processing and email never compete with request handling, and each process scales on its own.
Tradeoff
Two processes to deploy and monitor, and background work finishes after the response, not during it.
Shared HTTP conventions
What it does
One pipeline for validation, error handling, request ids and response formatting; errors use RFC 9457 problem details.
Why it matters
Every endpoint behaves the same way, so clients handle errors once and logs line up with responses.
Tradeoff
Controllers give up custom response envelopes.
Fail-closed configuration
What it does
Outside development and test, unsafe or missing security settings stop the process instead of falling back to defaults.
Why it matters
A forgotten secret becomes a failed deploy, not a production system running with a placeholder key.
Tradeoff
Deployed environments must set every required variable explicitly, even for a quick staging test.

One flow, end to end: an image upload

The first three steps happen while the client waits. The rest happen in the worker after the transaction commits.

  1. requestAPI

    Start the upload

    POST /api/v1/attachments/uploads. The API checks the declared name, size and type, stores a pending record, and returns a presigned POST pinned to an upload key, the exact size and the content type.

  2. requestClient → S3

    Upload straight to storage

    The client sends the file to S3. Its bytes never pass through the API.

  3. requestAPI

    Verify and commit

    POST /api/v1/attachments/uploads/:id/complete. One completion wins. The API checks the stored size, reads the first bytes of that exact object version to confirm the type, and copies that version to a key the client never had. Then, in one transaction, it marks the image as processing and writes the processing job to the outbox.

  4. Response returned · the rest runs in the background

    backgroundWorker

    Relay the committed job

    The outbox relay claims the message (rows locked so two workers never take the same one) and adds it to the attachment queue with the message id as the job id.

  5. backgroundWorker

    Process the image

    The processor strips EXIF data, re-encodes the original, and stores four thumbnail sizes and a blurred placeholder in S3, all private.

  6. backgroundWorker

    Apply visibility

    Finally it applies the visibility the attachment has at that moment, so an owner who switched to private mid-processing stays private.

Run it locally

About ten minutes with Docker installed. The API and the worker are separate processes, so a complete local system needs both.

  1. Clone and install

    Node.js 24 (pinned in .nvmrc) and Docker for the local services.

    bash
    git clone https://github.com/moayyadfaris/Kuybi.git
    cd Kuybi
    nvm use
    npm ci
  2. Configure and start PostgreSQL and Redis

    The example environment works with the local Docker Compose services.

    bash
    cp .env.example .env
    docker compose up -d
  3. Run migrations and seeds

    Seed roles and permissions before users. The user seed creates a local admin account; its credentials are in the README. Change them anywhere beyond your machine.

    bash
    npm run migration:run
    npm run db:seed:acl
    npm run db:seed:countries
    npm run db:seed:users
  4. Start the API

    Serves on http://localhost:4040, with Swagger at /api/docs and health at /api/health.

    bash
    npm run start:dev
  5. Start the worker in a second terminal

    Needed for emails, image processing, the outbox relay and scheduled cleanup. Without it, jobs wait in the outbox.

    bash
    npm run start:worker:dev
  6. Optional: open the queue dashboard

    Bull Board on http://localhost:4050. Requires BULL_BOARD_PASSWORD. File uploads also need an S3 bucket (S3_* variables).

    bash
    npm run start:dashboard

Project status

Kuybi is actively developed in the open. Recent releases moved to Node.js 24, NestJS 12 and TypeScript 6, and every pull request runs the full CI suite. There's no contribution guide yet: open an issue to discuss a change before sending a pull request.

Stars
4 stars
Forks
3 forks
Last commit
Updated 25 days ago

Questions

What is Kuybi?
An open-source NestJS backend foundation for content-driven products, created by Moayyad Faris. It connects authentication, permissions, dynamic content types, versioned stories, media uploads, background jobs and observability so a new project starts from working groundwork.
Is it a CMS or a backend foundation?
A backend foundation. It provides the APIs and data model a CMS or content product needs, but no admin interface or visual content builder. You build or bring the front end.
Is it a microservices system?
No. It's a modular monolith with separate API and background-worker processes: one codebase, one PostgreSQL database and one Redis. Modules have enforced boundaries but are not independently deployable.
Can I use my own frontend?
Yes. Kuybi is API-only: an authenticated REST API documented with Swagger, and a public read API for published content. Any web or mobile client can use it.
How are background jobs handled?
BullMQ queues on Redis, processed by a separate worker. Jobs that depend on a database change go through a transactional outbox, so they exist only if the change committed. Delivery is at least once, with retries, a dead-letter queue and recurring schedules.
What infrastructure do I need?
Node.js 24, PostgreSQL 16 and Redis 7, with the API and worker running as two processes. File uploads need an S3 bucket and email needs SMTP. Bull Board, tracing, metrics and Sentry are optional.
What license does it use?
Apache License 2.0. You can use, modify and distribute it, including commercially, under the license terms.

Start from the foundation.