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
| Component | Convention | Example |
|---|---|---|
| Controllers | snake_case.rs | users.rs, auth.rs |
| Models | snake_case.rs | users.rs, blog_posts.rs |
| Modules | snake_case.rs | user_service.rs, email_service.rs |
| Middleware | snake_case.rs | auth.rs, rate_limit.rs |
| Templates | snake_case.html | index.html, user_profile.html |
| Schemas | snake_case.yaml | users.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→ Controllerssrc/models/*.rs→ Modelssrc/modules/*.rs→ Modulessrc/middleware/*.rs→ Middleware
No manual registration needed!
Next Steps
Now that you understand the project structure:
- Controllers Guide - Learn about routing
- Models Guide - Work with databases
- Views Guide - Use templates
- Modules Guide - Share business logic