Skip to content
STACK IT FAST

Loco + SeaORM + PostgreSQL (Rails-Style Rust SaaS)

Curated rule SaaS / Web App · Internal Admin Tool Updated Oct 2026 Which file does my tool read?
rust-loco-saas.md

Rails-style Rust SaaS rules for Loco: generators, SeaORM models and migrations, Tera views or htmx scaffolds, JWT auth, background workers and mailers.

Formats
4 files
AGENTS.md
45 lines
CLAUDE.md
17 lines
Languages
Rust
Updated
Oct 2026
Used by
4 projects
Install

Writes .claude/skills/rust-loco-saas/SKILL.md

$ curl -s --create-dirs -o .claude/skills/rust-loco-saas/SKILL.md https://stackitfast.com/rules/rust-loco-saas/SKILL.md

Rule files

AGENTS.md· 45 lines · 3.5 KB
1# Project Architecture & Guidelines (Loco + SeaORM + PostgreSQL)
2
3## 1. System Architecture
4- **Framework**: Loco 1.x ("Rails for Rust"), built on Axum and Tokio. Convention over configuration: follow the generated layout instead of inventing a new one.
5- **ORM**: SeaORM, with entities generated from the database (`cargo loco db entities`) and behaviour added in `src/models/<name>.rs`.
6- **Database**: PostgreSQL in development and production (SQLite only for throwaway prototypes).
7- **Rendering**: server-rendered Tera views (`ViewEngine<TeraView>`) or the htmx scaffold; a separate SPA only if the product needs one.
8- **Jobs and mail**: Loco background workers and mailers; queue backed by Redis or Postgres in production.
9- **Config**: `config/{development,test,production}.yaml` with `{{ get_env(name="...") }}` for secrets.
10
11## 2. Generators First
12- New resource: `cargo loco generate scaffold <name> field:type ... --htmx` (or `--html`, `--api`).
13- Schema change: `cargo loco generate migration <name> field:type`, then `cargo loco db migrate`, then `cargo loco db entities`.
14- Background job: `cargo loco generate worker <name>`; email: `cargo loco generate mailer <name>`; one-off task: `cargo loco generate task <name>`.
15- Never hand-edit files in `src/models/_entities/`; they are regenerated. Put model logic in `src/models/<name>.rs` (`impl ActiveModelBehavior`, finders, validations).
16
17## 3. Controllers and Views
18- Controllers in `src/controllers/<name>.rs` expose `pub fn routes() -> Routes` and are registered in `src/app.rs` (`AppRoutes::with_default_routes().add_route(...)`).
19- Handlers return `Result<Response>` or `Result<impl IntoResponse>` using Loco's `Error`; use `format::json`, `format::render().view(...)` and `format::redirect`.
20- Keep handlers thin: load params, call a model method, render. Business rules live on the model.
21- Views: templates in `assets/views/<name>/`, view helpers in `src/views/<name>.rs`.
22- Protected routes take `auth: auth::JWT` (or the cookie-based auth in your starter) as an extractor; load the user with `users::Model::find_by_pid`.
23
24## 4. Workers, Mailers and Tasks
25- Anything slower than ~100 ms or calling a third party goes to a worker (`BackgroundWorker::perform_later`).
26- Workers are idempotent and take serialisable args (IDs, not models).
27- Mailers render templates from `src/mailers/<name>/`; send from workers, never inline in a request.
28
29## 5. Agent Loop (run after every change)
301. `cargo check` until clean.
312. `cargo clippy --all-targets -- -D warnings`.
323. `cargo test` (request and model tests, including `insta` snapshots; review snapshot diffs instead of blindly accepting them).
334. `cargo loco doctor` after config or dependency changes; `cargo loco routes` to confirm new endpoints are mounted.
34- Prefer the generator over writing boilerplate by hand; the generated tests are the starting point.
35- No `unwrap()` in controllers, workers or models; propagate with `?`.
36
37## 6. Testing
38- Request tests use Loco's `request::<App, _, _>` helper with `#[serial]`; model tests run against a migrated test database.
39- Seed fixtures in `src/fixtures/*.yaml`; load them with `cargo loco db seed` (`--reset` for a clean dev/test database).
40- Snapshot tests (`insta`) for JSON and HTML responses; redact timestamps and IDs.
41
42## 7. Deploy
43- `cargo loco generate deployment` for a Dockerfile (or Shuttle / Nginx configs).
44- Run migrations on start in `production.yaml` (`auto_migrate: true`) or as a release step; never `dangerously_recreate`.
45- Ship one binary plus `assets/` and `config/`; set `LOCO_ENV=production`.

Works with Claude Code · Cursor · Windsurf · AGY

Architecture notes

Architecture Overview

Rails conventions with a Rust compiler. Loco gives you cargo loco generate scaffold, SeaORM models and migrations, Tera or htmx views, JWT auth, background workers, mailers and tasks, all on top of Axum and Tokio. It is the shortest path from “I know Rails” to a working Rust SaaS.

Why it suits AI coding agents

  • Generators remove the guesswork. The agent creates a resource the same way every time, and the generated request tests become its first safety net.
  • Clear places for code. Entities are generated, behaviour lives on the model, handlers stay thin, slow work goes to workers; every rule in the AGENTS.md maps to a directory.
  • The compiler still checks everything. SeaORM entities are typed, so a renamed column breaks the build after cargo loco db entities.

Trade-offs

Loco’s community and plugin ecosystem are far smaller than Rails’, and you inherit its choices (SeaORM, Tera, its auth). For a server-rendered app where you pick each crate yourself, see Axum + htmx + Askama. Why Rails developers are looking at Rust right now: Building web apps in Rust in 2026.

Frequently asked questions

Is Loco the Rails of Rust?

It is the closest thing: Loco is explicitly inspired by Rails and ships generators, an ORM (SeaORM), migrations, controllers, views, mailers, background workers, tasks and deployment generators on top of Axum. It is a much younger project with a smaller community, so you will read framework source more often than you would with Rails.

Can I move a Rails app to Loco?

The concepts map closely (models, controllers, views, jobs, mailers, migrations), which makes Loco the gentlest landing for Rails developers. A full rewrite still carries the usual risk of losing undocumented behaviour, so start with a new service or a slow endpoint rather than the whole app.

Loco or plain Axum?

Use Loco when you want conventions and generators for a CRUD-heavy SaaS and are happy to follow its layout. Use plain Axum when you are building an API, a service with unusual structure, or want to choose every crate yourself; Loco is Axum underneath, so handlers and Tower middleware carry over.

Why does generator-first matter for AI agents?

Generators produce the same file layout, tests and wiring every time, so an agent spends its effort on business logic instead of re-deriving boilerplate, and reviewers see familiar diffs. The agent loop then compiles, lints and tests the generated code like any other change.

Used in production

Explore all stacks