# How to Understand Jenkins' Internal Architecture From the Code: A Developer's Guide

> Dive into Jenkins' internal architecture by exploring its code. Understand core components like the Jenkins singleton, PluginManager, and ExtensionList to master Jenkins development.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: internals
- Published: 2026-08-01

---

**Jenkins is a modular, extensible Java application centered around the `Jenkins` singleton, which orchestrates subsystems including plugin management, extension points, job hierarchies, build execution, and security through specific classes like `PluginManager`, `ExtensionList`, and `Queue`.**

To truly understand Jenkins' internal architecture from the code, you must explore the `jenkinsci/jenkins` repository, where the core Java modules reveal a design built on the `Jenkins` singleton as the global state coordinator. The architecture separates concerns into distinct subsystems—each with dedicated entry points in the source tree—that handle everything from plugin isolation to build scheduling via the Stapler web framework.

## Core Engine and Global State

The heart of Jenkins resides in [`jenkins/model/Jenkins.java`](https://github.com/jenkinsci/jenkins/blob/main/jenkins/model/Jenkins.java), where the `Jenkins` singleton class manages the application lifecycle. This class implements `StaplerProxy` to serve as the root object for the web UI and provides access to all major subsystems through methods like `getPluginManager()` and `getQueue()`. When the servlet container starts, `hudson.WebAppMain` instantiates this singleton, triggering the **InitReactor** (`InitReactorRunner`) to walk through initialization phases defined in [`hudson/init/InitMilestone.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/init/InitMilestone.java), including `PLUGINS_PREPARED` and `EXTENSIONS_AUGMENTED`.

## Plugin Management and Isolation

Plugin discovery and loading are handled by [`hudson/PluginManager.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/PluginManager.java) (and its subclass `LocalPluginManager`), which maintains a map of `PluginWrapper` objects representing each installed plugin. Each plugin receives its own class loader (`ExistanceCheckingClassLoader` or `CachingClassLoader`), enabling hot-reloading and isolation. You can inspect loaded plugins programmatically:

```java
Jenkins jenkins = Jenkins.get();
PluginManager pm = jenkins.getPluginManager();
for (PluginWrapper pw : pm.getPlugins()) {
    System.out.println(pw.getShortName() + " – " + pw.getVersion());
}

```

## Extension Mechanism

Jenkins uses an annotation-driven extension system defined in [`hudson/ExtensionList.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/ExtensionList.java). Classes annotated with `@Extension` are discovered by `ExtensionFinder` during startup and registered in `ExtensionList` instances for each extension point. To retrieve all implementations of a specific type (such as SCM providers):

```java
ExtensionList<SCM> scms = Jenkins.get().getExtensionList(SCM.class);
scms.forEach(scm -> System.out.println(scm.getClass().getName()));

```

## Item and Job Hierarchy

The model layer, defined in [`hudson/model/Item.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Item.java) and [`hudson/model/Job.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Job.java), represents all configurable entities. All top-level items implement `TopLevelItem`, while `ItemGroup` provides container semantics for hierarchical organization. The `Job` class extends this hierarchy to add build-related methods like `getBuilds()` and `scheduleBuild()`.

## Build Execution and Run Management

Builds are tracked through the `Run` class hierarchy in [`hudson/model/Run.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Run.java), with concrete implementations like `Build` for freestyle projects. The `Executor` class (referenced in [`hudson/model/Queue.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Queue.java)) runs build threads on agents, managing workspaces and result recording via `WorkspaceCleanupThread`.

## Queue and Scheduling System

The [`hudson/model/Queue.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Queue.java) file contains the `Queue` class, which holds pending build requests as `Queue.Item` objects. When resources become available, the queue consults `Computer` instances (representing agents) and their `Executor` pools to assign tasks. Flyweight tasks (like pipeline steps) run on the master, while heavyweight tasks distribute to agents.

## Security and Authorization

Security is managed through [`hudson/security/SecurityRealm.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/security/SecurityRealm.java), which defines authentication mechanisms (LDAP, Unix, etc.), and `AuthorizationStrategy`, which creates `ACL` objects governing permissions. Every `Item` and `Run` maintains an ACL checked via `hasPermission()`. CSRF protection is implemented through `CrumbIssuer`.

```java
ACL acl = Jenkins.get().getAuthentication().impersonate(User.current());
System.out.println("Can read config? " + acl.hasPermission(Jenkins.READ));

```

## Stapler Web Framework

Jenkins uses Stapler for URL routing and request handling, with integration points in [`hudson/web/StaplerProxy.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/web/StaplerProxy.java). The framework maps URLs to Java methods by convention, allowing `Jenkins` to serve as the URL root (`/`) while delegating to `RootAction` implementations for specific paths.

## Configuration and Persistence

Configuration serialization uses XStream via [`hudson/util/XmlFile.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/util/XmlFile.java) and `XStream2`. The `PersistedList` class handles collections that automatically save to disk, ensuring that changes to jobs or system configuration persist across restarts.

## Practical Code Examples for Navigating the Architecture

### Creating and Configuring Jobs Programmatically

To create a freestyle job through the API, use the `createProject` method in [`Jenkins.java`](https://github.com/jenkinsci/jenkins/blob/main/Jenkins.java):

```java
Jenkins jenkins = Jenkins.get();
FreeStyleProject proj = jenkins.createProject(FreeStyleProject.class, "example-job");
proj.setDescription("Created via the Jenkins API");
proj.save();

```

### Scheduling Builds and Inspecting Queue Status

Triggering a build returns a `Queue.Item` from [`hudson/model/Queue.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Queue.java):

```java
Job<?,?> job = Jenkins.get().getItemByFullName("example-job", Job.class);
Queue.Item queueItem = job.scheduleBuild2(0).getItem();
System.out.println("Queued: " + queueItem.getId());

```

## Summary

- **The `Jenkins` singleton** ([`jenkins/model/Jenkins.java`](https://github.com/jenkinsci/jenkins/blob/main/jenkins/model/Jenkins.java)) serves as the central hub, managing global state and providing access to all subsystems.
- **Plugin isolation** is enforced through dedicated class loaders managed by `PluginManager` ([`hudson/PluginManager.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/PluginManager.java)), with `PluginWrapper` tracking metadata.
- **Extensions** are discovered via the `@Extension` annotation and aggregated in `ExtensionList` ([`hudson/ExtensionList.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/ExtensionList.java)) for dependency injection.
- **Job hierarchies** are modeled through `Item` and `Job` ([`hudson/model/Item.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Item.java)), with `Queue` ([`hudson/model/Queue.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Queue.java)) handling scheduling across `Computer` agents.
- **Security** is enforced through `ACL` objects created by `SecurityRealm` ([`hudson/security/SecurityRealm.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/security/SecurityRealm.java)) and checked on all sensitive operations.
- **Persistence** relies on XStream serialization via `XmlFile` ([`hudson/util/XmlFile.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/util/XmlFile.java)), storing configuration as XML on disk.

## Frequently Asked Questions

### What is the best starting point for understanding Jenkins' internal architecture from the code?

Begin with [`jenkins/model/Jenkins.java`](https://github.com/jenkinsci/jenkins/blob/main/jenkins/model/Jenkins.java), which contains the singleton instance and entry points to all major subsystems. This file shows how the `PluginManager`, `Queue`, and security components are wired together during initialization in `hudson.WebAppMain`.

### How does Jenkins isolate plugins at runtime?

Each plugin loads in its own `ExistanceCheckingClassLoader` or `CachingClassLoader`, managed by [`hudson/PluginManager.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/PluginManager.java). This isolation prevents class conflicts between plugins while allowing the core to hot-reload or uninstall plugins safely via the `PluginWrapper` abstraction.

### What is Stapler and how does it relate to Jenkins' architecture?

Stapler is the web framework that binds URLs to Java object methods by convention. Defined in [`hudson/web/StaplerProxy.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/web/StaplerProxy.java), it enables `Jenkins` to act as the URL root and routes HTTP requests to the appropriate `Item`, `Run`, or `RootAction` without explicit servlet mapping.

### How does Jenkins decide which agent executes a build?

The `Queue` class ([`hudson/model/Queue.java`](https://github.com/jenkinsci/jenkins/blob/main/hudson/model/Queue.java)) evaluates available `Computer` instances (agents) and their `Executor` pools, matching task requirements (labels, resources) against agent capabilities. Once matched, the `Executor` thread runs the build using the `Run` class to track execution state.