# roundcube/roundcubemail architecture

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

- Interactive diagram: https://gitdiagram.com/roundcube/roundcubemail
- Repository: https://github.com/roundcube/roundcubemail

## Overview

#### Purpose

Roundcube Webmail is a PHP/JavaScript browser-based, multilingual IMAP client. It provides mail handling, MIME rendering, address books, folder management, searching, spell checking, and a customizable UI. The application requires a MariaDB/MySQL, PostgreSQL, or SQLite database and uses external libraries.

#### Public entry points

- `public_html/index.php` and `index.php` are web application front doors for deployments with different document-root layouts.
- `installer/index.php` provides the installation interface.
- `bin` contains administrative and maintenance command-line scripts, including database initialization/update, import/export, health checks, and installation helpers.
- `public_html/static.php` is a public static-resource entry point.

#### Core components

- **Request actions** — `program/actions`: Mail, contacts, login, settings, and utility action handlers. The directory structure exposes the application’s main user-facing operation areas.
- **Application orchestration** — `program/include`: Request setup, output handling, attachments, OAuth, mail sending, health checks, installation, and shared application utilities.
- **Core framework and protocol/data services** — `program/lib/Roundcube`: IMAP, SMTP, MIME/message processing, users, sessions, caching, databases, address books, spell checking, HTML filtering, and related framework services.
- **Browser client** — `program/js`: JavaScript application behavior, editing, lists, navigation, and shared browser utilities.
- **Configuration and runtime defaults** — `config`: Deployment configuration, defaults, MIME definitions, and web-server access protection.
- **Database schemas and upgrades** — `SQL`: Initial schemas and timestamped migrations for MySQL, PostgreSQL, and SQLite.
- **Theme/UI customization** — `skins/elastic`: Templates, JavaScript, styles, fonts, and images for the bundled Elastic interface.
- **Extension system and bundled extensions** — `plugins`: Plugin entry points, optional drivers, client assets, localization, and plugin-specific UI resources. The README identifies the plugin API as the primary extension mechanism.

#### Relationships

Browser traffic enters through the public PHP front doors and is handled by the application/action areas under `program/actions` and `program/include`. Those areas own mail, contacts, authentication, and settings operations while the framework under `program/lib/Roundcube` supplies shared protocol, message, session, cache, storage, and rendering services.

The framework’s mail-facing areas form the repository boundary to external IMAP and SMTP services; the database areas form the boundary to the configured SQL backend. `SQL` supplies the persistent schema and upgrade data consumed by deployment and maintenance operations.

The core UI uses `program/js` together with a selected skin such as `skins/elastic`. Bundled plugins remain optional integrations around the core and may add server behavior, browser assets, localization, drivers, or templates through the plugin API. Exact dispatch order and source-level dependency details are not established by the supplied tree and README.

Main entry points: [`program/lib/Roundcube`](https://github.com/roundcube/roundcubemail/tree/master/program/lib/Roundcube) (Framework and protocol services), [`program/actions`](https://github.com/roundcube/roundcubemail/tree/master/program/actions) (Request actions), [`public_html/index.php`](https://github.com/roundcube/roundcubemail/blob/master/public_html/index.php) (Web front doors), [`plugins`](https://github.com/roundcube/roundcubemail/tree/master/plugins) (Bundled plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_core["Roundcube application"]
  node_n_front["Web front doors<br/>PHP entry points<br/>[index.php]"]
  node_n_actions["Request actions<br/>PHP action handlers"]
  node_n_include["Application orchestration<br/>PHP application layer"]
  node_n_framework["Framework and protocol services<br/>PHP framework"]
  node_n_browser["Browser client<br/>JavaScript client"]
  node_n_skin["Elastic skin<br/>UI theme"]
  node_n_config["Configuration"]
  node_n_sql[("Database schemas<br/>SQL schema and migrations")]
  node_n_bin["Maintenance commands<br/>CLI scripts"]
end

subgraph group_g_ext["Optional extensions"]
  node_n_plugins{{"Bundled plugins<br/>Plugin extensions"}}
end

node_n_imap[("IMAP service<br/>External mail system")]
node_n_smtp[("SMTP service<br/>External mail system")]
node_n_db[("SQL backend<br/>External database")]

node_n_front -->|"handles traffic"| node_n_actions
node_n_front -->|"initializes requests"| node_n_include
node_n_actions -->|"uses services"| node_n_framework
node_n_include -->|"uses services"| node_n_framework
node_n_framework -->|"connects to"| node_n_imap
node_n_framework -->|"connects to"| node_n_smtp
node_n_framework -->|"stores data"| node_n_db
node_n_sql -->|"defines schema"| node_n_db
node_n_bin -->|"applies upgrades"| node_n_sql
node_n_browser -->|"uses theme"| node_n_skin
node_n_plugins -.->|"extends"| node_n_actions
node_n_plugins -.->|"extends"| node_n_framework

click node_n_front "https://github.com/roundcube/roundcubemail/blob/master/public_html/index.php"
click node_n_actions "https://github.com/roundcube/roundcubemail/tree/master/program/actions"
click node_n_include "https://github.com/roundcube/roundcubemail/tree/master/program/include"
click node_n_framework "https://github.com/roundcube/roundcubemail/tree/master/program/lib/Roundcube"
click node_n_browser "https://github.com/roundcube/roundcubemail/tree/master/program/js"
click node_n_skin "https://github.com/roundcube/roundcubemail/tree/master/skins/elastic"
click node_n_config "https://github.com/roundcube/roundcubemail/tree/master/config"
click node_n_sql "https://github.com/roundcube/roundcubemail/tree/master/SQL"
click node_n_bin "https://github.com/roundcube/roundcubemail/tree/master/bin"
click node_n_plugins "https://github.com/roundcube/roundcubemail/tree/master/plugins"

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_n_front,node_n_actions,node_n_include,node_n_framework,node_n_browser,node_n_skin,node_n_config,node_n_sql,node_n_bin toneBlue
class node_n_plugins toneAmber
class node_n_imap,node_n_smtp,node_n_db toneNeutral
```

## Components

### Roundcube application

Core browser-based mail application.

- [Web front doors](https://github.com/roundcube/roundcubemail/blob/master/public_html/index.php): PHP entry points · Receives browser traffic for deployed document-root layouts. · `public_html/index.php`
- [Request actions](https://github.com/roundcube/roundcubemail/tree/master/program/actions): PHP action handlers · Handles mail, contacts, login, settings, and utility operations. · `program/actions`
- [Application orchestration](https://github.com/roundcube/roundcubemail/tree/master/program/include): PHP application layer · Provides request setup, output handling, mail sending, OAuth, and shared utilities. · `program/include`
- [Framework and protocol services](https://github.com/roundcube/roundcubemail/tree/master/program/lib/Roundcube): PHP framework · Provides IMAP, SMTP, MIME, sessions, caching, databases, address books, and rendering services. · `program/lib/Roundcube`
- [Browser client](https://github.com/roundcube/roundcubemail/tree/master/program/js): JavaScript client · Provides browser application behavior, editing, lists, navigation, and shared utilities. · `program/js`
- [Elastic skin](https://github.com/roundcube/roundcubemail/tree/master/skins/elastic): UI theme · Provides templates, client assets, styles, fonts, and images. · `skins/elastic`
- [Configuration](https://github.com/roundcube/roundcubemail/tree/master/config): Runtime configuration · Provides deployment configuration and runtime defaults. · `config`
- [Database schemas](https://github.com/roundcube/roundcubemail/tree/master/SQL): SQL schema and migrations · Provides initial schemas and timestamped upgrades for supported databases. · `SQL`
- [Maintenance commands](https://github.com/roundcube/roundcubemail/tree/master/bin): CLI scripts · Provides database, health, import/export, and installation operations. · `bin`

### Optional extensions

Plugin-based extensions around the core.

- [Bundled plugins](https://github.com/roundcube/roundcubemail/tree/master/plugins): Plugin extensions · Uses the plugin API for optional server behavior, assets, localization, drivers, and UI resources. · `plugins`

### Other components

- **IMAP service**: External mail system · External mail service reached through the framework's mail-facing areas.
- **SMTP service**: External mail system · External mail service reached through the framework's mail-facing areas.
- **SQL backend**: External database · Configured MariaDB/MySQL, PostgreSQL, or SQLite backend.

## Connections

- Web front doors → Request actions: handles traffic
- Web front doors → Application orchestration: initializes requests
- Request actions → Framework and protocol services: uses services
- Application orchestration → Framework and protocol services: uses services
- Framework and protocol services → IMAP service: connects to
- Framework and protocol services → SMTP service: connects to
- Framework and protocol services → SQL backend: stores data
- Database schemas → SQL backend: defines schema
- Maintenance commands → Database schemas: applies upgrades
- Browser client → Elastic skin: uses theme
- Bundled plugins → Request actions: extends
- Bundled plugins → Framework and protocol services: extends
