When organizing a Rust application, it’s important to follow a folder structure that is both maintainable and scalable. A well-organized folder structure makes it easier for developers to understand the code, contribute to the project, and scale the application as it grows. Below is a recommended structure for a typical Rust application, with explanations for each part.

my_rust_app/
├── Cargo.toml                # Project configuration (dependencies, metadata)
├── Cargo.lock                # Lock file (generated after running `cargo build`)
├── src/                      # Source files
│   ├── main.rs               # Main entry point (binary application)
│   ├── lib.rs                # Common library code (if applicable)
│   ├── bin/                  # Additional binaries (optional)
│   ├── models/               # Data models (e.g., structs, enums, etc.)
│   ├── services/             # Business logic / services
│   ├── handlers/             # Request handlers (e.g., for web servers)
│   ├── utils/                # Utility modules (e.g., helpers, utils)
│   ├── db/                   # Database-related code (e.g., migrations, queries)
│   ├── config/               # Configuration and environment setup
│   └── tests/                # Unit and integration tests
├── examples/                 # Example projects or usage demonstrations
├── target/                   # Build output directory (auto-generated by Cargo)
├── tests/                    # Integration tests (optional, alternative to `src/tests`)
├── scripts/                  # Utility scripts (e.g., setup, data generation)
└── README.md                 # Project documentation

Explanation of Folders and Files#

1. Cargo.toml & Cargo.lock#

  • Cargo.toml: This is the main configuration file for the Rust project. It contains metadata, dependencies, and build configuration for the project.
  • Cargo.lock: This file is automatically generated when you run cargo build or cargo install to lock the dependencies to specific versions. You should commit this file to ensure consistent builds.

2. src/#

This folder contains the core source code of the project.

  • main.rs: The main entry point of the application. If you’re building a binary application, this is the file where the program starts executing.
  • lib.rs: If your project is a library or contains shared functionality, the lib.rs file is the main library entry point. It can also be used in combination with main.rs for shared logic between binaries.
  • bin/: This folder is optional, but if you have multiple binary applications in the same repository (e.g., command-line tools), you can put them here. Each file in the bin/ directory is treated as a separate binary by Cargo.

3. models/#

Contains data models used in your application (e.g., structs, enums). These models represent the entities in your application, such as user accounts, products, etc.

Example:

// src/models/user.rs
pub struct User {
    pub id: i32,
    pub name: String,
}

4. services/#

This folder contains the core business logic or services that operate on the models. These could include things like user authentication, data processing, or application-specific logic.

Example:

// src/services/authentication.rs
pub fn authenticate(user: &User) -> bool {
    // Authentication logic here
    true
}

5. handlers/#

This folder is useful if you are building a web server or API. It will contain the request handlers or routes that respond to different HTTP requests.

Example:

// src/handlers/user_handler.rs
use crate::services::authentication;

pub fn login_handler(user: &User) {
    if authentication::authenticate(user) {
        // Send success response
    } else {
        // Send error response
    }
}

6. utils/#

Contains utility functions that are used throughout your application but don’t fit into other categories (e.g., string manipulation, logging, validation).

Example:

// src/utils/validation.rs
pub fn validate_email(email: &str) -> bool {
    // Validate email format
    email.contains('@')
}

7. db/#

Contains database-related logic, such as database models, queries, and migrations. If you’re using an ORM like Diesel, SQLx, or interacting with a database directly, this is where the code goes.

Example:

// src/db/mod.rs
pub fn connect_to_db() {
    // Connection logic here
}

8. config/#

Contains configuration files and environment setup logic. It may include code for loading configuration from environment variables, config files, etc.

Example:

// src/config/mod.rs
use std::env;

pub fn load_config() -> String {
    env::var("MY_CONFIG").unwrap_or_else(|_| String::from("default_value"))
}

9. tests/#

Tests in Rust can be placed in the same module as the code or in a dedicated tests folder. If you want to put integration tests outside the src/ folder, use this directory.

  • Unit tests can be inside the same file as the code.
  • Integration tests can go into this directory.

Example:

// src/tests/integration_test.rs
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_authenticate() {
        let user = User { id: 1, name: String::from("John") };
        assert!(authenticate(&user));
    }
}

10. examples/#

This folder can contain example code or small, runnable projects that demonstrate how to use your library or app. This is especially useful if you’re building a library crate and want to show how it works.

11. scripts/#

For any utility or automation scripts you may have, such as database migrations, test data generation, or deployment scripts.

12. target/#

This is the build output folder that Cargo generates. You should not commit this folder to your version control system, as it’s automatically created when you build your project. Use .gitignore to exclude it.

13. README.md#

The README file should provide basic information about the project, such as how to set up, run, and test the application.

Example Folder Layout#

my_rust_app/
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── main.rs
│   ├── lib.rs
│   ├── bin/
│   │   ├── app1.rs
│   │   └── app2.rs
│   ├── models/
│   │   ├── user.rs
│   │   └── product.rs
│   ├── services/
│   │   ├── authentication.rs
│   │   └── order_processing.rs
│   ├── handlers/
│   │   └── user_handler.rs
│   ├── utils/
│   │   └── validation.rs
│   ├── db/
│   │   └── db_connection.rs
│   ├── config/
│   │   └── config_loader.rs
│   └── tests/
│       └── integration_test.rs
├── examples/
│   └── basic_usage.rs
├── target/
├── scripts/
├── README.md
└── .gitignore

Additional Notes:#

  • Modularization: Try to modularize your code as much as possible to make it easier to maintain and test. Each folder/module should have a specific responsibility.
  • Testing: It’s a good practice to write unit and integration tests to ensure the stability of your application.
  • Documentation: Keep your codebase well-documented. A clear README and comments within the code will make it easier for others (and your future self) to understand.

This folder structure is flexible, so feel free to adjust it based on your specific use case and project requirements!