Directory Structure

Andurel v2 separates application-owned code, reusable framework modules, and executable process boundaries.

Application layout

 1cmd/app/                  thin web process; calls runtime.App
 2cmd/queue/                thin queue process; calls runtime.Queue
 3cmd/migrate/              one-shot storage.RunMigrations (not part of cmd/app)
 4cmd/ssr/                  Node SSR process owner (Inertia)
 5cmd/seeds/                seed command entry point
 6internal/runtime/         Fx process graphs (App, Queue, database, email, telemetry)
 7config/                   environment loading and typed providers
 8config/hosts.go           extra routing.HostName consts (not scaffolded)
 9controllers/              HTTP handlers and route registration
10router/cookies/           kiks jar, session payload, cookie module
11router/middleware/        auth and related Echo middleware
12router/routes/            typed route declarations (optional routing.Host)
13views/                    Templ components and Inertia root document
14resources/js/             Inertia pages, layouts, Vite entry (when enabled)
15models/                   entities, model APIs, and Fx module
16models/factories/         generated test and seed builders
17models/queries/           application-written narsilc SQL
18models/internal/queries/  generated narsilc implementation
19services/                 application workflows
20queue/jobs/               River argument types
21queue/workers/            River workers and registration
22email/                    Templ email components
23migrations/               embedded Goose SQL migrations
24seeds/                    named seed sets and registry
25telemetry/                application observability wiring
26assets/                   embedded compiled assets
27andurel.toml              project manifest (UI, database, tool pins)
28andurel.lock              tool download digests

Fx graphs live in internal/runtime. cmd/app and cmd/queue only load env and call runtime.App / runtime.Queue. Register new services, controllers, and workers in their package Module. Add process-wide providers (email drivers, extra Fx provides) in internal/runtime. cmd/migrate applies pending SQL and exits; development still uses andurel db migrate up.

Reusable framework packages

Generated applications import github.com/mbvlabs/andurel/pkg/* modules for routing, server, storage, validation, hypermedia, Inertia, email, kiks, and telemetry behavior. Their versions are pinned in the application's go.mod and do not have to match the CLI version.

Unlike v1, these implementations are not copied into an application-owned internal/ tree. Configuration, middleware policy, controllers, model behavior, and presentation remain application-owned.

Project metadata

andurel.toml records scaffold choices (frontend adapter, package manager, SSR runtime, database null strategy) and pinned tool versions. andurel.lock stores per-platform SHA-256 digests for those tools. Commit both with the project. go.mod remains the source of truth for framework package versions; use andurel packages update to bump them deliberately. See Project Lock.