📦 Axum Base Recipe

A pluggable, highly modular starter architecture for building decoupled and scalable APIs with Rust and Axum.

This recipe establishes a clear feature-driven isolation pattern, allowing developers to drop in or remove standalone modules effortlessly without breaking the application core.

📂 Architecture Overview

Every feature (e.g., health, auth, users) lives inside its own isolated folder under src/modules/. Modules expose only their unified router to the central router system.

src/
├── main.rs          # Application entry point (Server boot & listener)
├── lib.rs           # Crate root exporting core routing and modules
├── routes.rs        # Central router hub (Where modules are mounted via .nest())
└── modules/
    ├── mod.rs       # Module registry (Enables/disables standalone modules)
    └── health/      # Example of an isolated feature module
        ├── mod.rs   # Entry point exposing the feature's router
        └── routes.rs # Feature-specific handlers and endpoints

🚀 Key Design Philosophies

• Strict Isolation: Modules do not cross-contaminate. Code inside modules/health/ knows nothing about external modules.
• Plug & Play (Router::nest): To attach or detach a feature, you only add or remove a single line in src/routes.rs.
• Crate-Ready: The architecture separates binary logic (main.rs) from library logic (lib.rs), making it trivial to extract features into standalone open-source crates later.

🛠️ Quick Start

1. Installation & Recipe Setup

The setup lifecycle automatically handles configuration and pulls the essential asynchronous and serialization primitives:

cargo add axum
cargo add tokio --features full
cargo add serde --features derive

2. Booting the Server

Run the application locally:

cargo run

Once booted, the application mounts your decoupled modules under the specified path prefixes:

• Health Check Endpoint: GET [http://127.0.0.1:3000/api/health](http://127.0.0.1:3000/api/health)

🔌 How to Add a New Feature Module

To expand your API with a new module (e.g., a users module) without causing architectural drift, follow these three steps:

1. Create the Folder Structure: Create src/modules/users/mod.rs and write your handlers/routes inside it, exposing a single pub fn router() -> Router function.
2. Register the Module: Open src/modules/mod.rs and register your new folder:

pub mod health;
pub mod users; // <-- Add this

3. Mount the Route Hub: Inject the standalone router into the gateway tree in src/routes.rs:

pub fn create_router() -> Router {
    Router::new()
        .nest("/api/health", modules::health::router())
        .nest("/api/users", modules::users::router()) // <-- Mount here
}