Documentation

Gridwillow is a text language for software architecture. You write one .bp file describing a system — its services, stores, queues and the data that moves between them — and the compiler draws it as an isometric blueprint you can pan, hover and click through.

Every reference page here is served twice: as HTML at the link, and as raw markdown at the same URL with .md on the end. If you are a coding agent, the shortest path is /llms-full.txt — one fetch, everything below, enough to write a blueprint that compiles.

Reference

• The .bp language

  The complete language reference — the two rules, the whole syntax on one screen, the eight-shape table, the six connection kinds, every attribute by scope, prose blocks and inline markup, and what the checker treats as an error versus a warning. Read this one first.

• Writing a blueprint

  The procedure to follow against a real codebase: survey before writing anything, choose 15–40 subsystem blocks, trace only the connections you can name, then let bp check grade the result.

• Writing the prose

  How to write is, why and carry so the hover cards are worth opening. The default register of generated documentation is the wrong one here, and this page is about correcting it.

• Keeping a blueprint true

  The procedure for re-checking an existing blueprint against the code it claims to describe — moved paths, deleted functions, new tables — and rewriting only what actually drifted.

Grammar and examples

• /docs/grammar.ebnf

  The formal grammar, in EBNF. The normative answer when the prose reference and your parser disagree.

• /docs/blueprint-ir.schema.json

  JSON Schema for the compiled intermediate form the renderer consumes. You never write this by hand; bp build emits it.

• /examples/payments.bp

  A complete, checked blueprint of a payments platform — 16 blocks, 19 connections, groups, tabs and terms. The worked example, and the file rendered on the front page.

• /examples/self.bp

  Gridwillow’s own architecture as a blueprint — the compiler, the renderer and the app, drawn in their own language.