Reference

Glossary

Every word Grit uses that is not ordinary Go or React, in one sentence each. 71 terms. Each one has its own link, so anything can point at the exact definition: /docs/glossary#row-rule.

The shape of a project

What grit new produces, and the words for its parts.

Project#project
Everything one grit new produces: the root directory and every app inside it.Read more
Appalso called: service#app
One deployable unit inside a project, such as apps/api, apps/web or apps/admin. A project has several; an app is one of them.
Package#package
A shared library under packages/, such as packages/shared, which holds the types and schemas both the API and the frontend use. Not an app, and not a Go module.Read more
Architecturealso called: tier, mode#architecture
Which apps a project has: triple, double, single, api or mobile. Chosen at grit new and awkward to change afterwards, so it is the first question the CLI asks.Read more
Triple#triple
The Go API, a customer-facing Next.js web app and a separate Next.js admin, in one monorepo. The default, and the right choice when the operator console should not look like the customer app.Read more
Double#double
The Go API plus one frontend, with the admin as a route group at /admin inside it.Read more
Single#single
One frontend that is also the project root, with the Go API beside it and the admin as a section of the router. The frontend is at the root, not in apps/web.Read more
Frontend (the choice)also called: vite, spa#frontend
Which router and bundler the React apps use: next for Next.js, or tanstack for TanStack Router on Vite.Read more
Style#style
Which admin dashboard layout is written: default, modern, minimal or glass. Decided once, at generation.Read more
Theme#theme
Which colour variables the admin uses, such as aurora or emerald. Unlike a style, a theme can be changed at runtime.Read more

Making code

The five verbs, which are not interchangeable.

Scaffold#scaffold
What grit new does: write a whole project from nothing. Only ever used for the whole project, never for one resource.Read more
Generate#generate
What grit generate resource does: add one resource to a project that already exists, by writing new files and injecting lines into existing ones.Read more
Upgrade#upgrade
What grit upgrade does: bring an existing project up to the CLI version you have installed. Nothing to do with the database.Read more
Migrate#migrate
Database schema only. grit migrate applies migration files; it never touches your application code.Read more
Sync#sync
What grit sync does: regenerate the TypeScript types, Zod schemas and error codes from the Go models, so the two sides cannot disagree.Read more
Resourcealso called: entity, model#resource
One thing your application stores, such as Invoice or Contact, and everything generated for it: the model, service, handler, routes, types, schema, hooks and admin screens.Read more
Field type#field-type
What a field is, in the generator’s vocabulary: string, money, image, belongs_to, enum and about thirty others. The field type decides the database column, the Go type, the validation, the form input and the table cell all at once.Read more
Definition file#definition-file
A YAML file describing a resource, used instead of a long --fields string when a resource has many fields or you want it in version control.Read more
Injection#injection
Adding a line to a file your project already has, at a named anchor, so a newly generated resource appears in the route table and the sidebar. It is why grit remove can take it out again.
Anchor#anchor
A marker comment in a generated file, such as // grit:models, that tells the generator where to inject. Deleting one does not break the build; it quietly stops future resources appearing there.
Framework-owned file#framework-owned
A file Grit writes and maintains, which travels on every upgrade. Editing one means your change is overwritten the next time you upgrade.Read more
Manifest#manifest
The record in .grit/ of every file Grit has written and what it looked like. It is how grit upgrade can tell a file you edited from one you have not touched, and leave yours alone.Read more
Repair#repair
A targeted rewrite applied during an upgrade to a file the project may have edited, where replacing the whole file would throw your changes away.Read more

The admin panel

The screens an operator uses, and how they are described.

Admin panel#admin-panel
The operator-facing screens over your data, in whichever of the three shapes your architecture gives you.Read more
Admin app#admin-app
The admin as its own application at apps/admin, with its own port and container. Only a triple project has one.Read more
Embedded panel#embedded-panel
The admin as a route group at /admin inside the web app, which is what a double project has.Read more
Resource definition#resource-definition
The file that describes an admin screen: which columns, which filters, which form fields. Change the definition and the table, the form and the detail view all follow.Read more
Widget#widget
A dashboard block: a statistic, a chart or an activity feed. A good one answers a question somebody asks at the start of the day rather than showing a number.Read more
System pages#system-pages
The operational screens that come with the admin: jobs, files, cron, mail preview, trash, sessions, API keys and the route table.Read more
Bulk actions#bulk-actions
Creating or editing many rows at once through a grid on a list screen, with each row validated against the model’s own rules so a bad row reports itself rather than failing the batch.Read more
Saved view#saved-view
A named combination of filters, sort and columns on a list screen, so an operator does not rebuild the same query every morning.Read more
Trash#trash
The screen listing soft-deleted records, from which they can be restored. It exists because somebody will delete the wrong row.Read more

Data and the backend

The layers a request passes through, and the patterns in them.

Model#model
A Go struct that maps to a database table, with tags describing the column, the JSON name and the validation rules.Read more
Handler#handler
The function that turns an HTTP request into a service call and the result back into a response. It holds no business logic.Read more
Service#service
Where the business rules live, and where a transaction begins and ends. Called by handlers, by jobs and by the CLI alike.Read more
Seeder#seeder
Code that puts starting data into a database: an admin account, reference data, or realistic rows for development. Run with grit seed.Read more
AutoMigrate#automigrate
GORM comparing your structs to the database and adding what is missing. Right for development, and not for production, because it never drops or renames and cannot be reviewed before it runs.Read more
Soft delete#soft-delete
Marking a row deleted rather than removing it, so it disappears from queries and can be restored from the trash.Read more
Sequence#sequence
A gap-free counter for things like invoice numbers, implemented with a locked row rather than a database sequence, because a database sequence does not roll back.Read more
Outbox#outbox
A table that holds events written in the same transaction as the data they describe, so an event cannot be lost when the process dies between the write and the publish.Read more
Saga#saga
A multi-step operation where each step has an undo, so a failure partway through runs the undos backwards. Used when the steps span services and no single transaction covers them.Read more
Append-only table#append-only
A table the application may insert into and never update or delete, enforced by database grants and a trigger. Used for audit entries.Read more
N+1 query#n-plus-one
One query for a list and then one more for each row in it, usually from reading a relation inside a loop. Invisible locally and expensive in production.Read more

Access and security

Who is calling, and what they may touch.

Permission#permission
One thing a user may do, such as invoice.delete. Code checks the permission rather than the role, so changing policy does not mean editing handlers.Read more
Role#role
A named bundle of permissions, such as admin, editor or viewer, assigned to a user.Read more
Policy#policy
A function that sees both the user and the record and decides whether the action is allowed. Used for rules a role cannot express, such as "the author may edit their own post for thirty minutes".Read more
Row rule#row-rule
A scope that is part of the query, so a record belonging to somebody else cannot be returned at all. A permission answers 403 and a row rule answers 404, because a 403 would confirm the record exists.Read more
owned-by#owned-by
The generator flag that puts the owner into every query a resource produces, including the list, the bulk actions and the export, so the rule does not depend on remembering it.Read more
Confidential resource#confidential
A resource an administrator cannot read either. Stricter than ownership, and deliberately not something the role system can grant.Read more
Tenantalso called: organisation, workspace#tenant
One customer’s slice of a shared system, usually an organisation. Every tenant-owned table carries its id, and every query filters on it.Read more
Session#session
A row backing one refresh token, so signing out of a device means something. It is what makes per-device revoke and an active-sessions screen possible.Read more
Refresh rotation#refresh-rotation
Issuing a new refresh token every time one is used, so a token that arrives twice has been stolen and the whole family is revoked.Read more
API key#api-key
A credential for a machine rather than a person: scoped, stored hashed, rotatable, with the last use recorded.Read more
Audit log#audit-log
A record of who did what, chained so that altering or removing an entry is detectable. Tamper-evident rather than tamper-proof.Read more
Route table#route-table
The static list in internal/access of every route and what guards it. It exists because a web framework cannot report its own middleware chain at runtime, so without it nothing can answer whether an endpoint is protected.Read more

Batteries and extensions

The parts you turn on rather than build.

Battery#battery
A capability that comes with a generated project rather than being installed: caching, the job queue, file storage, email, cron, AI. "Batteries included" means these are already wired.Read more
Plugin#plugin
Something you add to a project with grit plugin add, which writes real files into your repository rather than adding a dependency that hides behind an interface.Read more
Blueprint#blueprint
A whole application built with Grit that you start from, rather than a feature you add. A separate repository, not part of the scaffold.Read more
Jobalso called: worker, task, background job#job
Work done outside the request, on a queue, so a slow email provider does not slow your API down. Retried with backoff, and visible in the admin.Read more
Cron#cron
Work on a schedule. It must run on exactly one instance however many you deploy, which is why the scheduler is not simply started inside the API.Read more
Storage driver#storage-driver
Where uploaded files go: local disk, MinIO, S3, Cloudflare R2 or Backblaze B2. One environment variable chooses, and the application code is the same for all of them.Read more
Presigned URL#presigned-url
A time-limited permission to upload one file to one key, signed by your server so the browser can send the bytes straight to storage without them passing through your API.Read more
Realtime#realtime
Pushing updates to a connected client. Across more than one instance it needs a Redis backplane, because a connection belongs to exactly one process.Read more
Vector field#vector-field
A field storing an embedding in Postgres with pgvector, so a similarity search can find passages that mean the same thing rather than ones that share words.Read more

Tools and companions

The separate products a generated project uses.

grit doctor#doctor
An offline check of a project against the things that are commonly wrong. It reads files and compiled-in floors and never the network, which is what makes it usable in CI.Read more
GORM Studio#studio
A database browser embedded in the generated API at /studio. A separate project of ours, so a bug in it is an issue on its repository.Read more
Pulse#pulse
Request observability: what each request did, which queries it ran and where the time went. A separate project of ours.Read more
Sentinel#sentinel
The rate limiter and web application firewall in front of the API. A separate project of ours.Read more
Scout#scout
A security scanner, fed the generated route table so it knows which endpoints are meant to be protected. Opt-in with grit add scout.Read more
Grit UI#grit-ui
A standalone React component library. Not part of a generated project, and deliberately not added to the scaffold.Read more
Release channel#release-channel
Whether a version is stable or a prerelease. A version is stable unless it carries an -rc, -beta or -alpha suffix, and grit update only moves you between stable releases.Read more

A word that is not here

Three are deliberately left out, because they are in circulation without an agreed meaning and using them without saying which sense you mean causes confusion: the site (the marketing pages, or the whole web app), the dashboard (the admin's landing screen, or its whole authenticated area) and tier (fine with a number attached, misleading alone). Say which one you mean.