# mailcow/cow-app architecture

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

- Interactive diagram: https://gitdiagram.com/mailcow/cow-app
- Repository: https://github.com/mailcow/cow-app

## Overview

Mailcow App is the Flask backend for the CowUI interface. A browser request reaches registered API or authentication resources; those handlers validate and process account, credential, and settings operations, persist application state, and—in account or mail-feature paths—delegate to the sync engine or Sieve service. The sampled code shows these handler and integration boundaries, but not every route implementation or the full database configuration, so unsampled relationships are omitted rather than inferred.

Main entry points: [`app/api/views.py`](https://github.com/mailcow/cow-app/blob/master/app/api/views.py) (API handlers), [`app/auth/utils.py`](https://github.com/mailcow/cow-app/blob/master/app/auth/utils.py) (Account and token logic), [`app/__init__.py`](https://github.com/mailcow/cow-app/blob/master/app/__init__.py) (App bootstrap), [`app/auth/views.py`](https://github.com/mailcow/cow-app/blob/master/app/auth/views.py) (Auth handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_server["Flask server<br/>[server.py]"]
  node_app_init["App bootstrap<br/>[__init__.py]"]
  node_logger["Validation logger<br/>[logger.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_api["CowUI API"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_api_views["API handlers<br/>[views.py]"]
  node_api_models[("Users and settings<br/>[models.py]")]
  node_api_exceptions["API errors<br/>[exceptions.py]"]
  node_validation["Request validation<br/>[validate.py]"]
  node_settings_schema["Settings schema<br/>[settings.py]"]
  node_http_utils["HTTP responses<br/>[httputils.py]"]
end

subgraph group_auth["Authentication and accounts"]
  node_auth_routes["Auth routes<br/>[routes.py]"]
  node_auth_views["Auth handlers<br/>[views.py]"]
  node_auth_utils["Account and token logic<br/>[utils.py]"]
  node_auth_models[("Token model<br/>[models.py]")]
  node_auth_exceptions["Auth errors<br/>[exceptions.py]"]
end

subgraph group_mail["Mail settings"]
  node_api_utils["Mail settings logic<br/>[utils.py]"]
  node_sieve_template["Sieve renderer<br/>[template.py]"]
  node_sieve_file["CowUI Sieve template<br/>[cowui.sieve]"]
end

subgraph group_integrations["External services"]
  node_sync_services["Sync account service<br/>[services.py]"]
  node_sync_engine["Sync engine"]
  node_mail_server["IMAP and SMTP"]
  node_sieve_service["ManageSieve server"]
end

node_browser(("Browser user"))

node_browser -->|"sends requests"| node_server
node_server -->|"runs app"| node_app_init
node_app_init -->|"loads config"| node_config
node_app_init -->|"registers routes"| node_api_routes
node_app_init -->|"registers routes"| node_auth_routes
node_app_init -->|"configures errors"| node_api_exceptions
node_api_routes -->|"routes requests"| node_api_views
node_auth_routes -->|"routes requests"| node_auth_views
node_api_views -->|"queries and updates"| node_api_models
node_api_views -->|"validates settings"| node_validation
node_validation -->|"loads schema"| node_settings_schema
node_api_views -->|"builds responses"| node_http_utils
node_api_views -->|"calls account logic"| node_auth_utils
node_api_views -->|"uses mail utilities"| node_api_utils
node_auth_views -->|"calls auth logic"| node_auth_utils
node_auth_views -->|"queries users"| node_api_models
node_auth_utils -->|"updates records"| node_api_models
node_auth_utils -->|"stores tokens"| node_auth_models
node_auth_utils -->|"handles token errors"| node_auth_exceptions
node_auth_utils -->|"delegates account sync"| node_sync_services
node_sync_services -->|"calls account API"| node_sync_engine
node_api_views -->|"proxies API calls"| node_sync_engine
node_validation -->|"logs validation"| node_logger
node_api_utils -->|"renders template"| node_sieve_template
node_api_utils -->|"loads template"| node_sieve_file
node_api_utils -->|"updates scripts"| node_sieve_service
node_auth_views -.->|"checks credentials"| node_mail_server

click node_server "https://github.com/mailcow/cow-app/blob/master/server.py"
click node_app_init "https://github.com/mailcow/cow-app/blob/master/app/__init__.py"
click node_api_routes "https://github.com/mailcow/cow-app/blob/master/app/api/routes.py"
click node_api_views "https://github.com/mailcow/cow-app/blob/master/app/api/views.py"
click node_api_models "https://github.com/mailcow/cow-app/blob/master/app/api/models.py"
click node_api_exceptions "https://github.com/mailcow/cow-app/blob/master/app/api/exceptions.py"
click node_validation "https://github.com/mailcow/cow-app/blob/master/app/api/validation/validate.py"
click node_settings_schema "https://github.com/mailcow/cow-app/blob/master/app/api/validation/schemas/settings.py"
click node_http_utils "https://github.com/mailcow/cow-app/blob/master/app/httputils.py"
click node_auth_routes "https://github.com/mailcow/cow-app/blob/master/app/auth/routes.py"
click node_auth_views "https://github.com/mailcow/cow-app/blob/master/app/auth/views.py"
click node_auth_utils "https://github.com/mailcow/cow-app/blob/master/app/auth/utils.py"
click node_auth_models "https://github.com/mailcow/cow-app/blob/master/app/auth/models.py"
click node_auth_exceptions "https://github.com/mailcow/cow-app/blob/master/app/auth/exceptions.py"
click node_sync_services "https://github.com/mailcow/cow-app/blob/master/app/auth/services.py"
click node_api_utils "https://github.com/mailcow/cow-app/blob/master/app/api/utils.py"
click node_sieve_template "https://github.com/mailcow/cow-app/blob/master/app/sieve_templates/template.py"
click node_sieve_file "https://github.com/mailcow/cow-app/blob/master/app/sieve_templates/cowui.sieve"
click node_logger "https://github.com/mailcow/cow-app/blob/master/app/logger.py"
click node_config "https://github.com/mailcow/cow-app/blob/master/config.py"

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_server,node_app_init,node_logger,node_config,node_browser toneBlue
class node_api_routes,node_api_views,node_api_models,node_api_exceptions,node_validation,node_settings_schema,node_http_utils toneAmber
class node_auth_routes,node_auth_views,node_auth_utils,node_auth_models,node_auth_exceptions toneMint
class node_api_utils,node_sieve_template,node_sieve_file toneRose
class node_sync_services,node_sync_engine,node_mail_server,node_sieve_service toneIndigo
```

## Components

### Application runtime

- [Flask server](https://github.com/mailcow/cow-app/blob/master/server.py): `server.py`
- [App bootstrap](https://github.com/mailcow/cow-app/blob/master/app/__init__.py): `app/__init__.py`
- [Validation logger](https://github.com/mailcow/cow-app/blob/master/app/logger.py): `app/logger.py`
- [Runtime config](https://github.com/mailcow/cow-app/blob/master/config.py): `config.py`

### CowUI API

- [API routes](https://github.com/mailcow/cow-app/blob/master/app/api/routes.py): `app/api/routes.py`
- [API handlers](https://github.com/mailcow/cow-app/blob/master/app/api/views.py): `app/api/views.py`
- [Users and settings](https://github.com/mailcow/cow-app/blob/master/app/api/models.py): `app/api/models.py`
- [API errors](https://github.com/mailcow/cow-app/blob/master/app/api/exceptions.py): `app/api/exceptions.py`
- [Request validation](https://github.com/mailcow/cow-app/blob/master/app/api/validation/validate.py): `app/api/validation/validate.py`
- [Settings schema](https://github.com/mailcow/cow-app/blob/master/app/api/validation/schemas/settings.py): `app/api/validation/schemas/settings.py`
- [HTTP responses](https://github.com/mailcow/cow-app/blob/master/app/httputils.py): `app/httputils.py`

### Authentication and accounts

- [Auth routes](https://github.com/mailcow/cow-app/blob/master/app/auth/routes.py): `app/auth/routes.py`
- [Auth handlers](https://github.com/mailcow/cow-app/blob/master/app/auth/views.py): `app/auth/views.py`
- [Account and token logic](https://github.com/mailcow/cow-app/blob/master/app/auth/utils.py): `app/auth/utils.py`
- [Token model](https://github.com/mailcow/cow-app/blob/master/app/auth/models.py): `app/auth/models.py`
- [Auth errors](https://github.com/mailcow/cow-app/blob/master/app/auth/exceptions.py): `app/auth/exceptions.py`

### Mail settings

- [Mail settings logic](https://github.com/mailcow/cow-app/blob/master/app/api/utils.py): `app/api/utils.py`
- [Sieve renderer](https://github.com/mailcow/cow-app/blob/master/app/sieve_templates/template.py): `app/sieve_templates/template.py`
- [CowUI Sieve template](https://github.com/mailcow/cow-app/blob/master/app/sieve_templates/cowui.sieve): `app/sieve_templates/cowui.sieve`

### External services

- [Sync account service](https://github.com/mailcow/cow-app/blob/master/app/auth/services.py): `app/auth/services.py`
- **Sync engine**
- **IMAP and SMTP**
- **ManageSieve server**

### Other components

- **Browser user**

## Connections

- Browser user → Flask server: sends requests (evidence: `README.md`)
- Flask server → App bootstrap: runs app (evidence: `server.py`)
- App bootstrap → Runtime config: loads config (evidence: `app/__init__.py`)
- App bootstrap → API routes: registers routes (evidence: `app/__init__.py`)
- App bootstrap → Auth routes: registers routes (evidence: `app/__init__.py`)
- App bootstrap → API errors: configures errors (evidence: `app/__init__.py`)
- API routes → API handlers: routes requests (evidence: `app/api/routes.py`)
- Auth routes → Auth handlers: routes requests (evidence: `app/auth/routes.py`)
- API handlers → Users and settings: queries and updates (evidence: `app/api/views.py`)
- API handlers → Request validation: validates settings (evidence: `app/api/views.py`)
- Request validation → Settings schema: loads schema (evidence: `app/api/validation/validate.py`)
- API handlers → HTTP responses: builds responses (evidence: `app/api/views.py`)
- API handlers → Account and token logic: calls account logic (evidence: `app/api/views.py`)
- API handlers → Mail settings logic: uses mail utilities (evidence: `app/api/views.py`)
- Auth handlers → Account and token logic: calls auth logic (evidence: `app/auth/views.py`)
- Auth handlers → Users and settings: queries users (evidence: `app/auth/views.py`)
- Account and token logic → Users and settings: updates records (evidence: `app/auth/utils.py`)
- Account and token logic → Token model: stores tokens (evidence: `app/auth/utils.py`)
- Account and token logic → Auth errors: handles token errors (evidence: `app/auth/utils.py`)
- Account and token logic → Sync account service: delegates account sync (evidence: `app/auth/utils.py`)
- Sync account service → Sync engine: calls account API (evidence: `app/auth/services.py`)
- API handlers → Sync engine: proxies API calls (evidence: `app/api/views.py`)
- Request validation → Validation logger: logs validation (evidence: `app/api/validation/validate.py`)
- Mail settings logic → Sieve renderer: renders template (evidence: `app/api/utils.py`)
- Mail settings logic → CowUI Sieve template: loads template (evidence: `app/api/utils.py`)
- Mail settings logic → ManageSieve server: updates scripts (evidence: `app/api/utils.py`)
- Auth handlers → IMAP and SMTP: checks credentials