Axum architecture: modules, API surface, dependency graph

At a Glance

---

What This System Does

Axum is a general-purpose software system built with Rust. The codebase contains 25 modules organized into 7 functional domains.

Business Capabilities

The system is organized around 7 functional domains, each representing a distinct business capability:

Technical Foundation

Module Composition

The codebase follows a layered architecture with clear separation of concerns:

Codebase Health

Strategic Observations

• The codebase follows Core/kernel architecture — `axum-core/src/extract`, `axum-core/src/response`, `axum-core/src/ext_traits` (+5 more), Plugin system — `axum/src/extension.rs`, Middleware pipeline — `axum/src/middleware`, Shared utility layer — `axum/src/util.rs`, `axum/src/test_helpers`, `axum-core/src/lib.rs` (+1 more), Dedicated test infrastructure — `axum/src/test_helpers` architectural patterns, providing a familiar structure for developers.
• With 7 distinct domains, the system has clear separation of concerns suitable for team-based development.

---

This executive summary was generated from comprehensive repository analysis including dependency graphs, data flow detection, and architectural pattern recognition. Enable AI enhancement with `GITHUB_TOKEN` for strategic recommendations, risk assessments, and plain-language explanations tailored for non-technical stakeholders.

<!-- repolens:docs-badge -->  · Examples

The Big Picture

Axum is a medium-sized codebase with clear structure, containing 25 modules spread across 72 files.

---

Technology Stack

The system is built on a modern technology foundation:

Architecture Patterns

The codebase follows 5 identified architectural patterns:

• Core/kernel architecture — `axum-core/src/extract`, `axum-core/src/response`, `axum-core/src/ext_traits` (+5 more) — A structured approach to organizing code and managing complexity.
• Plugin system — `axum/src/extension.rs` — The system supports extensibility through a plugin architecture allowing third-party additions.
• Middleware pipeline — `axum/src/middleware` — A structured approach to organizing code and managing complexity.
• Shared utility layer — `axum/src/util.rs`, `axum/src/test_helpers`, `axum-core/src/lib.rs` (+1 more) — A structured approach to organizing code and managing complexity.
• Dedicated test infrastructure — `axum/src/test_helpers` — A structured approach to organizing code and managing complexity.

Module Architecture

The system is organized into 5 architectural layers:

Layer Details

Other Modules — 5 modules

• axum/src/extract — 15 files — Core application module
• axum/src/routing — 10 files — Core application module
• axum/src/handler — 3 files — Core application module
• axum/src/response — 3 files — Core application module
• +1 more modules

core — 7 modules

• axum-core/src/extract — 7 files — Core application module
• axum-core/src/response — 4 files — Core application module
• axum-core/src/ext_traits — 3 files — Core application module
• axum-core/src/body.rs — 1 files — Core application module
• +3 more modules

middleware — 1 module

• axum/src/middleware — 6 files — Request/response middleware

test — 1 module

• axum/src/test_helpers — 4 files — Utility and helper functions

Shared Libraries — 1 module

• axum-core/src/lib.rs — 1 files — Utility and helper functions

Functional Domains

The following domains represent the largest functional areas by file count:

---

This system overview was generated from comprehensive repository analysis. Enable AI enhancement with `GITHUB_TOKEN` for narrative context, architectural rationale, technology trade-off analysis, and scalability recommendations.

<!-- repolens:docs-badge -->  · Examples

Overview

Axum is organized into 7 functional domains, each representing a distinct area of business capability. This document maps the technical structure to business-oriented functional areas.

Quick Reference:

---

1. Other

Business Capability

Uncategorized module

This is a significant domain with 9 modules and 35 source files.

Key Modules

Business Impact

• Change Frequency Impact: Medium — Changes here affect 35 files
• Domain Complexity: Complex (multiple modules)

---

2. Core Engine

Business Capability

path axum-core/src/extract matches core

This is a focused domain with 7 modules and 18 source files.

Key Modules

Business Impact

• Change Frequency Impact: Low — Changes here affect 18 files
• Domain Complexity: Complex (multiple modules)

---

3. API Layer

Business Capability

path axum/src/middleware matches middleware

This is a focused domain with 2 modules and 9 source files.

Key Modules

Business Impact

• Change Frequency Impact: Low — Changes here affect 9 files
• Domain Complexity: Simple

---

4. Shared Utilities

Business Capability

path axum/src/test_helpers matches helper

This is a focused domain with 4 modules and 7 source files.

Key Modules

Business Impact

• Change Frequency Impact: Low — Changes here affect 7 files
• Domain Complexity: Moderate

---

5. Plugin System

Business Capability

path axum/src/extension.rs matches extension

This is a focused domain with 1 module and 1 source file.

Key Modules

Business Impact

• Change Frequency Impact: Low — Changes here affect 1 file
• Domain Complexity: Simple

---

6. UI Components

Business Capability

path axum/src/form.rs matches form

This is a focused domain with 1 module and 1 source file.

Key Modules

Business Impact

• Change Frequency Impact: Low — Changes here affect 1 file
• Domain Complexity: Simple

---

7. Services

Business Capability

path axum/src/service_ext.rs matches service

This is a focused domain with 1 module and 1 source file.

Key Modules

Business Impact

• Change Frequency Impact: Low — Changes here affect 1 file
• Domain Complexity: Simple

---

Domain Health Summary

---

Domain mapping is based on directory naming conventions and code organization patterns. Enable AI enhancement with `GITHUB_TOKEN` for business-language descriptions, stakeholder impact analysis, strategic recommendations, and cross-domain relationship narratives.

<!-- repolens:docs-badge -->  · Examples

Architectural Philosophy

Axum follows a Core/kernel architecture — `axum-core/src/extract`, `axum-core/src/response`, `axum-core/src/ext_traits` (+5 more) architecture with elements of Plugin system — `axum/src/extension.rs`, Middleware pipeline — `axum/src/middleware`, Shared utility layer — `axum/src/util.rs`, `axum/src/test_helpers`, `axum-core/src/lib.rs` (+1 more), Dedicated test infrastructure — `axum/src/test_helpers`.

Pattern Analysis

Core/kernel architecture — `axum-core/src/extract`, `axum-core/src/response`, `axum-core/src/ext_traits` (+5 more)

A structured approach to organizing code and managing complexity.

Benefits: Structured organization, maintainability, clarity

Plugin system — `axum/src/extension.rs`

The system supports extensibility through a plugin architecture allowing third-party additions.

Benefits: Extensibility, community contributions, core stability

Middleware pipeline — `axum/src/middleware`

A structured approach to organizing code and managing complexity.

Benefits: Structured organization, maintainability, clarity

Shared utility layer — `axum/src/util.rs`, `axum/src/test_helpers`, `axum-core/src/lib.rs` (+1 more)

A structured approach to organizing code and managing complexity.

Benefits: Structured organization, maintainability, clarity

Dedicated test infrastructure — `axum/src/test_helpers`

A structured approach to organizing code and managing complexity.

Benefits: Structured organization, maintainability, clarity

System Layers

The system is organized into 7 functional layers, each encapsulating a distinct area of responsibility:

Module Layers

Modules are classified into 5 architectural roles:

Other Modules

Role: General purpose functionality

core

Role: Supporting application functionality

middleware

Role: Supporting application functionality

test

Role: Supporting application functionality

Shared Libraries

Role: Provides shared utilities and abstractions used across modules

Technology Foundation

Scale & Complexity Analysis

---

This architecture overview was generated from comprehensive dependency graph analysis and pattern detection. Enable AI enhancement with `GITHUB_TOKEN` for architectural narratives, design rationale explanations, scalability analysis, and refactoring recommendations.

<!-- repolens:docs-badge -->  · Examples

A complete inventory of all code modules in the repository, organized by location and size. Each module represents a distinct area of responsibility within the codebase.

Total modules: 25

---

Module Inventory

---

Module detection is based on the `module_roots` setting in your RepoLens configuration. Adjust this setting to change how modules are grouped.

<!-- repolens:docs-badge -->  · Examples

A complete listing of user-facing pages and backend API endpoints. This map shows every URL a user or client can interact with, along with the source file that handles each route.

---

Route Detection

This project is a library/package — it does not define its own routes or pages. Libraries are consumed by other applications that define their own routing.

<!-- repolens:docs-badge -->  · Examples

This page documents both the API endpoints the application exposes and the external services it integrates with. Use it as a reference for understanding the system's interfaces.

---

Internal API Endpoints

These are the backend services the application provides to handle incoming requests.

No API routes were detected in this scan. If your project uses a routing framework (Express, Fastify, NestJS, etc.), ensure the relevant directories are included in your scan.include patterns.

---

External API Integrations

Third-party services the application connects to, grouped by category.

No external API integrations were detected. This section populates automatically when RepoLens identifies SDK imports or API client usage in your codebase.

---

HTTP method reference — GET: retrieve data, POST: create, PUT/PATCH: update, DELETE: remove.

<!-- repolens:docs-badge -->  · Examples

Understanding Data Movement

Data flows describe how information moves through Axum — from external inputs through processing layers to storage or presentation. Understanding these flows is essential for debugging, performance optimization, and architectural decisions.

Flow Detection Results

No data flows were detected in the codebase. This typically indicates one of the following:

1. Simple request-response pattern — The system uses straightforward HTTP request/response patterns without complex pipelines
2. Event-driven architecture — Data flows through event listeners that are harder to detect statically
3. External orchestration — Flow control happens outside this codebase (e.g., in a parent service or message queue)

Recommendations

To help RepoLens detect flows more accurately, consider:

• Adding descriptive naming conventions (e.g., processOrder, handlePayment)
• Using consistent file patterns for flow entry points
• Documenting flows explicitly in code comments

---

Flow detection is based on naming conventions and import patterns. Enable AI enhancement with `GITHUB_TOKEN` for intelligent flow inference from code structure, even when explicit patterns are absent.

<!-- repolens:docs-badge -->  · Examples

No changes detected.

<!-- repolens:docs-badge -->  · Examples

What is this? This visual diagram shows how different parts of your codebase connect to each other. Arrows indicate dependencies (which modules use which).

Showing: 25 modules and 0 relationships

Source: Heuristic inference (run full publish for import-based analysis)

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│              🏗️  SYSTEM ARCHITECTURE MAP                    │
└─────────────────────────────────────────────────────────────┘

⚙️  CORE LOGIC
│
├── extract (7 files)
├── response (4 files)
├── ext_traits (3 files)
├── body.rs (1 file)
├── error.rs (1 file)
├── lib.rs (1 file)
├── macros.rs (1 file)
└── body (1 file)
│
🧩  PLUGINS
│
└── extension.rs (1 file)
│
🔀  MIDDLEWARE
│
└── middleware (6 files)
│
⚡  SERVICES
│
└── service_ext.rs (1 file)
│
🛠️  UTILITIES
│
├── lib.rs (1 file)
└── util.rs (1 file)
│
✅  TESTING
│
└── test_helpers (4 files)
│
📦  OTHER
│
├── extract (15 files)
├── routing (10 files)
├── handler (3 files)
├── response (3 files)
├── serve (2 files)
├── body (1 file)
├── boxed.rs (1 file)
├── form.rs (1 file)
├── json.rs (1 file)
├── macros.rs (1 file)
└── error_handling (1 file)
│

Legend:
  →  imports / depends on
  ╌→ tests

<!-- repolens:docs-badge -->  · Examples

Welcome to Axum! 👋

This guide will help you get up to speed quickly. Axum is a general-purpose tools project built with Rust, containing 25 modules across 72 files.

What You'll Learn

1. ✅ Repository structure and organization
2. ✅ Technology stack and tools
3. ✅ Key modules to understand first
4. ✅ How data flows through the system
5. ✅ How to start contributing

---

Quick Reference Card

---

Repository Structure

Understanding the directory layout is your first step to navigating the codebase:

Where to Begin

Focus on these directories first:

1. `axum/src` — Project files
2. `axum-core/src` — Project files

---

Technology Stack

---

Core Modules to Understand

These are the most important modules by size and centrality. Understanding them will unlock the rest of the codebase:

---

Getting Started Checklist

Follow these steps to set up your development environment:

1. Clone and Install

git clone <repository-url>
cd axum
npm install  # or yarn, pnpm

2. Explore the Structure

• Review the directory structure above
• Open the README.md for project-specific instructions
• Look for CONTRIBUTING.md for contribution guidelines

3. Understand Core Modules

Start with the high-priority modules listed above. Read the code and comments to understand:

• What problem each module solves
• How modules interact with each other
• What data structures are used

4. Make Your First Change

Start small:

1. Find a small bug or typo to fix
2. Make the change in a feature branch
3. Run tests to ensure nothing breaks
4. Submit a pull request for review

---

Common Pitfalls

New contributors often run into these issues:

• Environment setup — Check for .env.example files and ensure you have all required environment variables.
• Branch naming — Follow the team's branch naming conventions (usually feature/, fix/, docs/).

---

Additional Resources

---

This onboarding guide was generated from comprehensive repository analysis. Enable AI enhancement with `GITHUB_TOKEN` for narrative walkthroughs, common pitfall documentation, debugging tips, architecture deep-dives, and personalized contribution recommendations.

Welcome to the team! Happy coding! 🚀

<!-- repolens:docs-badge -->  · Examples

No GraphQL schema was detected in this repository.

RepoLens scans for .graphql and .gql schema files, inline SDL via tagged template literals (e.g. gql\...\``), resolver patterns, and popular GraphQL libraries including Apollo, Yoga, Nexus, Pothos, Mercurius, type-graphql, Relay, and urql.

If your project uses GraphQL, ensure the relevant source directories are included in your scan.include configuration.

<!-- repolens:docs-badge -->  · Examples

No TypeScript type declarations were detected in this repository.

RepoLens analyzes .ts and .tsx files for interface declarations, type aliases, classes, and enums. Ensure your TypeScript source directories are included in the scan.include configuration.

<!-- repolens:docs-badge -->  · Examples

No source files were found to analyze for import dependencies.

Ensure your scan.include patterns cover the relevant source directories.

<!-- repolens:docs-badge -->  · Examples

No baseline found. Run repolens publish once to establish a baseline.

A baseline snapshot of the current architecture has been saved. On subsequent runs, this report will track structural changes across the following dimensions:

<!-- repolens:docs-badge -->  · Examples

No security anti-patterns were detected in the scanned source files.

RepoLens scans JavaScript and TypeScript source files for common security risks including code injection (eval), XSS (innerHTML), SQL injection, command injection, prototype pollution, hardcoded credentials, and insecure randomness.

Test files, configs, and build outputs are excluded from analysis to reduce false positives.

<!-- repolens:docs-badge -->  · Examples

No source files were available for health analysis.

RepoLens computes a health score (0–100) per module by synthesizing cyclomatic complexity, coupling (fan-in × fan-out), documentation coverage, and security findings. Ensure your scan.include patterns cover the relevant source directories.

<!-- repolens:docs-badge -->  · Examples