What each piece does, and where to check it.
Each line below names the function, file or doc that backs it. The plain version is on Building blocks.
Every dependency, from prisma-map up.
- Building blocks
- Developer experience
- Done
- Builds on
- Reads its map
- Template will adopt
Hover or focus a piece to light what it builds on and what builds on it.
- templateThe whole SaaS appBuilt on prisma-map, json-rules, permissions, rules-builder, atlas, transitions, gloss
- rules-builderRule screensBuilt on json-rules
- transitionsLifecyclesBuilt on json-rules, permissions
- permissionsWho can do whatBuilt on prisma-map, json-rules
- json-rulesRulesBuilt on prisma-map
- prisma-mapData shape
Read the map as text
How to read the map: colour shows which part a piece belongs to (amber building blocks, teal developer experience, lime agentic, blue outside your machine, violet governance; charcoal marks closed source and pink marks a connection that goes through a Signet). Fill shows status: a solid block is done, a block in scaffolding is under construction, a dashed outline is planned. Lines show the relation: solid builds on or runs with, dotted reads prisma-map's map, pink goes through a Signet, a scaffold-dashed line is under construction (on the technical graph: what template will adopt), a long-dashed grey line reaches a planned piece.
- prisma-map: Your Prisma schema, readable at runtime. Built on config.
- json-rules: One rule that runs in memory, in Prisma and in SQL. Built on prisma-map (reads its map), config.
- permissions: RBAC, ABAC and ReBAC on your own records. Built on prisma-map (reads its map), json-rules, config.
- transitions: Declarative lifecycles. Built on json-rules, permissions, config.
- rules-builder: A headless rule builder. Built on json-rules, config.
- atlas: A map of your code. Built on json-rules, config.
- gloss: Explanations kept out of the source. Built on config.
- config: The shared toolchain and theme.
- worktrees: A worktree per task, with its own database and ports.
- init: Sets up hosting, database and secrets for a new project.
- CI rules: Checks that hold the codebase to its own conventions.
- template: The whole SaaS app, built from the libraries. Under construction. Built on prisma-map, json-rules, permissions, rules-builder, atlas, config, worktrees, init, CI rules, transitions (to adopt), gloss (to adopt).
An API, web, admin and superadmin apps and a shared UI package.
- Sign-inBetterAuth for email/password and OAuth, then an ES256 JWT per person; API tokens for scripts. No session cookies. Doc
- TenancyOrganizations and spaces, each with memberships and roles (owner, admin, member); a space membership needs the org membership first. Doc
- PermissionsDeclarative rules over the data graph, checked by the permissions package. Doc
- Field-level encryptionAES-256-GCM per field, declared in the ENCRYPTED_MODELS registry; the rotateEncryptionKeys job re-encrypts records on a stale key. Doc
- Audit logModels listed in AUDIT_ENABLED_MODELS get an immutable trail of every mutation, with its actor and subject. Doc
- Background jobsmakeJob, makeSingletonJob and makeSupersedingJob on BullMQ, staged jobs that fan out and wait, and rolling caches. Doc
- WebhooksSubscriptions per organization or space, RSA-SHA256 signatures, delivery through jobs with retries and tracking. Doc
- Live dataAuthenticated WebSockets with open/snapshot/append/close data streams and authorized query channels over Redis pub/sub. Doc
- EmailStored MJML templates and components, a planner that picks the template, preferences and verification. Doc
- Routes write their own contractAdd a route and controller; it registers itself, emits OpenAPI 3.1 and regenerates a typed SDK. Doc
- Responses checked against the specA controller can only send the responses its route declares, and payloads are validated at runtime. Doc
- Errors as a systemOne error body everywhere, with guidance per status and request correlation. Doc
Building blocks, in dependency order from the bottom up.
prisma-map sits at the bottom: json-rules and permissions read your schema through it. Transitions builds on permissions, and rules-builder on json-rules. Each is MIT and published on npm.
prisma-map
Your Prisma schema, readable at runtime.
- buildPrismaMapV6 and buildPrismaMapV7 read models, fields, relations, foreign-key direction and enums from a generated Prisma client.
- getRelations, relationForeignKey, getColumns and pickColumns let rules and permissions walk your data graph without reaching into Prisma's internals.
json-rules
One rule that runs in memory, in Prisma and in SQL.
- One rule AST: check evaluates it in memory, toPrisma turns it into a Prisma where, and toWhereSql into a SQL WHERE clause for PostgreSQL or MySQL.
- Rules are plain JSON. Store them, send them, let a tenant write one.
- Operators, paths and bindings (bindRule, listBindings) are type-checked against your models.
permissions
RBAC, ABAC and ReBAC in one engine, decided on your own records.
- No separate tuple store to keep in sync. createRebacCheck decides on the rows you already have, walked through the schema map you pass; createHydrator loads them through your own load function.
- Entitlements and delegates: a grant is checked again against whoever granted it, every time it is used. You can only hand on what you could do yourself.
- Rules are json-rules, down to a rule a tenant writes on one record.
- A small core you can read. Its runtime dependencies are json-rules and lodash-es.
transitions
Declarative lifecycles on json-rules.
- checkTransition guards a proposed change and returns why it failed; available lists the actions open on one record; eligible compiles the same rules into a Prisma query for every record an action is open to.
- createAuthorize hands each side's permission rule to @inixiative/permissions.
- Workflow rules and permission rules are written in the same language.
rules-builder
A headless rule builder that only offers what the engine can run.
- useRuleBuilder is a React hook that builds conditions against the fields and operators the engine supports. Bring your own components.
- useTransitionBuilder builds transitions the same way; parseSavedRule and stringifySavedRule store what people build.
Tools for working on the code. None of them ships in your product.
Atlas, gloss and config are packages of their own; template uses atlas and config. Worktrees, init and the CI rules ship in template's repo.
atlas
gloss
Agent commentary kept out of your code.
- The agent records what it found useful, or what you want kept, as a gloss beside the symbol. In law, a gloss is a note in the margin that explains a text.
- Glosses live in a mirrored tree: src/foo.ts gets .gloss/src/foo.ts.md. checkRepo and fileStaleness report glosses that no longer match their code.
config
worktrees
Comes with template: bun run worktree:create.
- Each worktree gets its own Postgres databases, Redis database, storage buckets and ports (scripts/worktree/create.sh); worktree:destroy frees them.
- --skip-db makes an edit-only worktree that needs no Docker.
init
Comes with template: bun run init.
- A terminal app (init/) that provisions GitHub, PlanetScale, Railway, Vercel, Cloudflare and Resend, and keeps their secrets in Infisical.
CI rules
Comes with template: run by bun run check.
- Repo-owned rules in scripts/ci/rules/ fail on a raw lock, a raw transaction, a second middleware chain and similar bypasses of existing systems.
- doc-freshness fails when a doc names a path, symbol or line that no longer exists.