GoLocomotiveDevelopers
How a GoLocomotive app is made: locosdk, schema.ts, the server, the client, the UI and the loco cli.
Every GoLocomotive app is one TypeScript repo on one dependency, locosdk. The app holds its schema, its pages and its hooks. Everything generic lives in the sdk: the database, the API, sign in, the data layer, the UI shell, the review cards and the release tools.
This section is for a developer, or an agent, who reads or changes an app. The Reference holds the full tables.
One process per app#
An app runs as one Bun process. That process serves the API, the pages, a small admin and one SQLite file. There is no shared database and no tenant column: each app has its own data folder.
The storage, the REST wire and the filter language copy PocketBase. A PocketBase database opens as is, and a model that knows PocketBase already knows the API.
The tiers#
locosdk exports four tiers and a cli. A lower tier never imports a higher one.
| import | what it owns |
|---|---|
locosdk/schema | field builders, defineSchema, the inferred record types, the audit journal collection, the mail templates |
locosdk/server | createApp: SQLite in PocketBase's layout, the rule compiler, the records API, auth, files, hooks, crons, mail, backups, the MCP server |
locosdk/client | the typed fetch client and the MobX data layer: lists, records, aggregates, batched writes |
locosdk/ui | the Mantine shell, sign in, grids, record cards, the schema form, the journal screens, the what's new modal |
loco | the cli in the app repo: gate, review cards, shots, releases, backups, schema import, superusers |
Two rules hold everything#
- The server does the work. Filtering, sorting, paging, relations and sums run on the server. A screen never downloads a collection to filter, count or sum it. The data layer classes make this the easy path.
- Server rules are the law. Each collection declares who can list, view, create, update and delete, in the filter language. The records API applies them on every request. A check in the UI only helps the user.
In this section#
| page | read it when you |
|---|---|
| An app, step by step | start an app or want the whole picture in one place |
| Anatomy of an app | look for a file, or need the contract with the host |
| Schema as code | add a collection, a field, an index or a view |
| Rules and filters | decide who sees and changes what |
| Server: hooks, routes, crons | add behavior on the server |
| Client and data layer | read or write data from a page |
| UI: shell, grids, forms | build a screen |
| Auth and mail | change sign in, codes, mails |
| Files, backups and proxies | store files, back up data, run behind a proxy |
| The MCP server | let a client's own AI work in the app |
| Review cards and shots | show a change to the client |
| Changelog and releases | ship a version |
| Coming from PocketBase | move a PocketBase app |