Backend · Any coding agent
Bun & Elysia / Hono ARCHITECTURE.md
An ARCHITECTURE.md for Bun & Elysia / Hono: module responsibilities, data flow and the boundaries code changes must keep.
- Path
- ARCHITECTURE.md
- Loads
- Read when referenced
- Format
- Markdown (.md)
- Used by
- Any coding agent
What this file tells the agent
ARCHITECTURE.md describes module responsibilities, state boundaries and data flow, so a coding agent knows where code belongs before it changes anything. Point to it from CLAUDE.md or AGENTS.md so agents read it.
- Use Elysia's native t schema builder (powered by TypeBox) for request body, query, and parameter validation.
- Leverage native Bun.serve(), Bun.file(), and Bun.password instead of slow Node.js polyfills or external dependencies.
- Structure plugins using .use() and define explicit Eden Treaty contracts for frontend consumption.
- Handle application errors using Elysia .onError(({ code, error, set }) => ...) with typed error codes.
- Ensure zero unhandled promise rejections and use strict type inference for all endpoint responses.
Code to avoid, and what to write instead
The rule steers the agent away from the left and toward the right.
// Discouraged: Node.js bcrypt imports, unvalidated body, and Express paradigms
import bcrypt from "bcrypt";
app.post("/users", async (req: any, res: any) => {
const hash = await bcrypt.hash(req.body.password, 10);
res.json({ success: true });
});import { Elysia, t } from "elysia";
export const app = new Elysia()
.onError(({ code, set }) => {
if (code === "NOT_FOUND") {
set.status = 404;
return { ok: false, error: "Resource not found" };
}
})
.post(
"/api/users",
async ({ body, set }) => {
const hash = await Bun.password.hash(body.password);
set.status = 201;
return { ok: true, email: body.email };
},
{
body: t.Object({
email: t.String({ format: "email" }),
password: t.String({ minLength: 8 }),
}),
}
);Install it in one command
- 01
Go to your project root
The file goes at ARCHITECTURE.md, relative to the root.
- 02
Download the file
Run the command on the right. It downloads this preset and writes the file.
- 03
Make sure it gets used
Agents read it when your CLAUDE.md or AGENTS.md points to it. Add a line such as "Read ARCHITECTURE.md before structural changes".
$ curl -fsSL "https://www.devscratchpad.tech/api/raw/architecture-md/bun-elysia" -o "ARCHITECTURE.md"
writes ARCHITECTURE.md
ARCHITECTURE.md
To write the file from your own code instead, use Read your code or Convert Legacy Rules in the editor above.
More for Bun & Elysia / Hono
Questions
- What belongs in ARCHITECTURE.md?
- How the main modules relate, how state and data flow, and the boundaries every change must keep.
- How does ARCHITECTURE.md help AI agents?
- It tells them where code belongs and which boundaries to keep, so they are less likely to add circular dependencies or skip layers. Point to it from CLAUDE.md or AGENTS.md so they read it.