umbral: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working in this repository.

Project status

Greenfield. No Cargo workspace or source yet. Before scaffolding anything, read arch.md; that's the authoritative design spec.

umbral is a declarative web framework in Rust (umbral means 'of the shadow', from Latin umbra). The goal is to recreate that declare-your-data-and-get-everything feeling: declare data and you get migrations, CRUD, an admin, and an optional REST API almost for free, with Rust's compile-time guarantees. The name is a placeholder; the whole tree can be renamed later with sed 's/umbral/yourname/g'.

The one idea that matters most

Thin core, plugin-heavy. The framework dogfoods its own plugin system. Auth, sessions, admin, tasks, and REST are all plugins. Structurally they're identical to a third-party one. A REST-free app has to compile and run with zero serializer code. If a built-in can't be expressed as a plugin, the plugin contract is wrong.

Crate layout = the architecture

The Cargo workspace boundaries encode the core-vs-plugin split:

crates/
  umbral-core     # ORM, migrations, routing, DB backends, the Plugin TRAIT. No plugin deps.
  umbral-macros   # #[derive(Model)], #[task], etc.
  umbral          # FACADE: re-exports core + macros as one stable surface (umbral::prelude::*)
  umbral-cli      # the umbral command-line tool binary
plugins/         # built-in plugins, each its own crate (from M9 onward)
  umbral-auth      # built-in: users, permissions, password hashing (argon2)
  umbral-sessions  # built-in: session store + middleware (tower-sessions)
  umbral-admin     # built-in: auto CRUD UI
  umbral-tasks     # built-in: DB-backed background task queue
  umbral-rest      # OPTIONAL: serializers, viewsets, routers (the REST layer)
  umbral-openapi   # OPTIONAL: Swagger UI / schema gen; depends on umbral-rest

Dependency inversion is the whole game

• Dependencies point inward toward core. Control flows outward through the trait.
• Every plugin depends on the umbral facade, never the reverse. umbral-core defines the Plugin trait but never names a concrete plugin; it touches plugins only as Box<dyn Plugin>. That trait object is the dynamic seam that holds the registry of installed plugins.
• The user's binary crate depends on core plus every chosen plugin and wires them via an explicit builder: App::builder().plugin(...).build().
• umbral-core depends on neither umbral-rest nor umbral-openapi. That's the structural proof that "serializers are a plugin." Cargo's ban on circular deps enforces it for us.
• Plugins import only the facade (use umbral::prelude::*), never umbral-core internals. The internal crate split can then be refactored without breaking any plugin.