Skip to content

Architecture and Security

Jump to bottom
Tyler Hatfield edited this page Jul 13, 2026 · 1 revision

Architecture & Security

PolyPress is built around a secure multitenant workspace model, utilizing a dual SQLite database structure and robust authentication protocols.

🗄️ Database & Storage Engine

PolyPress stores data in two zero-configuration SQLite databases located in the data/ directory:

  • polypress.db: Houses active data including tenant tables, users, lists, campaigns, templates, subscriber records, and automation pathways.
  • polypress_history.db: Stores historical analytical events (subscriber signups, click tracking, open activities, bounce trends) to keep main database operations fast.

Schema Reconciliation

Upon startup, the FastAPI initialization layer inspects database structures. It automatically performs ALTER TABLE operations to append new columns (such as schema updates and custom fields) without causing data loss.

🏢 Multitenancy & Workspace Scopes

Data in PolyPress is partitioned by tenant workspaces. Administrators can configure:

  • Allowed Whitelist Domains: Limit registration to specific email domains (e.g. yourcompany.com).
  • Auto-Create Tenants: Automatically spin up a separate company tenant workspace when a new user from an allowed email domain logs in.
  • Host Diagnostics: Configure host-wide server identities, sending IP overrides, and custom branding logo paths.

🔐 Global OIDC Single Sign-On (SSO)

You can delegate authentication to any OpenID Connect (OIDC) provider (such as Authentik, Keycloak, or Okta):

  1. Navigate to Global Admin in the sidebar.
  2. Enable OIDC login and configure provider credentials (issuer URI, Client ID, Client Secret, and redirect URLs).
  3. Define custom JSON path claim mappings for roles and tenant scopes (e.g., mapping mapping roles to custom fields on the OIDC user token).

💾 Backups, Security, and API Tokens

Backup Security

PolyPress generates portable ZIP archives containing database files and branding assets. To query or pull these archives programmatically, developers use a secure, rotatable API token.

# Example secure pull using Backup API token
curl -L -G 'https://yourdomain.com/api/admin/backups/export' \
  --data-urlencode 'token=pp_backup_tok_xyz123' \
  -o polypress_backup.zip

Auto-Backup Schedules

Configure scheduled automated backups through the host admin panel:

  • Backup Interval: The cycle frequency (in hours) to generate backup archives.
  • Retention Limit: The maximum count of archive ZIP files to preserve locally before cleaning up older backups.

Clone this wiki locally