# apache/roller architecture

> Architecture diagram of the GitHub repository apache/roller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/roller
- Repository: https://github.com/apache/roller

## Overview

1. **Overall shape**
Apache Roller is a single Java web application with a layered monolithic architecture. The main runtime is the `app` module, which packages the webapp, business services, persistence mappings, templates, and UI actions. It is typically deployed to a servlet container such as Tomcat, with a relational database behind it.

2. **Top-level Maven modules**
The repo is organized into a few clearly separated projects: `app` for the product runtime, `assembly-release` for distribution packaging, `docs` for user/install/template documentation, `it-selenium` for browser-level integration tests, and `db-utils` for Derby test support. The root `pom.xml` ties these together.

3. **Request entry points**
HTTP traffic enters through `web.xml` and is split across several interfaces:
- the main blog rendering pipeline under `ui/rendering/servlets`
- the admin/editor UI under Struts2 actions in `ui/struts2`
- public APIs under `webservices` such as AtomPub, XML-RPC, OAuth, OpenSearch, and tag data
- auxiliary endpoints for media, comments, trackbacks, previews, and feeds

4. **Web UI composition**
The application has two major presentation styles:
- **Struts2-backed admin/editor screens** for managing users, weblogs, entries, templates, media, comments, and configuration
- **Velocity-driven public site rendering** for weblog pages, feeds, and themes  
The UI layer is heavy on JSPs, Tiles layouts, Velocity templates, and UI-specific action beans/interceptors.

5. **Core domain and service layer**
Most application logic sits in `weblogger/business` and `planet/business`. These packages define managers and service interfaces for users, weblogs, entries, bookmarks, media files, comments, themes, properties, search, pinging, threads, and OAuth. The `WebloggerFactory`/`WebloggerImpl` and `PlanetManager` are the main access points to these subsystems.

6. **Persistence boundary**
The application uses JPA for most persistent state, with implementation classes under `business/jpa` and ORM metadata in `resources/org/apache/roller/.../*.orm.xml`. This is where entities such as users, weblogs, entries, comments, permissions, ping queues, media files, and theme/template records are stored. The database is an external dependency and the codebase includes SQL scripts for multiple vendors.

7. **Content rendering pipeline**
Public weblog requests are parsed into request objects, mapped to the correct page/feed/resource model, then rendered by Velocity. The rendering layer includes request mappers, model loaders, pagers, and Velocity resource loaders. Themes and templates are first-class runtime assets, so page rendering depends on both database-stored template metadata and filesystem/theme resources.

8. **Background work and scheduling**
Roller performs several asynchronous or scheduled jobs in `business/runnable` and `tasks`. These include hit-count processing, scheduled entries, cache warmup, ping queue processing, planet refresh tasks, and static planet generation. The task system uses worker threads and leasing/locking to avoid duplicate execution across nodes.

9. **Search and indexing**
Search is handled as a separate subsystem under `business/search/lucene`. Weblog entries are indexed into Lucene, and search requests flow through dedicated models and servlet endpoints. Index updates are triggered by content changes, while search results are rendered as pages or feeds.

10. **Caching and performance**
There is an explicit caching layer in `util/cache` and rendering-side caches for pages, feeds, salt values, site-wide content, and planet data. This boundary sits between request handling and the underlying database/templates to reduce repeated rendering and lookup costs. Cache warmup is also part of the scheduled job set.

11. **Planet subsystem**
The `planet` packages implement blog aggregation: fetching external feeds, persisting subscriptions/groups, and generating combined planet pages/feeds. It is integrated into the main Roller app through specialized tasks, UI screens, and feed rendering models. Feed fetching uses Rome-based infrastructure.

12. **External integrations**
Several features cross system boundaries:
- outbound blog pings and auto-pings
- feed fetching from remote sites
- comment spam and validation hooks, including Akismet-style validation
- email notifications via mail utilities
- OAuth and legacy blogging APIs for client integrations  
These integrations are service-layer concerns, not UI concerns.

13. **Security and startup**
Startup and authentication are handled early in the request lifecycle. Filters initialize the app, manage persistence sessions, load security salts, enforce security, and support OpenID/role assignment. There is also a startup/database-install path for first-run setup and schema creation.

14. **Static assets and runtime resources**
Themes, templates, SQL scripts, localization bundles, logging config, and web resources are all packaged with the app. The runtime therefore depends on both database state and filesystem/classpath assets. The `app/src/main/webapp/themes` tree is especially important because it defines the visible site output.

15. **Testing and deployment**
Unit tests cover business logic, utilities, UI helpers, and search. Integration tests are split between DB-related tests and Selenium browser tests. Docker and Docker Compose provide a reproducible demo/runtime path, while the release assembly module creates the official distributable artifacts.

Main entry points: [`app/src/main/java/org/apache/roller/weblogger/business`](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business) (Business layer), [`pom.xml`](https://github.com/apache/roller/blob/master/pom.xml) (Root POM), [`app/src/main/webapp/WEB-INF/web.xml`](https://github.com/apache/roller/blob/master/app/src/main/webapp/WEB-INF/web.xml) (Web entry), [`app/src/main/java/org/apache/roller/weblogger/ui/rendering`](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/rendering) (Rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_root_pom["Root POM<br/>build aggregator<br/>[pom.xml]"]
  node_app_module["App module<br/>[pom.xml]"]
  node_assembly_module["Release assembly<br/>packaging module<br/>[pom.xml]"]
  node_docs_module["Docs<br/>documentation<br/>[README.md]"]
  node_selenium_module["Selenium ITs<br/>integration tests<br/>[pom.xml]"]
  node_db_utils_module["DB utils<br/>test support<br/>[pom.xml]"]
end

subgraph group_app["App runtime"]
  node_webxml["Web entry<br/>servlet config<br/>[web.xml]"]
  node_core_ui["Core UI<br/>ui core"]
  node_struts_ui["Struts2 UI<br/>admin/editor UI"]
  node_rendering["Rendering<br/>public site pipeline"]
  node_webservices["Web services<br/>api endpoints"]
  node_business["Business layer<br/>service layer"]
  node_persistence[("JPA persistence<br/>persistence boundary")]
  node_search["Lucene search<br/>indexing subsystem"]
  node_planet["Planet<br/>aggregation subsystem"]
  node_tasks["Background tasks<br/>scheduler/workers"]
  node_cache["Caches<br/>caching layer"]
  node_resources["Runtime assets<br/>templates/config"]
  node_webapp_assets["Web assets<br/>web resources"]
end

subgraph group_support["Support"]
  node_external_db[("Database<br/>external dependency")]
  node_servlet_container["Servlet container<br/>external dependency"]
end

node_root_pom -->|"builds"| node_app_module
node_root_pom -->|"builds"| node_assembly_module
node_root_pom -->|"includes"| node_docs_module
node_root_pom -->|"builds"| node_selenium_module
node_root_pom -->|"builds"| node_db_utils_module
node_app_module -->|"starts at"| node_webxml
node_webxml -->|"routes to"| node_core_ui
node_webxml -->|"routes to"| node_struts_ui
node_webxml -->|"routes to"| node_rendering
node_webxml -->|"routes to"| node_webservices
node_core_ui -->|"uses"| node_business
node_struts_ui -->|"uses"| node_business
node_rendering -->|"loads from"| node_business
node_rendering -->|"accelerates"| node_cache
node_rendering -->|"renders with"| node_resources
node_business -->|"persists via"| node_persistence
node_business -->|"indexes via"| node_search
node_business -->|"schedules"| node_tasks
node_business -->|"uses"| node_cache
node_business -->|"integrates"| node_planet
node_persistence -->|"stores in"| node_external_db
node_tasks -.->|"coordinates"| node_external_db
node_webservices -->|"calls"| node_business
node_webservices -.->|"reads/writes"| node_external_db
node_app_module -->|"deploys to"| node_servlet_container
node_resources -.->|"shapes"| node_webapp_assets
node_planet -->|"uses"| node_resources

click node_root_pom "https://github.com/apache/roller/blob/master/pom.xml"
click node_app_module "https://github.com/apache/roller/blob/master/app/pom.xml"
click node_assembly_module "https://github.com/apache/roller/blob/master/assembly-release/pom.xml"
click node_docs_module "https://github.com/apache/roller/blob/master/docs/README.md"
click node_selenium_module "https://github.com/apache/roller/blob/master/it-selenium/pom.xml"
click node_db_utils_module "https://github.com/apache/roller/blob/master/db-utils/pom.xml"
click node_webxml "https://github.com/apache/roller/blob/master/app/src/main/webapp/WEB-INF/web.xml"
click node_core_ui "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/core"
click node_struts_ui "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/struts2"
click node_rendering "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/rendering"
click node_webservices "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/webservices"
click node_business "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business"
click node_persistence "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business/jpa"
click node_search "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business/search/lucene"
click node_planet "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/planet"
click node_tasks "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business/runnable"
click node_cache "https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/util/cache"
click node_resources "https://github.com/apache/roller/tree/master/app/src/main/resources"
click node_webapp_assets "https://github.com/apache/roller/tree/master/app/src/main/webapp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_pom,node_app_module,node_assembly_module,node_docs_module,node_selenium_module,node_db_utils_module toneBlue
class node_webxml,node_core_ui,node_struts_ui,node_rendering,node_webservices,node_business,node_persistence,node_search,node_planet,node_tasks,node_cache,node_resources,node_webapp_assets toneAmber
class node_external_db,node_servlet_container toneMint
```

## Components

### Repository

Top-level Maven modules and supporting assets

- [Root POM](https://github.com/apache/roller/blob/master/pom.xml): build aggregator · Coordinates the multi-module build · `pom.xml`
- [App module](https://github.com/apache/roller/blob/master/app/pom.xml): webapp module · Main Java web application runtime · `app/pom.xml`
- [Release assembly](https://github.com/apache/roller/blob/master/assembly-release/pom.xml): packaging module · Builds distributable release artifacts · `assembly-release/pom.xml`
- [Docs](https://github.com/apache/roller/blob/master/docs/README.md): documentation · User, install, and example documentation · `docs/README.md`
- [Selenium ITs](https://github.com/apache/roller/blob/master/it-selenium/pom.xml): integration tests · Browser-level integration test suite · `it-selenium/pom.xml`
- [DB utils](https://github.com/apache/roller/blob/master/db-utils/pom.xml): test support · Derby lifecycle and database test helpers · `db-utils/pom.xml`

### App runtime

Main Roller web application and its internal architecture

- [Web entry](https://github.com/apache/roller/blob/master/app/src/main/webapp/WEB-INF/web.xml): servlet config · Request routing and filter/servlet wiring · `app/src/main/webapp/WEB-INF/web.xml`
- [Core UI](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/core): ui core · Startup filters, security, and UI session handling · `app/src/main/java/org/apache/roller/weblogger/ui/core`
- [Struts2 UI](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/struts2): admin/editor UI · Admin and editor actions, beans, and interceptors · `app/src/main/java/org/apache/roller/weblogger/ui/struts2`
- [Rendering](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/ui/rendering): public site pipeline · Request mapping, models, pagers, and Velocity rendering · `app/src/main/java/org/apache/roller/weblogger/ui/rendering`
- [Web services](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/webservices): api endpoints · AtomPub, XML-RPC, OAuth, OpenSearch, and tag data · `app/src/main/java/org/apache/roller/weblogger/webservices`
- [Business layer](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business): service layer · Managers and domain services for Roller · `app/src/main/java/org/apache/roller/weblogger/business`
- [JPA persistence](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business/jpa): persistence boundary · JPA-backed managers and ORM-mapped domain state · `app/src/main/java/org/apache/roller/weblogger/business/jpa`
- [Lucene search](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business/search/lucene): indexing subsystem · Indexing and search operations for weblog content · `app/src/main/java/org/apache/roller/weblogger/business/search/lucene`
- [Planet](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/planet): aggregation subsystem · Feed aggregation, subscriptions, and planet rendering · `app/src/main/java/org/apache/roller/planet`
- [Background tasks](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/business/runnable): scheduler/workers · Scheduled jobs, leasing, and worker threads · `app/src/main/java/org/apache/roller/weblogger/business/runnable`
- [Caches](https://github.com/apache/roller/tree/master/app/src/main/java/org/apache/roller/weblogger/util/cache): caching layer · Application and rendering caches · `app/src/main/java/org/apache/roller/weblogger/util/cache`
- [Runtime assets](https://github.com/apache/roller/tree/master/app/src/main/resources): templates/config · Themes, Velocity templates, SQL scripts, i18n, and config resources · `app/src/main/resources`
- [Web assets](https://github.com/apache/roller/tree/master/app/src/main/webapp): web resources · JSPs, static assets, themes, and web.xml runtime resources · `app/src/main/webapp`

### Support

Packaging, tests, docs, and utilities

- **Database**: external dependency · Relational database used for application persistence
- **Servlet container**: external dependency · Host runtime such as Tomcat or similar servlet engine

## Connections

- Root POM → App module: builds · Aggregates the main application module
- Root POM → Release assembly: builds · Includes release packaging
- Root POM → Docs: includes · Carries documentation and examples
- Root POM → Selenium ITs: builds · Runs browser integration tests
- Root POM → DB utils: builds · Provides DB test support utilities
- App module → Web entry: starts at · Servlet and filter entry wiring
- Web entry → Core UI: routes to · Initialization, security, and session filters
- Web entry → Struts2 UI: routes to · Admin/editor Struts2 actions
- Web entry → Rendering: routes to · Public weblog rendering pipeline
- Web entry → Web services: routes to · API endpoints and protocol handlers
- Core UI → Business layer: uses · Delegates to managers and services
- Struts2 UI → Business layer: uses · Admin/editor actions call service layer
- Rendering → Business layer: loads from · Fetches weblog, theme, and content data
- Rendering → Caches: accelerates · Caches pages, feeds, and shared data
- Rendering → Runtime assets: renders with · Velocity templates and theme resources
- Business layer → JPA persistence: persists via · JPA manager implementations back the domain model
- Business layer → Lucene search: indexes via · Updates and queries Lucene indexes
- Business layer → Background tasks: schedules · Background jobs and worker execution
- Business layer → Caches: uses · Business-side caching and warmup
- Business layer → Planet: integrates · Planet aggregation hooks into the core app
- JPA persistence → Database: stores in · Relational persistence backend
- Background tasks → Database: coordinates · Uses locking and scheduled work against stored state
- Web services → Business layer: calls · Protocol handlers delegate into managers
- Web services → Database: reads/writes · API operations ultimately reach persisted state
- App module → Servlet container: deploys to · Packaged as a servlet webapp
- Runtime assets → Web assets: shapes · Templates and runtime assets drive the visible site
- Planet → Runtime assets: uses · Feed and theme configuration resources
