# drdroidlab/playbooks architecture

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

- Interactive diagram: https://gitdiagram.com/drdroidlab/playbooks
- Repository: https://github.com/drdroidlab/playbooks

## Overview

##### Main Components
- Frontend Client: Represented by the “web” folder. This React/Vite based web interface is used to configure PlayBooks, view alerts, and interact with the system.
- Backend/API Layer: The central orchestration is provided by multiple Django apps (such as “accounts”, “playbooks”, “management”, “media”, “connectors”, “executor”, “engines”, etc.). Each module manages distinct aspects:
– Accounts and Authentication: Handles admin, user management, sessions, and API security.
– Playbooks: Manages the creation, storage, and execution of investigation documents.
– Connectors: Provides integrations with 15+ external observability tools and servers.
– Executor and Engines: Manages execution of tasks, command running, and query processing.
- Communication Layer (Protos): The “protos” directory shows that there is a well-defined contract (using Protocol Buffers) for internal and possibly external communication between microservices.
- Data Storage Layer: Implicit from the migration files and PostgreSQL helm chart, a relational database is used for persisting all the application data.
- Docker / Deployment: Dockerfiles, docker-compose, Helm charts, and associated scripts indicate containerized deployment and orchestration of services.
- External Integrations: Represent external observability tools, APIs, and servers (like CloudWatch, Grafana, elastic search, etc.) that are connected via the connectors subsystem.
- Workflows: The workflow components (under executor/workflows) provide support for task scheduling, event handling, and notification routing.

##### Relationships and Interactions
- The frontend (web client) communicates with the backend API through REST endpoints (or potentially via GraphQL) to manage playbook configurations, authenticate users, and request execution of investigations.
- The backend “playbooks” module and “executor” module work together to translate PlayBook definitions into a series of actions.
- The “connectors” module interacts with external systems: once a PlayBook is executed, connector assets and managers send commands or queries to external services.
- Communication between internal services is tightly controlled via defined Protocol Buffers interfaces (protos directory), indicating a microservice or modular internal architecture.
- A messaging or task queue (celery, as seen in the Helm charts for celery beat/worker) is used for asynchronous task execution in the executor subsystem.

##### Architectural Patterns
- Modular / Domain Driven Design: Each Django app (accounts, connectors, executor, playbooks, etc.) abstracts a separate domain.
- Layered Architecture: There’s a clear separation between the presentation layer (frontend), service layer (backend APIs and business logic), integration layer (connectors and engines), and persistence layer (database).
- Containerized Deployment: Docker and Helm charts denote container-based deployment with orchestration.
- Event-driven / Asynchronous Processing: Use of celery workers for managing background tasks.
- Use of Protobuf for inter-service communications further emphasizes clear interface definitions between components.

##### Relevant Technologies & Frameworks
- Python/Django for the backend with multiple dedicated apps.
- React and Vite for the frontend web client.
- Docker Compose & Kubernetes (via Helm charts) for container orchestration.
- Celery for asynchronous job processing.
- Protocol Buffers (protos) for data contracts.
- Database systems such as PostgreSQL (as indicated by the Helm chart).
- Integration with observability tools (like CloudWatch, Grafana, etc.) via custom connector code.

##### Final Advice
- Use layering (similar to OSI models) to separate concerns – this helps in understanding data flow from user interactions to backend execution and external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        FE("Frontend Web Application"):::frontend
        click FE "https://github.com/drdroidlab/playbooks/tree/main/web"
    end

    subgraph "Backend Services"
        A("User Management (Accounts)"):::backend
        click A "https://github.com/drdroidlab/playbooks/tree/main/accounts"
        P("Playbooks Engine"):::backend
        click P "https://github.com/drdroidlab/playbooks/tree/main/playbooks"
        EXE("Executor (Task Orchestration)"):::backend
        click EXE "https://github.com/drdroidlab/playbooks/tree/main/executor"
        ENG("Engines (Query & Parsing)"):::backend
        click ENG "https://github.com/drdroidlab/playbooks/tree/main/engines"
        CON("Connectors (External Integrations)"):::backend
        click CON "https://github.com/drdroidlab/playbooks/tree/main/connectors"
        PB("Protobuf Contracts"):::integration
        click PB "https://github.com/drdroidlab/playbooks/tree/main/protos"
    end

    subgraph "Data Storage"
        DB("PostgreSQL Database"):::database
        click DB "https://github.com/drdroidlab/playbooks/tree/main/helm/charts/postgresql"
        subgraph "Data Migrations"
            AM("Accounts Migrations"):::database
            click AM "https://github.com/drdroidlab/playbooks/tree/main/accounts/migrations"
            PM("Playbooks Schema"):::database
            click PM "https://github.com/drdroidlab/playbooks/tree/main/playbooks/db"
            EM("Executor Migrations"):::database
            click EM "https://github.com/drdroidlab/playbooks/tree/main/executor/migrations"
            CM("Connectors Migrations"):::database
            click CM "https://github.com/drdroidlab/playbooks/tree/main/connectors/migrations"
        end
    end

    subgraph "Deployment & Infrastructure"
        D1("Dockerfile"):::deployment
        click D1 "https://github.com/drdroidlab/playbooks/tree/main/Dockerfile"
        D2("docker-compose"):::deployment
        click D2 "https://github.com/drdroidlab/playbooks/blob/main/deploy.docker-compose.yaml"
        D3("docker directory"):::deployment
        click D3 "https://github.com/drdroidlab/playbooks/tree/main/docker"
        D4("helm directory"):::deployment
        click D4 "https://github.com/drdroidlab/playbooks/tree/main/helm"
    end

    subgraph "Workflows & Messaging"
        WF("Workflows (Task Scheduling & Notifications)"):::workflow
        click WF "https://github.com/drdroidlab/playbooks/tree/main/executor/workflows"
    end

    subgraph "External Systems"
        EXT("External Observability Tools"):::external
    end

    FE -->|"API_calls"| A
    FE -->|"API_calls"| P
    P -->|"triggers"| EXE
    EXE -->|"schedules"| WF
    EXE -->|"invokes"| CON
    CON -->|"communicates"| EXT

    A -->|"persists"| DB
    P -->|"persists"| DB
    EXE -->|"persists"| DB
    ENG -->|"persists"| DB
    CON -->|"persists"| DB

    A -->|"uses"| PB
    P -->|"uses"| PB
    EXE -->|"uses"| PB
    ENG -->|"uses"| PB
    CON -->|"uses"| PB

    AM --> DB
    PM --> DB
    EM --> DB
    CM --> DB

    D1 --> FE
    D2 --> P
    D3 --> EXE
    D4 --> DB

    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A3E4D7,stroke:#1ABC9C,stroke-width:2px;
    classDef deployment fill:#F5B7B1,stroke:#CD6155,stroke-width:2px;
    classDef integration fill:#C39BD3,stroke:#8E44AD,stroke-width:2px;
    classDef workflow fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
```
