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.
Kuybiopen sourceApache-2.0
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
kuybi one codebase, one image
├─ api main.js :4040
├─ worker worker.js
└─ dashboard dashboard.js :4050 optional
shared PostgreSQL 16 · Redis 7A modular monolith with separate API and background-worker processes, created by Moayyad Faris.
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.
Kuybi is a backend, not a finished application. These are the products its pieces are shaped for.
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.
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.
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.
Sessions you can revoke, permissions that understand ownership.
Permissions apply to whole records. Field-scoped grants aren't supported yet, and they fail closed: a grant limited to certain fields grants nothing.
Model your own content types; publish stories with real version history.
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.
Uploads that verify what they receive; jobs that commit with your data.
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.
One log line per request, honest health checks, a pipeline that refuses bad config.
Outside development and test, configuration fails closed: the API refuses to start with a missing or weak JWT secret or a missing database password.
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.
Request path
Background path
Validation, authentication, permission checks, error formatting and request ids are configured once and shared by every route.
Controllers handle HTTP, services hold behavior, repositories own data access. Modules talk to each other only through their public exports.
One shared schema with real foreign keys. Transactions go through the owning repository.
Reads are cached under row, list and entity tags and invalidated after the transaction commits.
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.
Job processors in the worker send email over SMTP and process images in S3. Bull Board, if you run it, shows the same queues.
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.
The first three steps happen while the client waits. The rest happen in the worker after the transaction commits.
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.
The client sends the file to S3. Its bytes never pass through the API.
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.
Response returned · the rest runs in the background
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.
The processor strips EXIF data, re-encodes the original, and stores four thumbnail sizes and a blurred placeholder in S3, all private.
Finally it applies the visibility the attachment has at that moment, so an owner who switched to private mid-processing stays private.
About ten minutes with Docker installed. The API and the worker are separate processes, so a complete local system needs both.
Node.js 24 (pinned in .nvmrc) and Docker for the local services.
git clone https://github.com/moayyadfaris/Kuybi.git
cd Kuybi
nvm use
npm ciThe example environment works with the local Docker Compose services.
cp .env.example .env
docker compose up -dSeed 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.
npm run migration:run
npm run db:seed:acl
npm run db:seed:countries
npm run db:seed:usersServes on http://localhost:4040, with Swagger at /api/docs and health at /api/health.
npm run start:devNeeded for emails, image processing, the outbox relay and scheduled cleanup. Without it, jobs wait in the outbox.
npm run start:worker:devBull Board on http://localhost:4050. Requires BULL_BOARD_PASSWORD. File uploads also need an S3 bucket (S3_* variables).
npm run start:dashboardKuybi 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.