Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Project Structure

Understanding the RustF project structure is essential for building maintainable applications. This guide explains the standard layout and conventions.

Standard Project Layout

your_project/
├── src/
│   ├── main.rs              # Application entry point with auto-discovery
│   ├── controllers/         # HTTP request handlers
│   │   ├── home.rs          # Home page controller
│   │   ├── auth.rs          # Authentication controller  
│   │   ├── users.rs         # User management controller
│   │   └── api/             # API controllers (namespaced)
│   │       ├── users.rs     # User API endpoints
│   │       └── posts.rs     # Post API endpoints
│   ├── models/              # Database models (schema-generated)
│   │   ├── users.rs         # User model wrapper
│   │   ├── posts.rs         # Post model wrapper
│   │   └── base/            # Auto-generated base models (DO NOT EDIT)
│   │       ├── users.inc.rs
│   │       └── posts.inc.rs
│   ├── modules/             # Business logic modules
│   │   ├── user_service.rs  # User business logic
│   │   └── email_service.rs # Email functionality
│   ├── definitions/         # Template helpers & validators
│   ├── events/              # Event handlers (optional)
│   ├── middleware/          # Custom middleware
│   │   └── auth.rs          # Authentication middleware
│   ├── workers/             # Background workers (optional)
│   ├── _controllers.rs      # Auto-generated (IDE support only)
│   ├── _models.rs           # Auto-generated (IDE support only)
│   └── _modules.rs          # Auto-generated (IDE support only)
├── views/                   # Template files
│   ├── layouts/
│   │   └── default.html     # Default layout
│   ├── home/
│   │   ├── index.html       # Home page template
│   │   └── about.html       # About page template
│   └── auth/
│       └── login.html       # Login form template
├── schemas/                 # YAML schema definitions
│   ├── users.yaml           # User table schema
│   ├── posts.yaml           # Posts table schema
│   └── _meta.yaml           # Database metadata
├── public/                  # Static files
│   ├── css/
│   ├── js/
│   └── images/
├── uploads/                 # File uploads directory
├── config.toml              # Base configuration
├── config.dev.toml          # Development overrides (created by scaffold)
└── Cargo.toml               # Rust project configuration

Directory Descriptions

src/ - Source Code

All Rust source code lives in the src/ directory.

src/main.rs

The application entry point. Typically contains:

use rustf::prelude::*;

#[tokio::main]
async fn main() -> rustf::Result<()> {
    env_logger::init();
    
    let app = RustF::new()
        .controllers(auto_controllers!())
        .middleware_from(auto_middleware!());
    
    app.start().await
}

src/controllers/ - Request Handlers

Controllers handle HTTP requests and define routes. Each controller file must have an install() function.

Example: src/controllers/home.rs

#![allow(unused)]
fn main() {
use rustf::prelude::*;

pub fn install() -> Vec<Route> {
    routes![
        GET "/" => index,
        GET "/about" => about,
    ]
}

async fn index(ctx: &mut Context) -> Result<()> {
    ctx.view("home/index", json!({}))
}
}

Nested Controllers: src/controllers/api/users.rs

#![allow(unused)]
fn main() {
use rustf::prelude::*;

pub fn install() -> Vec<Route> {
    routes![
        GET "/api/users" => list_users,
        GET "/api/users/{id}" => get_user,
    ]
}
}

src/models/ - Database Models

Models represent database tables and provide type-safe database access.

Structure:

  • src/models/users.rs - User model wrapper (your code)
  • src/models/base/users.inc.rs - Auto-generated base model (don’t edit)

Example: src/models/users.rs

#![allow(unused)]
fn main() {
use rustf::prelude::*;

// The generated `Users` struct + CRUD are included directly from the base
// file (do not edit base/users.inc.rs).
include!("base/users.inc.rs");

// Add your custom business logic to the generated `Users` type:
impl Users {
    // Add custom methods here
}
}

src/modules/ - Business Logic

Modules contain business logic separate from HTTP concerns. They’re shared across controllers and can be accessed via MODULE.

Example: src/modules/user_service.rs

#![allow(unused)]
fn main() {
use rustf::prelude::*;

pub struct UserService;

impl UserService {
    pub fn create_user(&self, name: &str, email: &str) -> Result<User> {
        // Business logic here
    }
}

// Register as shared module
impl_shared_service!(UserService);
}

src/middleware/ - Request Processing

Middleware processes requests before they reach controllers.

Example: src/middleware/auth.rs

#![allow(unused)]
fn main() {
use async_trait::async_trait;
use rustf::middleware::{InboundAction, InboundMiddleware, MiddlewareRegistry};
use rustf::prelude::*;

pub struct AuthMiddleware;

#[async_trait]
impl InboundMiddleware for AuthMiddleware {
    async fn process_request(&self, ctx: &mut Context) -> rustf::Result<InboundAction> {
        // Authentication logic. Return InboundAction::Stop to short-circuit
        // the chain (after setting a response on ctx), otherwise continue.
        Ok(InboundAction::Continue)
    }
}

pub fn install(registry: &mut MiddlewareRegistry) {
    registry.register_inbound("auth", AuthMiddleware);
}
}

src/_*.rs - Auto-Generated Files

These files are generated by auto-discovery macros for IDE support:

  • _controllers.rs - Controller module declarations
  • _models.rs - Model module declarations
  • _modules.rs - Module declarations

Important: These files are NOT compiled. They’re only for IDE autocomplete.

views/ - Templates

Template files organized by feature.

Structure:

views/
├── layouts/
│   └── default.html         # Default layout
├── home/
│   ├── index.html           # Home page
│   └── about.html           # About page
└── auth/
    └── login.html           # Login form

Layout Example: views/layouts/default.html

<!DOCTYPE html>
<html>
<head>
    <title>@{title}</title>
</head>
<body>
    @{body}
</body>
</html>

View Example: views/home/index.html

<h1>Welcome</h1>
<p>Hello, @{name}!</p>

schemas/ - Database Schemas

YAML schema definitions for database tables. Used by the CLI to generate models.

Example: schemas/users.yaml

table: users
fields:
  id:
    type: integer
    primary: true
    auto_increment: true
  name:
    type: string
    length: 255
    required: true
  email:
    type: string
    length: 255
    required: true
    unique: true

public/ - Static Assets

Static files served directly by the web server.

public/
├── css/
│   └── style.css
├── js/
│   └── app.js
└── images/
    └── logo.png

Access via: http://localhost:8000/css/style.css

uploads/ - User Uploads

Directory for user-uploaded files. Location is configurable in config.toml.

Configuration Files

config.toml - Base Configuration

[server]
host = "127.0.0.1"
port = 8000

[views]
directory = "views"
cache_enabled = false

config.dev.toml - Development Overrides

The scaffold creates config.dev.toml, merged over config.toml in development. Create a config.prod.toml yourself for production — it works the same way, merged when running in the production environment.

# config.prod.toml (you create this for production)
[server]
host = "0.0.0.0"
port = 8080

[views]
cache_enabled = true

File Naming Conventions

ComponentConventionExample
Controllerssnake_case.rsusers.rs, auth.rs
Modelssnake_case.rsusers.rs, blog_posts.rs
Modulessnake_case.rsuser_service.rs, email_service.rs
Middlewaresnake_case.rsauth.rs, rate_limit.rs
Templatessnake_case.htmlindex.html, user_profile.html
Schemassnake_case.yamlusers.yaml, blog_posts.yaml

Best Practices

1. Organize by Feature

Group related files together:

src/controllers/
├── users.rs          # User-related routes
├── posts.rs          # Post-related routes
└── comments.rs       # Comment-related routes

2. Use Namespaces for APIs

Separate API controllers:

src/controllers/
├── api/
│   ├── v1/
│   │   ├── users.rs
│   │   └── posts.rs
│   └── v2/
│       └── users.rs

3. Keep Models Simple

Models should be thin wrappers around base models:

#![allow(unused)]
fn main() {
// Good: Thin wrapper
pub struct Users {
    base: UsersBase,
}

// Avoid: Complex logic in models
// Move business logic to modules
}

4. Separate Concerns

  • Controllers - HTTP request/response handling
  • Models - Database access
  • Modules - Business logic
  • Middleware - Cross-cutting concerns

Auto-Discovery

RustF automatically discovers components based on file location:

  • src/controllers/*.rs → Controllers
  • src/models/*.rs → Models
  • src/modules/*.rs → Modules
  • src/middleware/*.rs → Middleware

No manual registration needed!

Next Steps

Now that you understand the project structure:

  1. Controllers Guide - Learn about routing
  2. Models Guide - Work with databases
  3. Views Guide - Use templates
  4. Modules Guide - Share business logic