# Project Structure & How to Scale It

This is a [Loco](https://loco.rs) app (Rust, on top of Axum + SeaORM). It uses
the **standard Loco layer layout**. This document explains *why* that layout
scales and *how* you add things as the shop grows, so you never have to guess
where a new piece of code belongs.

---

## 1. The mental model: layers, not features

Loco organizes code by **what kind of thing it is** (a layer), not by which
feature it belongs to. The top-level dirs under `src/` are the layers:

```
src/
├── app.rs            # The wiring hub: registers routes, workers, initializers, tasks
├── lib.rs            # Declares which modules exist (pub mod ...)
├── bin/main.rs       # Binary entrypoint (you rarely touch this)
│
├── controllers/      # HTTP layer: routes + request handlers
├── models/           # Data layer: DB entities + business logic
│   └── _entities/    # AUTO-GENERATED SeaORM structs — never hand-edit
├── views/            # Presentation layer: shapes data into JSON for templates
├── mailers/          # Email sending + email templates (.t files)
├── workers/          # Background jobs (async, off the request path)
├── tasks/            # CLI tasks (`cargo loco task ...`)
├── initializers/     # Runs once at boot (seeders, view engine setup, ...)
├── fixtures/         # Seed data (YAML) for `cargo loco db seed`
├── data/             # Misc static/loaded data
└── shared/           # Cross-cutting helpers used by many layers
```

Supporting dirs outside `src/`:

```
migration/            # SeaORM migrations (one file per schema change)
config/               # development.yaml / test.yaml / production.yaml
assets/               # Tera templates (views/), i18n (.ftl), static files, CSS
tests/                # requests/ models/ workers/ tasks/ + snapshot .snap files
```

### Why layers scale

The instinct is often "put everything for the shop in one folder." That feels
nice early, but it fights the framework: Loco's codegen, conventions, and docs
all assume layers. By staying with layers you get:

1. **`loco generate` just works.** Scaffolding lands in the right place; you
   never hand-move files. (This is exactly why the project moved *back* to this
   layout in the `loco straucture` commit.)
2. **Each layer has one reason to change.** A routing change touches only
   `controllers/`. A schema change touches `migration/` + `models/_entities/`. A
   "make the price display differently" change touches only `views/`. Bugs stay
   contained.
3. **New contributors (and AI tools) navigate by convention**, not by reading
   the whole tree.

The trade-off — "I have to open 3 dirs to see the whole shop feature" — is
solved below with naming, not folders.

---

## 2. Feature grouping without folders: the naming convention

You still get the "everything for X in one glance" benefit, via **filename
prefixes** inside the flat `controllers/` dir:

```
controllers/
├── home.rs            ┐
├── shop.rs            │  public storefront
├── cart.rs            │
├── checkout.rs        ┘
│
├── admin_dashboard.rs ┐
├── admin_products.rs  │
├── admin_categories.rs│  admin area — `admin_` prefix groups them
├── admin_orders.rs    │
├── admin_shipping.rs  │
├── admin_login.rs     │
├── admin_form.rs      ┘
│
├── auth.rs            ┐
├── i18n.rs            │  cross-cutting
└── media.rs           ┘
```

In your editor's file list, `admin_*` sorts together — you see the whole admin
surface at once, but `loco generate` and Loco conventions still see flat
controllers. Best of both.

**Rule of thumb:** prefix = the "feature area." Add `admin_returns.rs`, not a
`returns/` folder.

---

## 3. How a request flows through the layers

Trace the shop index (`GET /shop`) to see how layers cooperate — this is the
pattern every feature follows:

```
Browser → app.rs routes()           # 1. router dispatches /shop to shop::index
        → controllers/shop.rs        # 2. handler: query DB, gather data
            → models/products.rs     # 3. data layer: products::Entity::find()...
            → views/shop.rs          # 4. shape Model → JSON (product_card)
            → shared/guard.rs        # 5. cross-cutting: is admin logged in?
        → assets/views/shop/index.html  # 6. Tera renders the JSON
        → HTML response
```

Concretely, from `controllers/shop.rs`:

```rust
use crate::{
    models::{categories, product_images, products},  // data layer
    views::shop as view,                              // presentation layer
    shared::guard,                                    // cross-cutting
    controllers::i18n::current_lang,
};

async fn index(...) -> Result<Response> {
    let list = products::Entity::find()                       // query (models)
        .filter(products::Column::Published.eq(true))
        .all(&ctx.db).await?;

    format::view(&v, "shop/index.html", json!({               // render
        "products": product_rows(&ctx, list).await?,          // shaped by views::shop
        "logged_in_admin": guard::logged_in(&ctx, &jar).await,
        "lang": current_lang(&jar),
    }))
}
```

The controller is a thin coordinator. It does **not** contain business logic —
that lives in `models/`. It does **not** build HTML strings — that's `views/` +
templates. Keeping controllers thin is the single biggest factor in whether this
stays scalable.

---

## 4. The models layer: the one piece of Loco that surprises people

There are **two files per database table**, and they have different jobs:

```
models/
├── _entities/products.rs   ← AUTO-GENERATED. The raw table struct
│                             (columns, relations). Regenerated as a unit
│                             whenever the schema changes. NEVER hand-edit.
│
└── products.rs             ← HAND-WRITTEN. Re-exports the entity, then adds
                              your behavior on top of it.
```

Your `models/products.rs` shows the pattern exactly:

```rust
pub use crate::models::_entities::products::{ActiveModel, Column, Entity, Model};

#[async_trait::async_trait]
impl ActiveModelBehavior for ActiveModel {
    // lifecycle hooks, e.g. touch updated_at before save
}

impl Model    {}  // read-oriented logic (your finders that return data)
impl ActiveModel {}  // write-oriented logic (validation, mutation)
impl Entity   {}  // custom queries / selectors
```

**Why two files:** the schema is machine-owned (so codegen can overwrite
`_entities/` safely), but your logic is human-owned (so it survives
regeneration). The `pub use` bridge means the rest of the app imports
`crate::models::products` and never has to know `_entities` exists.

**How to apply when scaling:** put domain logic on the model, not in the
controller. "Is this product low on stock?" → a method on `products::Model`.
"Recalculate order total" → a method on `orders`. As features pile up, this is
what keeps controllers from turning back into the 900-line god-files this
project deliberately escaped.

---

## 5. Where new code goes — a decision table

When you build the next thing, find the row and follow it:

| You want to add...                          | Touch these                                                            |
|---------------------------------------------|------------------------------------------------------------------------|
| A new page / endpoint                       | `controllers/<area>.rs` (+ register `routes()` in `app.rs`)            |
| A new admin screen                          | `controllers/admin_<thing>.rs` (prefix!) + `assets/views/admin/...`   |
| A new database table                        | `cargo loco generate model <name> ...` → migration + `_entities` + wrapper |
| A schema change to an existing table        | `cargo loco generate migration <name> ...`, then rebuild & migrate    |
| Business logic / a custom query             | a method in `models/<entity>.rs` (not the controller)                 |
| Reshaping data for a template               | `views/<area>.rs`                                                      |
| An HTML template / partial                  | `assets/views/<area>/...html`                                         |
| A reusable helper (money, slugs, auth)      | `shared/<helper>.rs`                                                   |
| Something slow (resize image, send batch)   | `workers/<name>.rs` (+ register in `app.rs` `connect_workers`)        |
| A transactional email                       | `mailers/<name>.rs` + `mailers/<name>/<event>/{subject,html,text}.t`  |
| One-time-at-boot setup / seeding            | `initializers/<name>.rs` (+ register in `app.rs` `initializers`)      |
| A CLI maintenance command                   | `tasks/<name>.rs` (+ register in `app.rs` `register_tasks`)           |
| A cross-cutting config value                | `shared/settings.rs` + `config/*.yaml`                                |

---

## 6. `app.rs` is the wiring hub — the one file you revisit constantly

Every new route, worker, initializer, and task is *registered* here. It's the
table of contents for the whole backend:

```rust
fn routes(_ctx: &AppContext) -> AppRoutes {
    AppRoutes::with_default_routes()
        .add_route(shop::routes())          // ← every new controller's routes()
        .add_route(admin_products::routes())//   gets one line here
        // ...
}

async fn initializers(...) -> Result<Vec<Box<dyn Initializer>>> {
    Ok(vec![ /* AdminSeeder, ShippingSeeder, ViewEngine ... */ ])
}

async fn connect_workers(...) { queue.register(DownloadWorker::build(ctx)).await?; }
fn register_tasks(tasks: &mut Tasks) { /* tasks-inject */ }
```

If you add a controller and the route 404s, the usual cause is: **you forgot the
`add_route` line in `app.rs`.** Same shape for workers/initializers/tasks.

---

## 7. Scaling checklist (the habits that keep this healthy)

As the shop grows, these are the things that decide whether the codebase stays
pleasant or rots:

1. **Keep controllers thin.** They query, gather, and render. Logic goes to
   `models/`, shaping goes to `views/`. If a handler exceeds ~80 lines, extract.
2. **One controller file per feature area, prefix-grouped.** Don't let
   `admin_products.rs` start handling orders. Split by area, not convenience.
3. **Never edit `models/_entities/`.** Change the schema via a migration and
   regenerate. Your logic in the sibling wrapper survives.
4. **Push slow/optional work to `workers/`.** Image processing, bulk emails,
   external API calls — off the request path so pages stay fast.
5. **Reuse via `shared/` and model methods**, not copy-paste. You already do
   this well: `money` (integer cents everywhere), `guard` (one source of truth
   for admin auth), `slug`.
6. **Every schema change is a migration file**, never a manual DB edit — so
   `test`, `development`, and `production` stay reproducible from
   `config/*.yaml` + `migration/`.
7. **Mirror new code with a test** in `tests/{models,requests,...}/`. The
   snapshot tests (`.snap`) catch accidental output changes for free.

### When a feature genuinely outgrows a single file

If one area gets huge (say `shop` becomes 5+ concerns), you have two
Loco-friendly options — both keep the layout intact:

- **Split by sub-area with more prefixes:** `shop_catalog.rs`,
  `shop_search.rs`, `shop_reviews.rs`.
- **Promote a layer file to a folder module:** turn `controllers/shop.rs` into
  `controllers/shop/mod.rs` + `controllers/shop/{listing,detail,search}.rs`.
  Loco doesn't care; `mod.rs` just re-exports a `routes()`.

What you should *not* do is recreate top-level vertical slices (a `src/shop/`
holding its own controllers+models+views). That's the layout this project
already tried and reverted — it breaks `loco generate` and fights the framework.

---

## TL;DR

- **Layers, not features.** `controllers/ models/ views/ ...` is deliberate and
  is what makes `loco generate` and Loco conventions work for you.
- **Group features by filename prefix** (`admin_*`) inside the flat layers.
- **Controllers are thin coordinators**; logic lives on models, shaping in views.
- **`_entities/` is machine-owned; the sibling model file is yours.**
- **`app.rs` registers everything** — add a line there for each new route/worker/task.
- **Scale by adding files within layers**, splitting busy files into more
  prefixes or `mod.rs` folders — never by going back to vertical slices.
