Say what must be true
A short spec: the entities, what happens to them, and requirements such as durable, shared by several instances, never lost, in order.
Open source · MIT · v0.3.5
Say what must be true. Get the Go.
tilegen is a compiler from architectural requirements to a Go project. You say the data must survive a restart and no event may be lost. It picks the database, the broker, the transport, the sign-in and the secrets at the lowest cost, writes the code, and shows why.
01 / The tour
Every feature, in 12 chapters and 25 minutes.
Recorded against tilegen v0.3.5 itself: the studio is the real compiler, and the terminal chapter is real output. Captions are on screen; there is no sound. Pick a chapter or let it play through.
02 / How it works
Requirements are the input. Tools are the output.
Most scaffolding starts by asking which database you want. tilegen starts one step earlier, with what the system has to do, and treats the choice of tools as something to compute.
Every tile is priced
A tile is one concrete way to meet a need. Each declares what it guarantees, what rules it out, and six costs, from work left for an LLM to what it takes to operate.
The cheapest legal design wins
tilegen finds the lowest-cost set of tiles that can do everything asked, using the tree tiling that compilers use to select instructions. Your team's weights set the prices.
The project is written
Types, interfaces, SQL, protobuf, wiring and a lock file are generated. What needs judgment is left as a typed method with its intent written down.
(project orders
(module github.com/acme/orders)
(go 1.22)
(require (uuid github.com/google/uuid v1.6.0))
(app)
(package orders
(entity Order
(field ID uuid.UUID)
(field CustomerEmail string)
(field TotalCents int64)
(store get list save (durable) (cross-process)))
(events
(durable) (at-least-once) (cross-process)
(event OrderPlaced (field OrderID uuid.UUID))
(outbox Order))
(api (get Order) (list Order) (save Order) (typed-clients))))$ tilegen explain spec.sexp orders.API (api) needs: typed-clients chosen by: auto chosen connect score 16 llm 2·4 + maint 2·3 + dep 2·1 grpc score 17 llm 2·4 + maint 2·3 + dep 3·1 illegal http-json there is no schema: every client writes its own requests and types ... orders.Bus (event-bus) needs: durable, at-least-once, cross-process chosen by: auto chosen nats-jetstream score 47 llm 5·4 + maint 3·3 + dep 4·1 + run 2·1 + ops 4·3 kafka score 70 llm 5·4 + maint 5·3 + dep 4·1 + run 4·1 + ops 9·3 illegal local-bus an in-process bus loses undelivered events on restart illegal nats-core core NATS is fire-and-forget: a message with no connected subscribe... illegal rabbitmq unverified: a durable exchange, a durable queue and persistent mess... illegal redis-streams durability is an operator setting: under the default append-only po... orders.OrderStore (store) needs: durable, cross-process, outbox chosen by: auto $ tilegen -out orders spec.sexp ... 7 open LLM task(s), 0 hole(s) already filled -> orders/tilegen.tasks.json next: cd orders && buf generate && sqlc generate && go mod tidy && go build ./...
What it does not do. tilegen writes everything that follows from the spec, and the
project builds. It does not write your business logic: store and bus method bodies are left as holes,
each a typed method with its intent, for you or an LLM to fill. tilegen prompt prints a
self-contained prompt for each one.
03 / The catalogue
23 tiles. Each one knows what it can promise.
Ask for something a tile cannot do and it is ruled out, with the reason in its own words. Ask for things no tile can do together and tilegen refuses, and says why each one is out.
API How clients call it
- connecta .proto and a Connect server
- grpca .proto and a grpc-go server
- http-jsonnet/http and JSON
Sign-in How callers prove who they are
- api-keya long-lived key per caller, resolved by a lookup you supply
- jwt-locala token this service signs and verifies itself, with no lookup
- oidcan identity provider issues tokens; this verifies them against i
- session-storean opaque session id in a cookie, looked up in a store on every
Event bus How events travel
- kafkaKafka as an inbound edge
- local-busin-process bus
- nats-corecore NATS
- nats-jetstreamNATS JetStream
- rabbitmqRabbitMQ
- redis-streamsRedis Streams
Store Where data lives
- badgerembedded key-value
- boltembedded key-value
- memoryin-memory store
- mongomongo
- postgres-pgxpostgres via pgx
- postgres-sqlcpostgres via sqlc
- sqlite-sqlcsqlite via sqlc
Secrets Where credentials come from
- env-secretsenvironment variables, read once when the process starts
- file-secretsone file per secret in a mounted directory, read on every call
- vaultone path of a HashiCorp Vault KV v2 mount, read through a short
Transport How a bus reaches another process
- kafkaKafka as an inbound edge
- nats-corecore NATS
04 / The studio
Tick boxes. Watch the design change.
The studio is tilegen compiled to WebAssembly, running in your browser. Nothing you type leaves the page. Tick requirements, read why each tile won, open the architecture diagram, and download the project as a zip.
05 / Install
One binary.
Go is the only thing tilegen itself needs. Some tiles need a build tool, such as sqlc or buf; tilegen says which, and prints the command to run.
$ brew install vinodhalaharvi/tap/tilegen # or: go install github.com/vinodhalaharvi/tilegen@latest $ tilegen explain spec.sexp # why each need got its tile $ tilegen -out orders spec.sexp # write the project $ tilegen check spec.sexp # for CI: stale code or open holes fail $ tilegen serve # the studio, from the same binary
$ tilegen -out orders spec.sexp ... 7 open LLM task(s), 0 hole(s) already filled -> orders/tilegen.tasks.json next: cd orders && buf generate && sqlc generate && go mod tidy && go build ./... $ cd orders && buf generate && sqlc generate && go mod tidy && go build ./...
06 / Documentation
Read it before you trust it.
The documentation here is the repository's own, so it cannot drift from the code it describes.
The guideThe spec language, every form in it, how tiles are chosen, policies, drafts, and handing holes to an LLM.
Running itSetting up locally, every make target, what each generated file is, and troubleshooting.
The tilesThe registry in full, worked selections with real numbers, the cost model, and how to write a tile.
Open source
MIT licensed. The decisions are yours to read.
Every cost, every guarantee and every rule that rules a tile out is a line in the repository. If you disagree with one, change the weight, switch the tile off, or send a pull request.