# Key Source Files for Understanding Maven's Core Concepts: A Deep Dive into Apache Maven's Architecture

> Explore ten key source files in the apache maven repository to understand Maven's core concepts like POM parsing and dependency resolution. Explore the architecture.

- Repository: [The Apache Software Foundation/maven](https://github.com/apache/maven)
- Tags: deep-dive
- Published: 2026-07-07

---

**Studying the ten core source files in the `apache/maven` repository—from [`MavenSession.java`](https://github.com/apache/maven/blob/main/MavenSession.java) to [`DefaultProjectBuilder.java`](https://github.com/apache/maven/blob/main/DefaultProjectBuilder.java)—reveals how Maven parses POMs, builds the reactor graph, resolves dependencies, and executes plugin goals.**

Apache Maven's architecture revolves around a handful of central classes that model the build lifecycle, project structure, and execution environment. Understanding these **key source files for understanding Maven's core concepts** provides essential insight into how the build tool transforms [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml) files into executable build plans. This guide examines the specific Java source files that handle everything from command-line parsing to artifact resolution in the Maven codebase.

## Maven Session and CLI Entry Point

The build process begins with the command-line interface and the runtime session that encapsulates the entire build state.

**[`api/maven-api-cli/src/main/java/org/apache/maven/api/cli/mvn/MavenCli.java`](https://github.com/apache/maven/blob/main/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/mvn/MavenCli.java)** serves as the primary entry point for the `mvn` command. This class parses command-line options, creates a `MavenExecutionRequest`, and invokes the core execution pipeline. It bridges user input with the internal execution framework.

**[`impl/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/execution/MavenSession.java)** represents the **Maven Session**—the runtime context that holds the current build, the reactor, user/system properties, and the request/response objects. According to the `apache/maven` source code, this class stores the overall state of a build, manages the list of projects (the reactor), and provides access to services like the repository system.

## Project Model and Construction

Maven transforms raw XML into resolved, executable project objects through a multi-stage building process.

**[`api/maven-api-model/src/main/java/org/apache/maven/model/Model.java`](https://github.com/apache/maven/blob/main/api/maven-api-model/src/main/java/org/apache/maven/model/Model.java)** defines the raw **Project Model** representation of a POM. This class contains fields such as `groupId`, `artifactId`, `version`, `dependencies`, `build`, and parent/extension handling. It represents the in-memory object created directly from parsing a [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml) file.

**[`impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectBuilder.java)** implements the **Project Builder** logic that turns a raw XML model into a fully-validated `MavenProject`. This file demonstrates the workflow for reading a POM, applying inheritance, interpolating expressions, and assembling the final project instance.

**[`impl/maven-core/src/main/java/org/apache/maven/project/MavenProject.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/MavenProject.java)** provides the concrete, fully-resolved representation of a module used throughout the build. Unlike the raw `Model` class, `MavenProject` contains resolved coordinates, collected dependencies, plugin bindings, and the directory layout used by mojos during execution.

## Build Lifecycle and Plugin Execution

Maven's build lifecycle binds plugin goals to specific phases, creating a structured execution plan.

**[`compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/lifecycle/Lifecycle.java`](https://github.com/apache/maven/blob/main/compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/lifecycle/Lifecycle.java)** defines the **Lifecycle & Phase Mapping** for Maven's default lifecycle (validate → install → deploy). This file lists the standard phases, default plugins bound to each phase, and how custom lifecycles can be defined within the `apache/maven` codebase.

**[`compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecution.java`](https://github.com/apache/maven/blob/main/compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/MojoExecution.java)** encapsulates the **Mojo Execution**—the unit of work a plugin performs during a phase. This class stores a specific plugin goal, its configuration, and execution parameters that are passed to the plugin's `execute()` method.

**[`compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/PluginDescriptor.java`](https://github.com/apache/maven/blob/main/compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/PluginDescriptor.java)** handles the **Plugin Descriptor** metadata that describes a plugin's goals, parameters, and default bindings. This source file shows how Maven reads [`META-INF/maven/plugin.xml`](https://github.com/apache/maven/blob/main/META-INF/maven/plugin.xml) to discover a plugin's capabilities and configuration requirements.

## Dependency Resolution and Reactor Graph

Multi-module builds and artifact resolution rely on graph algorithms and repository management.

**[`impl/maven-graph/src/main/java/org/apache/maven/graph/DefaultReactorGraph.java`](https://github.com/apache/maven/blob/main/impl/maven-graph/src/main/java/org/apache/maven/graph/DefaultReactorGraph.java)** implements the **Reactor (Build Order Graph)**. This class constructs the directed-acyclic graph that models inter-module dependencies and drives the multi-module build order, detecting cycles and determining the correct sequence for project compilation.

**[`impl/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/MavenRepositorySystem.java`](https://github.com/apache/maven/blob/main/impl/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/MavenRepositorySystem.java)** manages the **Repository System** for artifact resolution. This source file demonstrates interaction with the Eclipse Aether resolver, handling dependency collection, download from remote repositories, and local cache management.

## Practical Code Examples

The following snippets illustrate how these core classes interact during a typical build.

```java
// 1️⃣ Create a Maven execution request from CLI args
MavenCli cli = new MavenCli();
MavenExecutionRequest request = cli.requestBuilder()
                                 .setUserSettingsFile(new File("settings.xml"))
                                 .setGoal("install")
                                 .build();

// 2️⃣ Build the MavenSession (contains the request, repository system, etc.)
MavenSession session = cli.execute(request);

// 3️⃣ Inside MavenExecutionPlanBuilder the reactor graph is built:
//    – MavenProject instances are created by DefaultProjectBuilder
//    – Dependencies are resolved via MavenRepositorySystem
//    – Lifecycle phases are mapped to MojoExecutions

List<MavenProject> projects = session.getProjects();   // the reactor

```

```java
// 4️⃣ A MojoExecution example (inside a plugin):
public class CompileMojo extends AbstractMojo {
    @Parameter(defaultValue = "${project}", readonly = true)
    private MavenProject project;

    public void execute() throws MojoExecutionException {
        // Access compiled source directory, classpath, etc.
        File outputDir = new File(project.getBuild().getOutputDirectory());
        // ... compile sources ...
    }
}

```

## Summary

- **[`MavenCli.java`](https://github.com/apache/maven/blob/main/MavenCli.java)** serves as the command-line entry point that initializes the execution request.
- **[`MavenSession.java`](https://github.com/apache/maven/blob/main/MavenSession.java)** maintains the runtime build context and reactor state throughout the build.
- **[`Model.java`](https://github.com/apache/maven/blob/main/Model.java)** represents the raw POM structure, while **[`DefaultProjectBuilder.java`](https://github.com/apache/maven/blob/main/DefaultProjectBuilder.java)** and **[`MavenProject.java`](https://github.com/apache/maven/blob/main/MavenProject.java)** handle transformation into resolved build objects.
- **[`DefaultReactorGraph.java`](https://github.com/apache/maven/blob/main/DefaultReactorGraph.java)** determines multi-module build order using a directed-acyclic graph.
- **[`Lifecycle.java`](https://github.com/apache/maven/blob/main/Lifecycle.java)**, **[`MojoExecution.java`](https://github.com/apache/maven/blob/main/MojoExecution.java)**, and **[`PluginDescriptor.java`](https://github.com/apache/maven/blob/main/PluginDescriptor.java)** define how Maven binds plugin goals to lifecycle phases.
- **[`MavenRepositorySystem.java`](https://github.com/apache/maven/blob/main/MavenRepositorySystem.java)** handles artifact resolution from local and remote repositories.

## Frequently Asked Questions

### What is the difference between Model and MavenProject in Maven's source code?

**`Model`** ([`api/maven-api-model/src/main/java/org/apache/maven/model/Model.java`](https://github.com/apache/maven/blob/main/api/maven-api-model/src/main/java/org/apache/maven/model/Model.java)) represents the raw, unprocessed POM as parsed from XML, containing literal values from the [`pom.xml`](https://github.com/apache/maven/blob/main/pom.xml) file. **`MavenProject`** ([`impl/maven-core/src/main/java/org/apache/maven/project/MavenProject.java`](https://github.com/apache/maven/blob/main/impl/maven-core/src/main/java/org/apache/maven/project/MavenProject.java)) represents the fully-resolved, interpolated, and inheritance-processed project object used during the actual build, including resolved dependencies and effective plugin bindings.

### Which source file determines the order of builds in a multi-module Maven project?

**[`impl/maven-graph/src/main/java/org/apache/maven/graph/DefaultReactorGraph.java`](https://github.com/apache/maven/blob/main/impl/maven-graph/src/main/java/org/apache/maven/graph/DefaultReactorGraph.java)** implements the reactor graph that determines build order. This class constructs a directed-acyclic graph (DAG) from inter-module dependencies, ensuring that upstream modules are built before dependent modules and detecting circular dependency cycles.

### How does Maven convert command-line arguments into an executable build plan?

The **[`MavenCli.java`](https://github.com/apache/maven/blob/main/MavenCli.java)** class ([`api/maven-api-cli/src/main/java/org/apache/maven/api/cli/mvn/MavenCli.java`](https://github.com/apache/maven/blob/main/api/maven-api-cli/src/main/java/org/apache/maven/api/cli/mvn/MavenCli.java)) parses command-line arguments and creates a `MavenExecutionRequest`. This request is then used to initialize a **`MavenSession`**, which coordinates with **`DefaultProjectBuilder`** to create projects and **[`Lifecycle.java`](https://github.com/apache/maven/blob/main/Lifecycle.java)** to map phases to specific **`MojoExecution`** instances.

### Where does Maven define the default lifecycle phases like compile and install?

The default lifecycle phases are defined in **[`compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/lifecycle/Lifecycle.java`](https://github.com/apache/maven/blob/main/compat/maven-plugin-api/src/main/java/org/apache/maven/plugin/lifecycle/Lifecycle.java)**. This source file contains the standard phase definitions (validate, initialize, compile, test, package, verify, install, deploy) and the default plugin bindings that attach specific goals to each phase in the `apache/maven` codebase.