https://github.com/cosmicdriftgamestudio/kumiko-framework

Kumiko Framework — declarative full-stack TypeScript framework. BUSL-1.1.
https://github.com/cosmicdriftgamestudio/kumiko-framework

bun config-driven drizzle event-sourcing framework hono multitenant postgres realtime typescript

Last synced: 2 days ago
JSON representation

Kumiko Framework — declarative full-stack TypeScript framework. BUSL-1.1.

Host: GitHub
URL: https://github.com/cosmicdriftgamestudio/kumiko-framework
Owner: CosmicDriftGameStudio
License: other
Created: 2026-05-05T13:37:23.000Z (about 1 month ago)
Default Branch: main
Last Pushed: 2026-05-25T18:06:32.000Z (16 days ago)
Last Synced: 2026-05-25T19:34:13.513Z (16 days ago)
Topics: bun, config-driven, drizzle, event-sourcing, framework, hono, multitenant, postgres, realtime, typescript
Language: TypeScript
Size: 9.2 MB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: .github/SECURITY.md

Awesome Lists containing this project

README

          # Kumiko

> **AI-native backend builder.** Prompt your domain — get the full backend: schema, auth, audit, multi-tenant, realtime. TypeScript, your repo, your code.

[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](./LICENSE) [![npm](https://img.shields.io/npm/v/@cosmicdrift/kumiko-framework.svg)](https://www.npmjs.com/package/@cosmicdrift/kumiko-framework) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-runtime-black.svg)](https://bun.sh)

Other things people say about Kumiko

> **"With Kumiko, everything is faster!"** ^{\*faster than building it all from scratch again without Kumiko. Sample size: n=1 (the author).}

>

> **"90% of developers say: Kumiko makes everything faster."** ^{\*we asked 10.}

>

> **"Enterprise-ready since day one."** ^{\*day one hasn't arrived yet.}

>

> **"Battle-tested in production."** ^{\*the production of demo samples.}

>

> **"Multi-tenant out of the box."** ^{\*box not included.}

>

> **"Zero-config."** ^{\*after the initial 47-step setup.}

>

> **"Realtime with <1ms latency."** ^{\*on localhost, Wi-Fi off, exactly one tenant named "test".}

>

> **"Scales to millions of users."** ^{\*theoretically, provided Postgres, Redis, Meilisearch, and your wallet all cooperate.}

>

> **"Type-safe down to the last line."** ^{\*`any` is also a type.}

>

> **"Kumiko — because framework frameworks need a framework too."**

---

## What it does

You write:

```typescript

defineFeature("incident", (r) => {

  r.entity("incident", {

    fields: {

      title: { type: "text", required: true },

      severity: { type: "select", options: ["low", "high", "critical"] },

      status: { type: "select", options: ["open", "investigating", "resolved"] },

    },

  });

  r.writeHandler({

    name: "incident.open",

    schema: openSchema,

    handler: async (event, ctx) => {

      await ctx.appendEvent("incident-opened", { ...event });

    },

  });

});

```

You get, for free:

- **Multi-tenant scoping** — every entity is tenant-scoped by default

- **Audit trail** — every change is an event, time-travel queries work

- **Auth + sessions** — email/password, JWT, role-based access

- **Realtime updates** — SSE broadcast across tenants

- **CRUD UI** — schema-driven forms and lists with override paths

- **Type-safe everywhere** — no `any`, no magic strings

## Quickstart

### Prerequisites

- [Bun](https://bun.sh/) ≥ 1.2 (runtime, package manager, test runner)

- [Node.js](https://nodejs.org/) ≥ 20 (optional — Astro/docs tooling only)

- [Docker](https://www.docker.com/) (PostgreSQL + Redis)

### Setup

```bash

git clone git@github.com:cosmicdriftgamestudio/kumiko-framework.git

cd kumiko-framework

bun install

```

### Run

```bash

# Interactive CLI — shows all commands

bun kumiko

# Or directly:

bun kumiko dev      # Start Docker services (PG:15432, Redis:16379)

bun kumiko test     # Run unit tests

bun kumiko check    # Biome + TypeScript + Tests + Guards

bun kumiko status   # What's running?

bun kumiko stop     # Stop services

bun kumiko reset    # Wipe + restart everything

```

To explore feature patterns hands-on, run any sample:

```bash

cd samples/recipes/basic-entity

bun test

```

## Why use this

- **Built for B2B SaaS / internal tools** — multi-tenant + audit are first-class, not afterthoughts

- **Postgres-native** — no Kafka, no EventStoreDB, no NATS. One database, one source of truth

- **AI-builder ready** — config-driven, every `r.*` call is patchable by AI tools

- **DACH/EU-ready** — self-host on Hetzner / k8s / bare-metal. BYO LLM (Anthropic, OpenAI, Ollama, vLLM)

## Architecture

| Layer | Tech |

|-------|------|

| Runtime | Bun |

| API | Hono |

| DB | Postgres (EntityTableMeta + SQL migrations) |

| Auth | jose (JWT) |

| Search | Meilisearch |

| UI | React + Expo (Web + Mobile) |

| Realtime | SSE via Redis Pub/Sub |

| Tests | bun:test |

Pipeline flow:

```

HTTP Request

  → JWT Auth (Hono middleware)

  → Dispatcher

    → Zod schema validation

    → Access check (entity-level roles)

    → Field-level write check

    → Validation hooks

    → Handler (CrudExecutor → DB)

    → Lifecycle pipeline:

        Feature postSave hooks

        System hooks (priority order):

          1000: Search index (Meilisearch)

          1001: SSE broadcast

          1002: Audit trail (DB)

  → Response (with field-level read filtering)

```

## Samples

Tested, runnable examples per feature. Three buckets:

- [`samples/recipes/`](samples/) — one concept = one feature definition + one test

- [`samples/apps/`](samples/) — full-stack demos with dev-server + browser client

- See the full sample index: [samples/README.md](samples/README.md)

## Live showcase

[publicstatus.eu](https://publicstatus.eu) — open-source statuspage clone built with Kumiko. Multi-tenant, SSE-realtime, deployed on Hetzner. Source: [github.com/cosmicdriftgamestudio/publicstatus](https://github.com/cosmicdriftgamestudio/publicstatus).

## Documentation

Full docs: [docs.kumiko.rocks](https://docs.kumiko.rocks).

## Status

Pre-1.0 — actively developed. APIs may change between minor versions until 1.0. Breaking-change policy and migration guides documented per release in [CHANGELOG.md](./CHANGELOG.md).

Used in production at [publicstatus.eu](https://publicstatus.eu).

## License

Business Source License 1.1 (BUSL-1.1) → Apache License 2.0 on **2030-05-05**.

You may use Kumiko in production for any purpose, **except** providing a platform or service to third parties that allows them to host, deploy, or run their own applications built with Kumiko. This includes managed hosting, SaaS platforms, PaaS, developer platforms, and any multi-tenant managed offering.

Code from any release automatically becomes Apache-2.0 four years after publication.

For commercial licensing or alternative arrangements: marc@cosmicdriftgamestudio.com.

Details: [LICENSE](./LICENSE).

## Hosted platform

Don't want to self-host? [kumiko.rocks](https://kumiko.rocks) is the hosted version with AI-builder, designer, and managed hosting.

## Contributing

PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup + guidelines.

By contributing, you agree your contributions are licensed under the same BUSL-1.1 terms.

---

© 2026 Marc Frost — Cosmic Drift Game Studio.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/cosmicdriftgamestudio/kumiko-framework

Awesome Lists containing this project

README