Skip to main content
The Lacanians
Engineering8 min read

Blueprint Lang: A Declarative DSL That Compiles to TypeScript You'd Actually Ship

Blueprint is a declarative language for writing web services that compiles to production-ready TypeScript. No runtime dependency, no vendor lock-in -- just clean Hono, Drizzle, and Zod code that happens to be generated from a language you can read in five minutes.

A

Abdul Hamid Achik

·Updated

The Problem with Generated Code

Most code generation tools produce code that looks like it was written by a committee of interns during a hackathon. Sprawling utility functions nobody asked for, framework abstractions three layers deep, configuration files that outnumber your actual source files. You end up maintaining the generator’s opinions instead of your own application.

Blueprint takes a different position: what if the generated code was just… normal? Standard libraries, standard patterns, standard TypeScript. The kind of code a senior engineer would write if they had infinite patience and zero tolerance for boilerplate.

What Blueprint Actually Is

Blueprint is a declarative DSL for defining web services, and its compiler, bp, is written in Go. You describe your API endpoints, data models, middleware, and background jobs in a flat, readable .bp syntax. The default target turns it into a TypeScript project using Hono for routing, Drizzle ORM for database access, Zod for validation, BullMQ for job queues, and Vitest for tests. The same source can also target FastAPI and SQLAlchemy, though that Python target is still an advanced beta and the Node target is the mature path. The full language and CLI reference lives at blueprint-lang.dev.

The generated code has no required dependency on Blueprint. Delete the .bp files, uninstall the compiler, and your application still runs. There is no runtime, no framework, no SDK to vendor-lock you into the ecosystem. When you are ready to own the output outright, bp eject strips the “Generated by” markers.

The Arrow System

Blueprint’s syntax is built around a visual data flow that reads like a diagram:

@ "Create a new todo"
POST /api/todos {
  <- title string required
  |> todo = save todo { title: title }
  -> 201 { id: todo.id, title: todo.title, done: todo.done }
}

Four symbols cover most of what you read (a fifth, @>, comes up below):

  • @ declares intent: what this endpoint does, in plain language
  • <- marks input: data flowing into the handler
  • |> marks a processing step: data being transformed
  • -> marks output: data flowing out to the client

Read it top to bottom and you have a complete picture of the request lifecycle. No scrolling through middleware chains, no tracing through dependency injection containers, no grepping for where the response actually gets sent.

What the Compiler Produces

That todo endpoint compiles to this TypeScript:

todosRoutes.post('/api/todos', zValidator('json', postTodosSchema), async (c) => {
  try {
    const title = c.req.valid('json').title;
    const todo = (await db.insert(schema.todo)
      .values({ title: title })
      .returning())[0];
    return c.json({ id: todo.id, title: todo.title, done: todo.done }, 201 as const);
  } catch (err) {
    if (err instanceof BpError) return c.json({ error: err.message }, err.statusCode);
    throw err;
  }
});

Hono route. Zod validation. Drizzle insert. Typed response. The intent line becomes a comment above the route and the summary in the generated OpenAPI document. This is code you would write by hand. The compiler just writes it faster and never forgets the validation middleware.

Flat by Force

Blueprint has no if/else. No for loops. Ordinary blocks nest at most one level deep. This is not a limitation, it is a design decision.

Instead, Blueprint provides constrained alternatives:

@ "Complete a todo if it exists"
PATCH /api/todos/:id/complete {
  <- id uuid required

  |> todo = fetch todo(id)
  |> guard todo -> 404 "Todo not found"

  |> update todo { done: true }
  -> 200 { id: todo.id, done: true }
}

guard handles validation and early returns. when handles conditional logic. map handles iteration. try/recover handles runtime errors. Every handler reads as a linear sequence of steps, because that is what HTTP handlers actually are: receive input, validate it, do something, return output.

The flatness constraint is not about taste. It is about making the code readable for both humans and LLMs. Deeply nested control flow is where bugs hide. Blueprint forces them into the open.

Models and Enums

Data modeling follows the same flat philosophy:

model todo {
  id         uuid      primary
  title      string    required
  done       bool      default(false)
  created_at timestamp default(now)
}

enum Priority {
  low
  medium
  high
  critical
}

The compiler generates Drizzle schema definitions, Zod validators, and TypeScript types from these declarations. One source of truth, three outputs. Change the model, and the validation, types, and database schema all update together. The generated project also includes a typed frontend client package, so your UI shares the same contract.

LLM-Native Design

Here is where Blueprint gets interesting. The language was designed from the ground up to work with AI code generation – not as an afterthought, but as a core design principle.

Intent annotations (@) are not throwaway comments. They are part of the language: they carry through to generated code comments and the OpenAPI summary, and they tell any LLM reading the file what a block is supposed to do. When an LLM generates Blueprint, the intent annotation provides a built-in correctness check: does the implementation match the stated intent?

Generation slots take this further:

@ "Normalize a submitted name"
POST /api/names {
  <- name string required

  @> "reject names longer than 200 characters with status 400"
  -> 200 { name: name }
}

The @> marker, followed by a quoted prompt, is an explicit invitation for an LLM to fill in the implementation. Running bp generate sends each slot to the Anthropic API (you need an ANTHROPIC_API_KEY) and prints a preview of the rewritten source. Add --write and the slot is replaced in your .bp file by ordinary Blueprint statements such as a guard. The @> marker disappears, replaced by actual logic you can read, review, and modify. It is still preview functionality, so run bp check on the result, and note that bp build refuses to run while any slot is unresolved.

This is a fundamentally different approach from “AI writes all your code.” Blueprint defines the structure, the contracts, the data flow. The LLM fills in the business logic where you explicitly ask it to. You maintain control over the architecture while delegating the implementation details that are tedious but well-defined.

Beyond CRUD

Blueprint handles more than REST endpoints. The same flat, declarative syntax extends to:

Middleware:

middleware require_auth {
  before {
    |> guard header.X-API-Key -> 401 "Missing API key"
    |> key = query api_key where(key_hash == hash(header.X-API-Key)) first
    |> guard key -> 401 "Invalid API key"
    |> inject key as auth
  }
}

Endpoints opt in with use require_auth, and the injected auth value is available in the handler body.

Background workers:

worker send_welcome_email {
  trigger queue("welcome_emails")
  retry 3 backoff(exponential, base: 1s, max: 30s)

  <- user_id uuid
  |> user = fetch user(user_id)
  |> log "Sending welcome to {user.email}" level(info)
}

WebSocket and SSE streams, scheduled jobs, test suites – all using the same arrow syntax, the same flat structure, the same principle of making data flow visible at a glance.

Why This Matters

We build production systems for companies that cannot afford to ship vibe code. The irony of most code generation tools is that they produce exactly the kind of code that creates tech debt: functional but fragile, clever but unmaintainable, fast to write but slow to debug.

Blueprint inverts this. The generated TypeScript is boring in the best possible way. It uses the libraries your team already knows. It follows patterns your linter already enforces. It produces code that a new hire can read on day one without needing to understand a custom framework.

The DSL itself is learnable in an afternoon. The arrow system is intuitive enough that non-engineers can read a .bp file and understand what an endpoint does. That matters when you are reviewing AI-generated code, because the first question is always: does this do what I think it does?

Blueprint makes that question easy to answer. And that is the entire point.

Getting Started

Blueprint is open source and MIT licensed. Install the CLI, scaffold a project, and define your first model and endpoint. The compiler will generate a complete, runnable Hono application with typed routes and validated inputs, and it can emit a contract test suite too.

# Install Blueprint (macOS / Linux), or build from source with Go:
# git clone https://github.com/abdul-hamid-achik/blueprint && cd blueprint
# go build -o bin/bp ./cmd/bp
brew install abdul-hamid-achik/tap/bp

# Scaffold a new project
bp init my-api
cd my-api

# Validate the source
bp check my-api.bp

# Build, install dependencies, and start the service (needs DATABASE_URL)
bp run my-api.bp

# Or just generate the TypeScript project (add --gen-tests for tests)
bp build my-api.bp --target node --out generated

# Rebuild and restart on every change
bp dev my-api.bp

# Preview @> generation slots (add --write to apply them)
bp generate my-api.bp

The generated code is yours. No required runtime dependency, no license gotchas, no upgrade treadmill. If Blueprint disappeared tomorrow, your application would keep running without changes. That is the kind of tool we think the ecosystem needs more of.

A

Abdul Hamid Achik

Founder and lead engineer at The Lacanians. Abdul builds production software, developer tools, and local-first systems from Guadalajara for teams worldwide.