# openops-cloud/openops architecture

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

- Interactive diagram: https://gitdiagram.com/openops-cloud/openops
- Repository: https://github.com/openops-cloud/openops

## Overview

##### Project type and purpose
- OpenOps is a full-stack, No-Code FinOps automation platform.
- It consists of:
- A React-based browser UI (packages/react-ui & packages/ui-components)
- A TypeScript backend API (packages/server/api)
- A background worker (packages/server/worker)
- A sandboxed flow engine (packages/engine)
- A CLI (packages/cli)
- A library of “blocks” (packages/blocks/*) that connect to AWS, Azure, Slack, etc.
- Shared libraries (packages/server/shared & packages/shared) and end-to-end tests.

##### File structure for architectural hints
- Top-level directories:
- devcontainer, Docker, CI/CD files – containerized deployment
- deploy/docker-compose – local install
- nx.json & project.json – Nx monorepo orchestration
- packages/** – separate Nx projects (blocks, engine, openops core logic, react UI, server API, worker, CLI, UI-components, shared libs)
- tests-e2e – browser automation against real stack
- Notice “blocks” follow a plugin pattern (each integration is a block project).
- Backend uses controllers, modules, entities, migrations (Postgres & SQLite).
- Worker uses Redis as queue and pub/sub.
- Engine uses isolated-vm or v8-isolate for sandbox execution of workflow steps.

##### Extract additional insights from README
- OpenOps can be run as a managed service or via Docker-Compose locally.
- Deep integrations with cloud providers (AWS, Azure, GCP) plus Slack, GitHub, Jira, Snowflake, etc.
- Key domains: workflow editor & versioning, analytics, tables database, approvals.

##### Main components & interactions
a. Components
- Browser / React UI – user builds & runs workflows
- API Service – HTTP REST (Nest/Fastify) endpoints & WebSocket gateway
- PostgreSQL – primary data store for users, projects, flows, logs, templates
- Redis – message broker for queue and pub/sub (flow-runs, triggers, real-time updates)
- Worker – consumes Redis jobs, calls Engine, writes results back to API/DB
- Engine – sandboxed code executor that loads block definitions & runs steps
- Blocks Registry – Nx-managed packages of integration code (AWS, Azure, Slack, etc.)
- CLI – developer tooling to scaffold blocks/triggers and sync to server
- External Services – AWS, Azure, GCP, Slack, GitHub, Jira, Snowflake, Databricks, etc.

b. Data flows & relationships
1. User → React UI (HTTP / WebSocket) → API
2. API persists workflow definitions, version metadata → PostgreSQL
3. User triggers a flow run → API enqueues “flow-run” job in Redis
4. Worker subscribes to Redis queue → pulls job → invokes Engine
5. Engine loads block code & context → executes step(s) → returns events/results
6. Worker writes step results via API → API updates PostgreSQL
7. API publishes real-time progress via Redis pub/sub → WebSocket → React UI
8. Blocks call out to external cloud and SaaS APIs (AWS SDK, Azure REST, Slack API, etc.)

c. Architectural patterns & principles
- Modular plugin architecture for blocks – each integration is a self-contained Nx project
- Event-driven / message-oriented for decoupling (Redis queue/pubsub)
- Sandbox isolation for untrusted user code (isolated-vm or V8 isolate)
- Monorepo with Nx for fast, consistent builds & shared code
- Clear separation of concerns: UI, API, background processing, engine, data stores

d. Key technologies & frameworks
- React + Vite (packages/react-ui)
- Node.js + TypeScript + Fastify/Nest controllers (packages/server/api)
- Redis (queue + pub/sub)
- PostgreSQL (and SQLite for tests)
- isolated-vm / V8 isolate (packages/engine)
- Nx monorepo tooling, Jest/Karma for tests
- Docker / Docker-Compose for local environments
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Presentation Layer"
    direction TB
    User["User"]:::user
    ReactUI["React UI"]:::ui
    UIComp["UI Components"]:::ui
    SharedLib["Shared Client & Core Libs"]:::plugin
    User -->|"Interacts via Browser"| ReactUI
    ReactUI -->|"Uses components"| UIComp
    ReactUI -->|"Imports shared libs"| SharedLib
  end

  subgraph "API Layer"
    direction TB
    API["API Service"]:::backend
    CLI["CLI Tooling"]:::cli
    SharedServer["Shared Server Utilities"]:::plugin
    ReactUI -->|"HTTP/WS"| API
    CLI -->|"HTTP/WS"| API
    API -->|"Imports shared utils"| SharedServer
  end

  subgraph "Data & Messaging"
    direction TB
    Postgres[(PostgreSQL)]:::db
    Redis[(Redis)]:::message
    E2E["End-to-End Tests"]:::test
    API -->|"Reads/Writes"| Postgres
    API -->|"Enqueue/Publish"| Redis
    Postgres -->|"Test database"| E2E
  end

  subgraph "Background Processing"
    direction TB
    Worker["Background Worker"]:::backend
    Engine["Sandboxed Flow Engine"]:::engine
    Blocks["Blocks Registry"]:::plugin
    Redis -->|"Subscribes queue"| Worker
    Worker -->|"Invoke engine"| Engine
    Engine -->|"Execution results"| Worker
    Worker -->|"via API"| API
    Blocks -->|"Loads block code"| Engine
  end

  subgraph "External Services"
    direction TB
    AWS["AWS"]:::external
    Azure["Azure"]:::external
    Slack["Slack"]:::external
    GitHub["GitHub"]:::external
    Jira["Jira"]:::external
    Snowflake["Snowflake"]:::external
    Databricks["Databricks"]:::external
    Engine -->|"Calls APIs"| AWS
    Engine -->|"Calls APIs"| Azure
    Engine -->|"Calls APIs"| Slack
    Engine -->|"Calls APIs"| GitHub
    Engine -->|"Calls APIs"| Jira
    Engine -->|"Calls APIs"| Snowflake
    Engine -->|"Calls APIs"| Databricks
  end

  subgraph "Dev & Deploy"
    direction TB
    DockerCompose["Docker-Compose"]:::deploy
    DevContainer["DevContainer"]:::deploy
    Nx["Nx Orchestration"]:::deploy
  end

  classDef user fill:#D0E6FF,stroke:#0366d6
  classDef ui fill:#BEE3F8,stroke:#3182CE
  classDef backend fill:#C6F6D5,stroke:#38A169
  classDef cli fill:#FEEBC8,stroke:#DD6B20
  classDef db fill:#FEEBC8,stroke:#D69E2E
  classDef message fill:#F0ABFC,stroke:#9F7AEA
  classDef engine fill:#FDE68A,stroke:#D97706
  classDef plugin fill:#E2E8F0,stroke:#718096
  classDef external fill:#EDF2F7,stroke:#4A5568
  classDef test fill:#FFF5F7,stroke:#D53F8C
  classDef deploy fill:#E6FFFA,stroke:#2C7A7B

  click ReactUI "https://github.com/openops-cloud/openops/tree/main/packages/react-ui"
  click UIComp "https://github.com/openops-cloud/openops/tree/main/packages/ui-components"
  click API "https://github.com/openops-cloud/openops/tree/main/packages/server/api"
  click Worker "https://github.com/openops-cloud/openops/tree/main/packages/server/worker"
  click Engine "https://github.com/openops-cloud/openops/tree/main/packages/engine"
  click CLI "https://github.com/openops-cloud/openops/tree/main/packages/cli"
  click Blocks "https://github.com/openops-cloud/openops/tree/main/packages/blocks/"
  click SharedServer "https://github.com/openops-cloud/openops/tree/main/packages/server/shared"
  click SharedLib "https://github.com/openops-cloud/openops/tree/main/packages/shared"
  click E2E "https://github.com/openops-cloud/openops/tree/main/packages/tests-e2e"
  click DockerCompose "https://github.com/openops-cloud/openops/blob/main/deploy/docker-compose/docker-compose.yml"
  click DevContainer "https://github.com/openops-cloud/openops/blob/main/.devcontainer/devcontainer.json"
  click Nx "https://github.com/openops-cloud/openops/blob/main/nx.json"
```
