01. Thesis

The problem

TypeScript gives you types and takes away opinions.

Every Next.js codebase reinvents the same decisions: where models live, whether there is a service layer, how data gets from the database to a component, where authorization is checked, what belongs in lib/. None of those decisions are hard individually. The cost is that every project answers them differently, every new hire relearns them, and nothing enforces the answer after the person who made it moves on.

Six months in, lib/ is four thousand lines of unrelated helpers, three files construct their own Supabase client, authorization happens in two different layers depending on who wrote the route, and finding the code that writes to a table means grepping for the table name.

Opinionated server frameworks solved this socially and structurally. One place for each kind of thing. A generator that puts it there. A community that agrees on the shape, because the framework shipped with an opinion instead of a configuration option.

Who this is for

Someone who wants a prescribed application shape in TypeScript, and who is building on Next because that is where the team, the host, or the client already is.

Next is good at rendering. It has no answer to "where does this go." If you have used a framework that did, that silence reads as chaos. If you have not, you still pay for it: every teammate invents a slightly different lib/.

If you can stay on a stack that already answers this, stay. Avelon is for when the application is going to live in TypeScript and you still want one place for each kind of thing.

What success looks like

You clone an Avelon project and know where everything is without opening a single doc. You run one command and get a model, a migration, a factory, a controller, a policy, and a ward in the places the directory map promised. You write a controller that reads like a controller. Six months later the codebase still looks like the day it was generated, because the linter would not let it drift.

The negative test matters more: if someone can create a mess in Avelon and CI stays green, that is a bug.

The three mechanisms

Opinions in a README are advice. Opinions in tooling are decisions. Avelon carries the thesis in three shipped features, not in documentation.

1. Generators. There is exactly one way to create each kind of thing, and it is a command. Nobody hand-creates a controller and puts it somewhere reasonable-looking, because reeve make:controller is faster than deciding.

2. Bailiff. An ESLint plugin plus a CLI. Views cannot import models. Database calls cannot appear in components. There is no lib/. Generated files cannot be hand-edited. Every model has a ward. Every write validates through a Request. Violations are editor squiggles, not a code review comment someone forgets to leave.

3. Documentation conventions. Packages in a living ecosystem read alike when the docs set a register and tooling enforces it. reeve make:package scaffolds the structure and reeve docs:check fails a package whose README omits a public method or contains a code block that does not parse.

What Avelon is not

Not a boilerplate. A template is a snapshot you fork and diverge from. This is a dependency you

upgrade.

Not a Supabase wrapper. Supabase is the first driver. See 04-drivers.md.
Not Next-only. Next is the first adapter. See 03-architecture.md.
Not a theme pack of cute names. New ideas get their own words so they stay guessable. Controllers

are still called controllers. See 10-conventions.md.