# simple-login/app architecture

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

- Interactive diagram: https://gitdiagram.com/simple-login/app
- Repository: https://github.com/simple-login/app

## Overview

SimpleLogin protects users’ identities with email aliases: users configure aliases and mailboxes through the web app or API, then incoming mail is processed and forwarded through the alias system. The graph also preserves account linking, OAuth, subscription, contact/reverse-alias, and admin capabilities documented or represented in the repository. Relationships are limited to README statements and source-index references or excerpts; unsampled implementation details are not inferred.

Main entry points: [`app/models.py`](https://github.com/simple-login/app/blob/master/app/models.py) (Domain Models), [`app/account_linking.py`](https://github.com/simple-login/app/blob/master/app/account_linking.py) (Account Linking), [`app/alias_utils.py`](https://github.com/simple-login/app/blob/master/app/alias_utils.py) (Alias Management), [`email_handler.py`](https://github.com/simple-login/app/blob/master/email_handler.py) (Mail Ingress)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry Points"]
  node_web["Web App<br/>[server.py]"]
  node_api["User API<br/>[alias.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_dashboard["Dashboard"]
  node_oauth["OAuth Authorization<br/>[authorize.py]"]
end

subgraph group_identity["Identity and Aliases"]
  node_alias["Alias Management<br/>[alias_utils.py]"]
  node_contacts["Reverse Aliases<br/>[contact_utils.py]"]
  node_account_linking["Account Linking<br/>[account_linking.py]"]
end

subgraph group_mail["Email Processing"]
  node_mail_ingress["Mail Ingress<br/>[email_handler.py]"]
  node_email_utils["Email Handling<br/>[email_utils.py]"]
  node_unsubscribe["Unsubscribe Handling"]
  node_mail_sender["Mail Sending<br/>[mail_sender.py]"]
end

subgraph group_accounts["Accounts and Services"]
  node_mailbox["Mailbox Management<br/>[mailbox_utils.py]"]
  node_custom_domains["Custom Domains"]
  node_subscriptions["Subscriptions<br/>[paddle.py]"]
  node_proton["Proton Integration<br/>[proton_client.py]"]
end

subgraph group_platform["Shared Platform"]
  node_models["Domain Models<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
  node_events["Event Dispatch"]
  node_audit["Audit Logs"]
  node_storage["Object Storage<br/>[s3.py]"]
  node_admin["Admin Tools<br/>[index.py]"]
end

node_user(("User"))
node_mail_sender_external(("Remote Mail System"))

node_user -->|"uses web app"| node_web
node_user -->|"uses API"| node_api
node_mail_sender_external -.->|"delivers email"| node_mail_ingress
node_web -.->|"serves dashboard"| node_dashboard
node_api -.->|"manages aliases"| node_alias
node_auth -->|"links accounts"| node_account_linking
node_user -->|"authenticates"| node_auth
node_user -->|"authorizes app"| node_oauth
node_dashboard -->|"manages contacts"| node_contacts
node_mail_ingress -->|"resolves aliases"| node_alias
node_mail_ingress -->|"processes email"| node_email_utils
node_email_utils -->|"sends mail"| node_mail_sender
node_unsubscribe -->|"changes alias status"| node_alias
node_unsubscribe -->|"sends notice"| node_mail_sender
node_alias -->|"uses domain models"| node_models
node_contacts -->|"uses domain models"| node_models
node_account_linking -->|"updates accounts"| node_models
node_account_linking -->|"dispatches events"| node_events
node_account_linking -->|"records activity"| node_audit
node_models -->|"persists records"| node_database
node_mailbox -.->|"manages mailboxes"| node_models
node_custom_domains -.->|"manages domains"| node_models
node_subscriptions -->|"updates plans"| node_models
node_subscriptions -->|"dispatches changes"| node_events
node_proton -->|"links Proton users"| node_account_linking
node_admin -->|"administers records"| node_models
node_models -->|"stores file metadata"| node_storage

click node_web "https://github.com/simple-login/app/blob/master/server.py"
click node_api "https://github.com/simple-login/app/blob/master/app/api/views/alias.py"
click node_auth "https://github.com/simple-login/app/blob/master/app/api/views/auth.py"
click node_dashboard "https://github.com/simple-login/app/blob/master/app/dashboard/views/alias_contact_manager.py"
click node_oauth "https://github.com/simple-login/app/blob/master/app/oauth/views/authorize.py"
click node_alias "https://github.com/simple-login/app/blob/master/app/alias_utils.py"
click node_contacts "https://github.com/simple-login/app/blob/master/app/contact_utils.py"
click node_account_linking "https://github.com/simple-login/app/blob/master/app/account_linking.py"
click node_mail_ingress "https://github.com/simple-login/app/blob/master/email_handler.py"
click node_email_utils "https://github.com/simple-login/app/blob/master/app/email_utils.py"
click node_unsubscribe "https://github.com/simple-login/app/blob/master/app/handler/unsubscribe_handler.py"
click node_mail_sender "https://github.com/simple-login/app/blob/master/app/mail_sender.py"
click node_mailbox "https://github.com/simple-login/app/blob/master/app/mailbox_utils.py"
click node_custom_domains "https://github.com/simple-login/app/blob/master/app/custom_domain_utils.py"
click node_subscriptions "https://github.com/simple-login/app/blob/master/app/payments/paddle.py"
click node_proton "https://github.com/simple-login/app/blob/master/app/proton/proton_client.py"
click node_models "https://github.com/simple-login/app/blob/master/app/models.py"
click node_database "https://github.com/simple-login/app/blob/master/app/db.py"
click node_events "https://github.com/simple-login/app/blob/master/app/events/event_dispatcher.py"
click node_audit "https://github.com/simple-login/app/blob/master/app/user_audit_log_utils.py"
click node_storage "https://github.com/simple-login/app/blob/master/app/s3.py"
click node_admin "https://github.com/simple-login/app/blob/master/app/admin/index.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_web,node_api,node_auth,node_dashboard,node_oauth,node_user toneBlue
class node_alias,node_contacts,node_account_linking toneAmber
class node_mail_ingress,node_email_utils,node_unsubscribe,node_mail_sender toneMint
class node_mailbox,node_custom_domains,node_subscriptions,node_proton toneRose
class node_models,node_database,node_events,node_audit,node_storage,node_admin,node_mail_sender_external toneIndigo
```

## Components

### User Entry Points

- [Web App](https://github.com/simple-login/app/blob/master/server.py): `server.py`
- [User API](https://github.com/simple-login/app/blob/master/app/api/views/alias.py): `app/api/views/alias.py`
- [Authentication](https://github.com/simple-login/app/blob/master/app/api/views/auth.py): `app/api/views/auth.py`
- [Dashboard](https://github.com/simple-login/app/blob/master/app/dashboard/views/alias_contact_manager.py): `app/dashboard/views/alias_contact_manager.py`
- [OAuth Authorization](https://github.com/simple-login/app/blob/master/app/oauth/views/authorize.py): `app/oauth/views/authorize.py`

### Identity and Aliases

- [Alias Management](https://github.com/simple-login/app/blob/master/app/alias_utils.py): `app/alias_utils.py`
- [Reverse Aliases](https://github.com/simple-login/app/blob/master/app/contact_utils.py): `app/contact_utils.py`
- [Account Linking](https://github.com/simple-login/app/blob/master/app/account_linking.py): `app/account_linking.py`

### Email Processing

- [Mail Ingress](https://github.com/simple-login/app/blob/master/email_handler.py): `email_handler.py`
- [Email Handling](https://github.com/simple-login/app/blob/master/app/email_utils.py): `app/email_utils.py`
- [Unsubscribe Handling](https://github.com/simple-login/app/blob/master/app/handler/unsubscribe_handler.py): `app/handler/unsubscribe_handler.py`
- [Mail Sending](https://github.com/simple-login/app/blob/master/app/mail_sender.py): `app/mail_sender.py`

### Accounts and Services

- [Mailbox Management](https://github.com/simple-login/app/blob/master/app/mailbox_utils.py): `app/mailbox_utils.py`
- [Custom Domains](https://github.com/simple-login/app/blob/master/app/custom_domain_utils.py): `app/custom_domain_utils.py`
- [Subscriptions](https://github.com/simple-login/app/blob/master/app/payments/paddle.py): `app/payments/paddle.py`
- [Proton Integration](https://github.com/simple-login/app/blob/master/app/proton/proton_client.py): `app/proton/proton_client.py`

### Shared Platform

- [Domain Models](https://github.com/simple-login/app/blob/master/app/models.py): `app/models.py`
- [PostgreSQL](https://github.com/simple-login/app/blob/master/app/db.py): `app/db.py`
- [Event Dispatch](https://github.com/simple-login/app/blob/master/app/events/event_dispatcher.py): `app/events/event_dispatcher.py`
- [Audit Logs](https://github.com/simple-login/app/blob/master/app/user_audit_log_utils.py): `app/user_audit_log_utils.py`
- [Object Storage](https://github.com/simple-login/app/blob/master/app/s3.py): `app/s3.py`
- [Admin Tools](https://github.com/simple-login/app/blob/master/app/admin/index.py): `app/admin/index.py`

### Other components

- **User**
- **Remote Mail System**

## Connections

- User → Web App: uses web app
- User → User API: uses API
- Remote Mail System → Mail Ingress: delivers email
- Web App → Dashboard: serves dashboard
- User API → Alias Management: manages aliases
- Authentication → Account Linking: links accounts (evidence: `app/account_linking.py`)
- User → Authentication: authenticates (evidence: `app/api/views/auth.py`)
- User → OAuth Authorization: authorizes app (evidence: `app/oauth/views/authorize.py`)
- Dashboard → Reverse Aliases: manages contacts (evidence: `app/dashboard/views/alias_contact_manager.py`)
- Mail Ingress → Alias Management: resolves aliases (evidence: `email_handler.py`)
- Mail Ingress → Email Handling: processes email (evidence: `email_handler.py`)
- Email Handling → Mail Sending: sends mail (evidence: `app/email_utils.py`)
- Unsubscribe Handling → Alias Management: changes alias status (evidence: `app/handler/unsubscribe_handler.py`)
- Unsubscribe Handling → Mail Sending: sends notice (evidence: `app/handler/unsubscribe_handler.py`)
- Alias Management → Domain Models: uses domain models (evidence: `app/alias_utils.py`)
- Reverse Aliases → Domain Models: uses domain models (evidence: `app/contact_utils.py`)
- Account Linking → Domain Models: updates accounts (evidence: `app/account_linking.py`)
- Account Linking → Event Dispatch: dispatches events (evidence: `app/account_linking.py`)
- Account Linking → Audit Logs: records activity (evidence: `app/account_linking.py`)
- Domain Models → PostgreSQL: persists records (evidence: `app/models.py`)
- Mailbox Management → Domain Models: manages mailboxes (evidence: `app/models.py`)
- Custom Domains → Domain Models: manages domains (evidence: `app/models.py`)
- Subscriptions → Domain Models: updates plans (evidence: `app/payments/paddle.py`)
- Subscriptions → Event Dispatch: dispatches changes
- Proton Integration → Account Linking: links Proton users (evidence: `app/proton/proton_client.py`)
- Admin Tools → Domain Models: administers records (evidence: `app/admin/index.py`)
- Domain Models → Object Storage: stores file metadata (evidence: `app/models.py`)
