@rangka/core

Server-side runtime engine for the Rangka framework.

How it works

This package boots a complete Fastify server from declarative model/page definitions. It handles module discovery, schema resolution, database sync, REST API generation, authentication, lifecycle hooks, background jobs, and events. All server-side behavior lives here.

Architecture

src/
├── api/            — Fastify server, route generation, handlers, OpenAPI schema
├── audit/          — Audit trail recording
├── auth/           — JWT sessions, permissions, scopes, field-level access
├── boot/           — Boot sequence: discovery, schema loading, merging, registry init
├── db/             — DatabaseClient, auto-sync (DiffEngine), model-ops (Kysely CRUD)
├── events/         — EventBus (transaction-scoped pub/sub)
├── external-model/ — Adapter-based external data sources
├── fixtures/       — Seed data loading
├── helpers/        — Stamping, ownership checks, validation utilities
├── hooks/          — Hook registry, executor, middleware, context builder
├── jobs/           — Job registry, worker, scheduler, enqueue
├── model-api/      — Query builder, filter translation, scope enforcement, includes
├── plugins/        — Plugin lifecycle, adapter registry, loader
├── schema/         — SchemaRegistry, relationship resolution
├── services/       — ServiceRegistry, service factory
├── validation/     — Field-level validation engine
├── widgets/        — Server-side widget registry (for studio)
├── context.ts      — FrameworkContext builder
├── errors.ts       — AppError, BadRequestError, NotFoundError
└── index.ts        — Public exports

Key internal systems

| System | Entry point | Purpose | | ----------- | ----------------------------- | ---------------------------------------------- | | Boot | boot/index.ts | Orchestrates full server startup | | Schema | schema/registry.ts | Holds resolved models and relationships | | Model API | model-api/index.ts | CRUD with scopes, permissions, filters | | Hooks | hooks/executor.ts | Lifecycle pipeline (validate → before → after) | | Middleware | hooks/middleware.ts | Wraps hooks into Fastify request handlers | | Routes | api/route-generator.ts | Auto-generates REST endpoints per model | | Auth | auth/session.ts | JWT session management | | Permissions | auth/permission-registry.ts | Role-based model/field access | | Scopes | auth/scope-registry.ts | Row-level tenant isolation | | Services | services/registry.ts | Named business logic with DI | | Jobs | jobs/registry.ts | Background job processing | | Events | events/bus.ts | Transaction-scoped pub/sub |

Commands

pnpm --filter @rangka/core build   # Compile TypeScript
pnpm --filter @rangka/core test    # Unit tests
pnpm test:integration              # Integration tests (from repo root)

Contributing

• All data access in hooks/services goes through ctx.models (the ModelAccess interface). Never write raw Kysely for basic CRUD.
• All hooks/services/jobs receive FrameworkContext. Use it. Don't build parallel context objects.
• The hook pipeline is fixed: validate → beforeSave → (write) → afterSave. Don't add new phases.
• Route handlers are auto-generated by route-generator.ts. Don't duplicate CRUD routes manually.
• Registries are singletons created at boot. Extend existing ones, don't create new ones for the same purpose.
• Helper utilities (helpers/stamping.ts, helpers/validation.ts, helpers/assert-ownership.ts) must be reused. Don't recreate stamping or ownership logic.
• This package imports from @rangka/shared only. Never import from @rangka/client.