# apache/james-project architecture

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

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

## Overview

Apache James is a modular JVM mail-server platform. Users connect through mail protocols; the server exposes mailbox operations, applies configurable mail-treatment rules, and stores messages and related state using selectable backends. The tree also shows search, quota, event delivery, background tasks, backup, and recovery capabilities. The graph preserves these major product areas, but the sampled sources do not expose protocol-to-mailbox routing or most subsystem wiring, so those relationships are omitted rather than inferred.

Main entry points: [`mailbox/store/src/main/java/org/apache/james/mailbox/store/StoreMailboxManager.java`](https://github.com/apache/james-project/blob/master/mailbox/store/src/main/java/org/apache/james/mailbox/store/StoreMailboxManager.java) (Mailbox stores), [`mailbox/api/src/main/java/org/apache/james/mailbox/MessageManager.java`](https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/MessageManager.java) (Mailbox API), [`server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java`](https://github.com/apache/james-project/blob/master/server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java) (S3 recovery), [`protocols`](https://github.com/apache/james-project/tree/master/protocols) (Mail protocols)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mail["Mail handling"]
  node_protocols["Mail protocols"]
  node_mailbox_api["Mailbox API"]
  node_mail_treatment["Mailet treatment"]
end

subgraph group_state["Mailbox and data"]
  node_mailbox_model["Mailbox model<br/>[Mailbox.java]"]
  node_identity["User identity<br/>[Username.java]"]
  node_users["Users repository"]
  node_mailbox_storage[("Mailbox stores")]
  node_quota["Quota management"]
  node_search["Message search"]
end

subgraph group_platform["Platform services"]
  node_event_bus["Event bus<br/>[EventBus.java]"]
  node_event_delivery["Distributed delivery"]
  node_task_manager["Task manager<br/>[TaskManager.java]"]
  node_health["Health checks<br/>[Result.java]"]
end

subgraph group_operations["Operations"]
  node_backup["Mailbox backup"]
  node_recovery["S3 recovery"]
end

subgraph group_integrations["Storage integrations"]
  node_cassandra[("Cassandra backend")]
  node_postgres[("Postgres backend")]
  node_opensearch[("OpenSearch backend")]
  node_rabbitmq["RabbitMQ backend"]
  node_s3[("S3 object storage<br/>[BlobStore.java]")]
end

node_clients(("Mail clients"))

node_clients -->|"connects through"| node_protocols
node_protocols -.->|"serves mail operations"| node_mailbox_api
node_mailbox_api -.->|"applies directives"| node_mail_treatment
node_mail_treatment -.->|"guides storage"| node_mailbox_storage
node_mailbox_storage -.->|"stores mailboxes"| node_mailbox_model
node_mailbox_api -.->|"uses user identity"| node_identity
node_users -.->|"indexes users"| node_identity
node_mailbox_storage -.->|"persists with"| node_cassandra
node_mailbox_storage -.->|"persists with"| node_postgres
node_mailbox_storage -.->|"supports quota"| node_quota
node_mailbox_storage -.->|"supports search"| node_search
node_mailbox_api -.->|"publishes events"| node_event_bus
node_event_bus -.->|"dispatches events"| node_event_delivery
node_task_manager -.->|"runs recovery task"| node_recovery
node_backup -->|"archives messages"| node_mailbox_model
node_recovery -->|"restores mail"| node_mailbox_api
node_recovery -->|"reads blobs"| node_s3
node_search -.->|"queries index"| node_opensearch
node_event_delivery -.->|"uses broker"| node_rabbitmq
node_cassandra -.->|"reports health"| node_health
node_postgres -.->|"reports health"| node_health

click node_protocols "https://github.com/apache/james-project/tree/master/protocols"
click node_mailbox_api "https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/MessageManager.java"
click node_mail_treatment "https://github.com/apache/james-project/blob/master/mailet/api/src/main/java/org/apache/mailet/StorageDirective.java"
click node_mailbox_model "https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/model/Mailbox.java"
click node_identity "https://github.com/apache/james-project/blob/master/core/src/main/java/org/apache/james/core/Username.java"
click node_users "https://github.com/apache/james-project/blob/master/server/data/data-api/src/main/java/org/apache/james/user/api/UsersRepository.java"
click node_mailbox_storage "https://github.com/apache/james-project/blob/master/mailbox/store/src/main/java/org/apache/james/mailbox/store/StoreMailboxManager.java"
click node_quota "https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/quota/MaxQuotaManager.java"
click node_search "https://github.com/apache/james-project/blob/master/mailbox/opensearch/src/main/java/org/apache/james/mailbox/opensearch/query/QueryConverter.java"
click node_event_bus "https://github.com/apache/james-project/blob/master/event-bus/api/src/main/java/org/apache/james/events/EventBus.java"
click node_event_delivery "https://github.com/apache/james-project/blob/master/event-bus/distributed/src/main/java/org/apache/james/events/RabbitMQEventBus.java"
click node_task_manager "https://github.com/apache/james-project/blob/master/server/task/task-api/src/main/java/org/apache/james/task/TaskManager.java"
click node_health "https://github.com/apache/james-project/blob/master/core/src/main/java/org/apache/james/core/healthcheck/Result.java"
click node_backup "https://github.com/apache/james-project/blob/master/mailbox/backup/src/main/java/org/apache/james/mailbox/backup/ArchiveService.java"
click node_recovery "https://github.com/apache/james-project/blob/master/server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java"
click node_cassandra "https://github.com/apache/james-project/blob/master/backends-common/cassandra/src/main/java/org/apache/james/backends/cassandra/components/CassandraDataDefinition.java"
click node_postgres "https://github.com/apache/james-project/blob/master/backends-common/postgres/src/main/java/org/apache/james/backends/postgres/PostgresDataDefinition.java"
click node_opensearch "https://github.com/apache/james-project/blob/master/backends-common/opensearch/src/main/java/org/apache/james/backends/opensearch/OpenSearchIndexer.java"
click node_rabbitmq "https://github.com/apache/james-project/blob/master/backends-common/rabbitmq/src/main/java/org/apache/james/backends/rabbitmq/RabbitMQConnectionFactory.java"
click node_s3 "https://github.com/apache/james-project/blob/master/server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java"

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_protocols,node_mailbox_api,node_mail_treatment,node_clients toneBlue
class node_mailbox_model,node_identity,node_users,node_mailbox_storage,node_quota,node_search toneAmber
class node_event_bus,node_event_delivery,node_task_manager,node_health toneMint
class node_backup,node_recovery toneRose
class node_cassandra,node_postgres,node_opensearch,node_rabbitmq,node_s3 toneIndigo
```

## Components

### Mail handling

- [Mail protocols](https://github.com/apache/james-project/tree/master/protocols): `protocols`
- [Mailbox API](https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/MessageManager.java): `mailbox/api/src/main/java/org/apache/james/mailbox/MessageManager.java`
- [Mailet treatment](https://github.com/apache/james-project/blob/master/mailet/api/src/main/java/org/apache/mailet/StorageDirective.java): `mailet/api/src/main/java/org/apache/mailet/StorageDirective.java`

### Mailbox and data

- [Mailbox model](https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/model/Mailbox.java): `mailbox/api/src/main/java/org/apache/james/mailbox/model/Mailbox.java`
- [User identity](https://github.com/apache/james-project/blob/master/core/src/main/java/org/apache/james/core/Username.java): `core/src/main/java/org/apache/james/core/Username.java`
- [Users repository](https://github.com/apache/james-project/blob/master/server/data/data-api/src/main/java/org/apache/james/user/api/UsersRepository.java): `server/data/data-api/src/main/java/org/apache/james/user/api/UsersRepository.java`
- [Mailbox stores](https://github.com/apache/james-project/blob/master/mailbox/store/src/main/java/org/apache/james/mailbox/store/StoreMailboxManager.java): `mailbox/store/src/main/java/org/apache/james/mailbox/store/StoreMailboxManager.java`
- [Quota management](https://github.com/apache/james-project/blob/master/mailbox/api/src/main/java/org/apache/james/mailbox/quota/MaxQuotaManager.java): `mailbox/api/src/main/java/org/apache/james/mailbox/quota/MaxQuotaManager.java`
- [Message search](https://github.com/apache/james-project/blob/master/mailbox/opensearch/src/main/java/org/apache/james/mailbox/opensearch/query/QueryConverter.java): `mailbox/opensearch/src/main/java/org/apache/james/mailbox/opensearch/query/QueryConverter.java`

### Platform services

- [Event bus](https://github.com/apache/james-project/blob/master/event-bus/api/src/main/java/org/apache/james/events/EventBus.java): `event-bus/api/src/main/java/org/apache/james/events/EventBus.java`
- [Distributed delivery](https://github.com/apache/james-project/blob/master/event-bus/distributed/src/main/java/org/apache/james/events/RabbitMQEventBus.java): `event-bus/distributed/src/main/java/org/apache/james/events/RabbitMQEventBus.java`
- [Task manager](https://github.com/apache/james-project/blob/master/server/task/task-api/src/main/java/org/apache/james/task/TaskManager.java): `server/task/task-api/src/main/java/org/apache/james/task/TaskManager.java`
- [Health checks](https://github.com/apache/james-project/blob/master/core/src/main/java/org/apache/james/core/healthcheck/Result.java): `core/src/main/java/org/apache/james/core/healthcheck/Result.java`

### Operations

- [Mailbox backup](https://github.com/apache/james-project/blob/master/mailbox/backup/src/main/java/org/apache/james/mailbox/backup/ArchiveService.java): `mailbox/backup/src/main/java/org/apache/james/mailbox/backup/ArchiveService.java`
- [S3 recovery](https://github.com/apache/james-project/blob/master/server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java): `server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java`

### Storage integrations

- [Cassandra backend](https://github.com/apache/james-project/blob/master/backends-common/cassandra/src/main/java/org/apache/james/backends/cassandra/components/CassandraDataDefinition.java): `backends-common/cassandra/src/main/java/org/apache/james/backends/cassandra/components/CassandraDataDefinition.java`
- [Postgres backend](https://github.com/apache/james-project/blob/master/backends-common/postgres/src/main/java/org/apache/james/backends/postgres/PostgresDataDefinition.java): `backends-common/postgres/src/main/java/org/apache/james/backends/postgres/PostgresDataDefinition.java`
- [OpenSearch backend](https://github.com/apache/james-project/blob/master/backends-common/opensearch/src/main/java/org/apache/james/backends/opensearch/OpenSearchIndexer.java): `backends-common/opensearch/src/main/java/org/apache/james/backends/opensearch/OpenSearchIndexer.java`
- [RabbitMQ backend](https://github.com/apache/james-project/blob/master/backends-common/rabbitmq/src/main/java/org/apache/james/backends/rabbitmq/RabbitMQConnectionFactory.java): `backends-common/rabbitmq/src/main/java/org/apache/james/backends/rabbitmq/RabbitMQConnectionFactory.java`
- [S3 object storage](https://github.com/apache/james-project/blob/master/server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java): `server/blob/blob-api/src/main/java/org/apache/james/blob/api/BlobStore.java`

### Other components

- **Mail clients**

## Connections

- Mail clients → Mail protocols: connects through
- Mail protocols → Mailbox API: serves mail operations
- Mailbox API → Mailet treatment: applies directives
- Mailet treatment → Mailbox stores: guides storage
- Mailbox stores → Mailbox model: stores mailboxes (evidence: `mailbox/store/src/main/java/org/apache/james/mailbox/store/StoreMailboxManager.java`)
- Mailbox API → User identity: uses user identity
- Users repository → User identity: indexes users (evidence: `server/data/data-api/src/main/java/org/apache/james/user/api/UsersRepository.java`)
- Mailbox stores → Cassandra backend: persists with
- Mailbox stores → Postgres backend: persists with
- Mailbox stores → Quota management: supports quota
- Mailbox stores → Message search: supports search
- Mailbox API → Event bus: publishes events
- Event bus → Distributed delivery: dispatches events
- Task manager → S3 recovery: runs recovery task
- Mailbox backup → Mailbox model: archives messages (evidence: `mailbox/backup/src/main/java/org/apache/james/mailbox/backup/ArchiveService.java`)
- S3 recovery → Mailbox API: restores mail (evidence: `server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java`)
- S3 recovery → S3 object storage: reads blobs (evidence: `server/apps/distributed-app/src/main/java/org/apache/james/S3RecoveryService.java`)
- Message search → OpenSearch backend: queries index
- Distributed delivery → RabbitMQ backend: uses broker
- Cassandra backend → Health checks: reports health
- Postgres backend → Health checks: reports health
