← Back to all projects
🏗️

Open source · vishwajit-vm Designed · Phase 1

Strutvane Framework

Backend & database core: models, migrations, CRUD API, OpenAPI

@strutvane/framework is the backend and database heart of Strutvane. You describe a model as fields and types; it produces the database migration, a secured CRUD API with filtering, search, sorting and paging, OpenAPI 3.1 documentation and a typed client — plus queues, schedules, cache and mail. It is fully designed; implementation starts in Phase 1.

10 routes per modelOpenAPI 3.12 spikes · 74 tests

Built for: API and full-stack TypeScript developers building B2B backends.

Packages on npm

↓ Scroll to explore the problem, architecture and stack

😩

The problem

Each new resource in a typical Node backend means hand-writing a migration, a controller, validation, pagination, filtering, permission checks and docs — the same boilerplate, slightly different every time, and easy to get subtly wrong.

💡

Why it matters

One model definition drives the database, the API and the docs, through one carefully designed request pipeline. Developers keep full control with hooks, custom actions, handler overrides or sv eject api when they need it.

What you can do with it

01Define models with defineModel and field.* builders (string, decimal, enum, belongsTo…).
02Get auto-diffed SQL migrations, plus manual migrations, seeders and factories — or introspect an existing database with sv db:pull.
03Get 10 routes per model: list, show, create, update, replace, delete, restore, bulk, export and query.
04Filter, search, sort, page (keyset or offset), include relations and choose fields with one list protocol: filter[field][op].
05Read OpenAPI 3.1 at /openapi.json, browse docs at /docs and use a generated typed client.
06Use queues, schedules, cache, mail, a transactional outbox and API versioning.

How it’s built

A simplified view of the architecture — follow the dots as a request moves down the layers.

HTTP
Host adaptersHono · Express · Fastify · Nest
Resource engine
Request pipelinevalidate · authorize · scope
Hooks & actions
Data adapter
Drizzle + Kyselybehind an internal adapter
Migratorowned rename resolution
Databases
PostgreSQLtier 1
SQLite · MySQL

A request, step by step

  1. A request arrives at the HTTP host and is parsed into a typed list or write operation.
  2. Input is validated with Zod; the permission provider authorizes it and adds the tenant and policy filter.
  3. Before-hooks run, then the handler executes the query through the data adapter.
  4. After-hooks run; the audit entry and outbox events are written in the same transaction.
  5. Only visible fields are serialized; errors return as RFC 9457 problem+json.

Tech stack

Runtime
Node.jsTypeScriptHono
Data
PostgreSQLSQLiteMySQLDrizzleKysely
API
🔗RESTOpenAPI 3.1Zod 4
Jobs
BullMQValkey
Observability
OpenTelemetry

What I built

  • Designed the model DSL, the resource (CRUD) engine and the request pipeline: parse → validate → authorize → scope by tenant and policy → before-hooks → handler → after-hooks → audit and outbox → serialize.
  • Proved the database layer in spike 01 (23 tests on Postgres and SQLite) and the resource pipeline in spike 05 (51 tests).
  • Chose to own rename resolution in migrations after drizzle-kit 0.31 proved unreliable: the migrator asks instead of guessing, records the answer in the migration header and blocks destructive changes (ADR-0009).
  • Designed a custom OpenAPI serializer, because OpenAPI can’t express filter[field][op] and the alternatives failed strict type-checking or missed routes (ADR-0011).
  • Specified an advisory lock so migrations never run twice across replicas.

Hard problems & how I solved them

❓ Migrations that never lose data.

✅ Strutvane owns rename detection — it asks, records the answer and blocks destructive changes, instead of trusting a tool that guesses (ADR-0009).

❓ Documenting a rich filter syntax.

✅ A custom OpenAPI serializer describes filter[field][op] faithfully, and the docs page is self-hosted (ADR-0011).