# frappe/press architecture

> Architecture diagram of the GitHub repository frappe/press, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frappe/press
- Repository: https://github.com/frappe/press

## Overview

##### Project Type & Purpose
- Press is a full-stack, multi-tenant cloud hosting platform for the Frappe Framework. It combines a Vue-based dashboard (the “frontend”), a Python/Frappe REST API backend, CLI agents for server communication, and Ansible/Docker/Packer-based infrastructure orchestration.

##### High-Level Architecture Components
A. User & Admin Interfaces
- Dashboard SPA (dashboard/): a Vue 3 single-page app served as static assets.
- Public Website & Docs (press/www/): Flask or Frappe-based webpages.
B. Core Backend
- Press App (press/ + press/saas/): a Frappe Framework application exposing REST API endpoints under /api.
- Authentication, Billing, Marketplace, Multi-tenant logic implemented as Frappe Doctypes & Python controllers.
C. Agents & CLI
- backbone CLI tool (backbone/): a Python CLI to bootstrap servers, run commands against remote “agent” services.
- press agent (press/agent.py): a Flask microservice deployed on each managed server to receive instructions.
D. Infrastructure Orchestration
- Ansible playbooks & roles (press/playbooks/): automate provisioning, configuration, backups, failover, etc.
- Packer templates & scripts (backbone/packer/): build base VM/container images.
- Docker Compose & Dockerfiles (press/docker/): containerize the backend and agent services.
E. Data Stores & Messaging
- MariaDB (Frappe’s primary RDBMS)
- Redis (caching, job queue)
- RQ (Redis-Queue) or Celery for background tasks
F. Supporting Libraries
- filewarmer and mariadb_binlog_indexer (libs/): standalone tools for warm-up and binlog processing.

##### Component Interactions & Data Flows
- 1. User opens Dashboard SPA →
- 2. SPA issues HTTP/HTTPS REST calls to Press Backend API →
- 3. Backend authenticates (JWT/cookie), reads/writes MariaDB, points to Redis for caching/queues →
- 4. For long-running operations (e.g., deploy, backup), backend enqueues jobs in Redis →
- 5. Worker processes (RQ/Celery) pick up jobs, invoke Ansible playbooks via Ansible Controller →
- 6. Ansible connects over SSH (via jump/proxy servers) to managed nodes →
- 7. On each node, the Press Agent receives dispatch commands (HTTP or socket) to perform local tasks (e.g., Docker container restarts, database backups) →
- 8. Agent reports status back to Backend (via its API).

##### Architectural Patterns & Principles
- Layered Architecture: clear separation among Presentation (Vue SPA + public website), Application (Press/Frappe REST API), Infrastructure (Ansible + Agent), Data (RDBMS + Redis).
- Event-Driven/Queue-Based: use Redis/RQ or Celery for background job orchestration.
- Microservices & Agents: core backend and per-node agent communicate over HTTP, isolating responsibilities.
- Infrastructure as Code: Ansible roles/playbooks and Packer templates manage reproducible environments.

- Annotations for frameworks (Vue, Frappe, Flask, Ansible, Docker)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser"]:::external
        DashboardSPA["Dashboard SPA (Vue 3)"]:::frontend
        PublicWebsite["Public Website & Docs"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        PressAPI["Press Backend API (Frappe REST)"]:::backend
        SaaSLayer["Multi-tenant SaaS API"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MariaDB["MariaDB"]:::data
        Redis["Redis (Cache & Queue)"]:::data
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        Workers["RQ/Celery Workers"]:::queue
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        AnsibleController["Ansible Controller"]:::infra
        Agent["Press Agent Service"]:::infra
        ManagedServers["Managed Servers"]:::infra
    end

    %% Tooling
    subgraph "Tooling & CI"
        direction TB
        BackboneCLI["Backbone CLI Tool"]:::infra
        Packer["Packer Templates & Scripts"]:::infra
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        Stripe["Payment Gateway (Stripe, Mpesa)"]:::external
        GitHubAPI["GitHub API"]:::external
        DockerRegistry["Docker Registry"]:::external
    end

    %% Flows
    Browser -->|HTTPS| DashboardSPA
    DashboardSPA -->|HTTPS REST Calls| PressAPI
    Browser -->|HTTP| PublicWebsite

    PressAPI -->|Reads/Writes| MariaDB
    PressAPI -->|Cache| Redis
    PressAPI -->|enqueue job| Redis
    PressAPI -->|HTTP callback| Agent

    Redis -->|jobs| Workers
    Workers -->|invoke playbooks| AnsibleController
    Workers -->|use libs| Filewarmer
    Workers -->|use libs| BinlogIndexer

    BackboneCLI -->|bootstrap/provision| AnsibleController
    Packer -->|build images| AnsibleController
    DockerRegistry -->|pull images| AnsibleController

    AnsibleController -->|SSH/HTTPS| Agent
    Agent -->|manage containers| ManagedServers
    ManagedServers -->|Docker| DockerInfra

    %% External integration calls
    PressAPI -->|process payments| Stripe
    PressAPI -->|fetch apps| GitHubAPI

    %% Click Events
    click DashboardSPA "https://github.com/frappe/press/tree/master/dashboard/"
    click PublicWebsite "https://github.com/frappe/press/tree/master/press/www/"
    click PressAPI "https://github.com/frappe/press/tree/master/press/api/"
    click SaaSLayer "https://github.com/frappe/press/tree/master/press/saas/"
    click BackboneCLI "https://github.com/frappe/press/tree/master/backbone/"
    click Agent "https://github.com/frappe/press/blob/master/press/agent.py"
    click Playbooks "https://github.com/frappe/press/tree/master/press/playbooks/"
    click Packer "https://github.com/frappe/press/tree/master/backbone/packer/"
    click DockerInfra "https://github.com/frappe/press/tree/master/press/docker/"
    click Filewarmer "https://github.com/frappe/press/tree/master/libs/filewarmer/"
    click BinlogIndexer "https://github.com/frappe/press/tree/master/libs/mariadb_binlog_indexer/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef backend fill:#DAFDD6,stroke:#333,stroke-width:1px
    classDef queue fill:#FFE4B2,stroke:#333,stroke-width:1px
    classDef infra fill:#E3D0B5,stroke:#333,stroke-width:1px
    classDef data fill:#E6D0FF,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
