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 newproduces: 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/weborapps/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 newand 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:
nextfor Next.js, ortanstackfor TanStack Router on Vite.Read more
Making code
The five verbs, which are not interchangeable.
- Scaffold#scaffold
- What
grit newdoes: write a whole project from nothing. Only ever used for the whole project, never for one resource.Read more - Generate#generate
- What
grit generate resourcedoes: 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 upgradedoes: 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 migrateapplies migration files; it never touches your application code.Read more - Sync#sync
- What
grit syncdoes: 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 removecan 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
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
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/accessof 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 updateonly 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.
