AI-first Scala 3 backend template
A production backend. Yours from the first commit.
Wired for coding assistants from day one: a live compile-and-test loop and docs the assistant reads as its knowledge base. Scala 3 underneath, so the compiler catches what tests would miss. Auth, background jobs, durable events and feature flags are already in place, and one script makes the code yours.
git clone https://github.com/madrileno-dev/madrilenocd madrilenocp .env.sample .envdocker compose up -dsbt "runMain madrileno.main.MigrateMain"sbt "~reStart"A running API on :9000, with tracing, mail capture and a dev login. One more script renames it to your project.
Included
What's in the box.
Twelve modules of plain Scala. Nothing here is a black box, and nothing is mandatory.
Sign-in and sessions
Let people sign in with Google, a company SSO or email. Sessions refresh themselves, and a dev login keeps you working offline.
Background jobs
Run work on a schedule, or once at a chosen time. Jobs outlive restarts, retry on failure and show up in an admin view.
Reliable events
Tell other systems what happened, but only once the change is really committed. Failed deliveries retry, then wait to be replayed.
Internal events
Let one part of the app react to another without the two depending on each other. The same code works on one instance or a dozen.
Live updates
Push changes to open browser connections as they happen, in a stable public shape clients can build against.
Feature flags
Ship code switched off, turn it on for one customer, then roll it out by percentage. Changing your mind costs no deploy.
Uploads and images
Accept files, keep them on disk or in the cloud, and resize, crop or strip metadata on the way through.
Rate limits
Cap how often an endpoint can be called, per user, per IP or per key, so one bad client cannot ruin the afternoon.
When something breaks
Traces, metrics and logs from the first request. Every error a caller sees carries an id you can search for.
Typed templates, queued and retried like any other job. In development they land in a local inbox instead of a real one.
Third-party APIs
One shape for calling someone else's service, with a fake to drop in so your tests stay fast and offline.
Caching
Hold expensive answers in memory behind an interface small enough to swap out or delete.
Built for assistant-driven work
Your coding assistant already knows the conventions.
A committed .mcp.json gives Claude Code two servers: Metals, for a live compile-and-test loop, and the madrileno MCP server, a read-only view of the upstream template. The docs on this site double as the assistant's knowledge base.
Ask for a new module and the assistant scaffolds it the way the existing ones are built, then compiles and runs the tests before it reports back.
How the setup worksCode you own
Template, not framework.
init-project renames the package, strips the wine-auction demo and removes the template licence. What remains is your repository. Nothing at runtime depends on madrileño.
When the template improves, pull the parts you want. The upstream guide walks through the diff and the pin that keeps your assistant's reference in sync.
Five principles
Most design choices are consequences of one of these.
- Domain-first. Domain types depend on nothing infrastructure-shaped. Codecs live next to their consumers.
- Type safety as a feature. One opaque type per concept, an ADT per state. Mix-ups fail to compile.
- Composition over duplication. Modules declare what they contribute. Adding one does not require remembering the others.
- Functional and explicit. Immutable data, pure functions, outcomes as values. Failure modes readable in a signature.
- Pluggable and pragmatic. Delete what you do not need. Swap what does not fit. Prefer the pattern you can still read in a year.
Companion frontend
Backend drift is a compile error.
A small React 19 and TypeScript app built against the oRPC contract generated from these routes. Rename a field on the backend and the frontend fails to build at the call site.
madrileno-frontend