Htmx/README.md

Stick: Use-Case Oriented Axum + Askama + MongoDB Template

A production-ready Rust web application template organized by vertical features (use-cases) rather than horizontal technical layers.

---

🛠️ Technology Stack

• Web Framework: Axum (v0.8) - Native RPITIT (Return-Position Impl Trait in Traits) extractors.
• Template Engine: Askama (v0.16) - Type-safe, compile-time HTML templates.
• Styling: Tailwind CSS - Modern utility-first styling.
• Database: MongoDB Rust Driver (v3.7) - Configured with BSON v3.
• Authentication/Authorization: jsonwebtoken (v10) with the rust_crypto backend, stored in secure HttpOnly session cookies.
• Password Hashing: bcrypt for secure password storage.

---

📁 Use-Case Centered Project Layout

Unlike traditional MVC setups, files are grouped by their business domain. A single use-case directory contains its models, database repositories, route handlers, local extractors, and templates.

stick/
├── Cargo.toml
├── .env.example
├── templates/             # Raw HTML template layout files
│   ├── base.html          # Global layout wrapper
│   ├── auth/              # Auth views
│   │   ├── login.html
│   │   └── register.html
│   ├── tasks/             # Task manager views
│   │   └── dashboard.html
│   └── main_view/         # Main views
│       └── index.html
└── src/
    ├── main.rs            # Server composition, shared state, and route merging
    ├── common/            # Shared features (errors, database, settings)
    │   ├── config.rs
    │   ├── database.rs
    │   └── errors.rs
    ├── auth/              # Authentication & User Management Use-Case
    │   ├── extractors.rs  # Session context extractors
    │   ├── handlers.rs    # User interaction handlers
    │   ├── models.rs      # User database schemas
    │   └── repository.rs  # User database actions
    ├── tasks/             # Tasks & Dashboard Management Use-Case
    │   ├── handlers.rs    # Task CRUD handlers
    │   ├── models.rs      # Task database schemas
    │   └── repository.rs  # Task database actions
    └── main_view/         # Static Navigation & Branding Use-Case
        └── mod.rs         # Serves index & handles public routes

---

🚀 Setup & Execution

1. Prerequisites

• Rust (v1.75+ required for native async traits)
• MongoDB running locally (port 27017)

2. Configuration

Copy the configuration example file and customize your settings:

cp .env.example .env

3. Run the Server

Start the development server:

cargo run

The server will start listening at http://127.0.0.1:3000.

---

💡 Designing Custom Use-Cases

When adding a new feature (e.g., projects):

1. Create src/projects/ containing:
   • models.rs (BSON schemas)
   • repository.rs (Database access)
   • handlers.rs (Endpoints)
   • mod.rs (Usecase module entrypoint exposing a pub fn router<S>() -> Router<S>)
2. Add its view templates under templates/projects/.
3. Expose the repository and compile constraints in src/main.rs.
4. Merge the usecase router inside the main router builder:

   let app = Router::new()
       .merge(main_view::router())
       .merge(auth::router())
       .merge(projects::router()) // Custom vertical router
       .with_state(state);