# litmuschaos/litmus architecture

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

- Interactive diagram: https://gitdiagram.com/litmuschaos/litmus
- Repository: https://github.com/litmuschaos/litmus

## Overview

LitmusChaos is a chaos-engineering platform; this repository slice shows its Chaos Center control plane and supporting services. The main user flow is to authenticate, configure a target and experiment workflow, run or schedule it, and view run status. The README documents execution through Kubernetes chaos resources, while the sampled subscriber code shows Kubernetes event watching and workflow-event streaming. Some subsystems are represented by tree paths or README capabilities rather than inspected implementation, so their internal wiring is intentionally limited.

Main entry points: [`chaoscenter/graphql/server/server.go`](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/server.go) (GraphQL API), [`chaoscenter/graphql/server/pkg/database/mongodb/operations.go`](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/database/mongodb/operations.go) (MongoDB persistence), [`chaoscenter/web/src/app/App.tsx`](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/app/App.tsx) (Web application), [`chaoscenter/authentication/pkg/services/application_service.go`](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/services/application_service.go) (Identity services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Chaos Center UI"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_workflowui["Workflow editor<br/>[PipelineGraph.tsx]"]
  node_api["Web API hooks"]
end

subgraph group_control["Control Plane"]
  node_graphql["GraphQL API<br/>[server.go]"]
  node_experiment["Experiment service<br/>[service.go]"]
  node_runs["Run service<br/>[service.go]"]
  node_infrastructure["Infrastructure service<br/>[service.go]"]
  node_hub["Chaos Hub service<br/>[service.go]"]
  node_gitops["GitOps service<br/>[service.go]"]
  node_probe["Probe service<br/>[handler.go]"]
  node_environment["Environment handler<br/>[handler.go]"]
  node_mongodb[("MongoDB persistence<br/>[operations.go]")]
  node_upgrade["Control-plane upgrades<br/>[upgrade-manager.go]"]
end

subgraph group_identity["Identity"]
  node_authapi["Authentication API<br/>[main.go]"]
  node_authservice["Identity services"]
  node_session["Session service<br/>[session_service.go]"]
  node_authstore[("Identity repositories<br/>[repository.go]")]
end

subgraph group_runtime["Execution Tracking"]
  node_subscriber["Kubernetes subscriber<br/>[subscriber.go]"]
  node_engineevents["Engine event watcher<br/>[chaosengine.go]"]
  node_workflowevents["Workflow events<br/>[workflow.go]"]
  node_eventtracker["Event tracker controller"]
end

node_user(("Developer / SRE"))
node_kubernetes["Target Kubernetes"]
node_execution["Chaos execution plane"]

node_user -->|"uses"| node_webapp
node_webapp -->|"edits workflow"| node_workflowui
node_webapp -->|"requests data"| node_api
node_api -->|"calls API"| node_graphql
node_graphql -->|"dispatches"| node_experiment
node_graphql -->|"dispatches"| node_runs
node_graphql -->|"dispatches"| node_infrastructure
node_graphql -->|"dispatches"| node_hub
node_graphql -->|"dispatches"| node_gitops
node_graphql -->|"dispatches"| node_probe
node_graphql -->|"dispatches"| node_environment
node_experiment -->|"reads / writes"| node_mongodb
node_runs -->|"reads / writes"| node_mongodb
node_infrastructure -->|"reads / writes"| node_mongodb
node_hub -->|"reads / writes"| node_mongodb
node_gitops -->|"reads / writes"| node_mongodb
node_probe -->|"reads / writes"| node_mongodb
node_environment -->|"reads / writes"| node_mongodb
node_user -->|"authenticates"| node_authapi
node_authapi -->|"invokes"| node_authservice
node_authservice -->|"uses"| node_session
node_authservice -->|"reads / writes"| node_authstore
node_session -->|"stores tokens"| node_authstore
node_graphql -->|"validates identity"| node_authapi
node_subscriber -->|"starts watcher"| node_engineevents
node_engineevents -->|"watches resources"| node_kubernetes
node_engineevents -->|"emits events"| node_workflowevents
node_kubernetes -->|"hosts resources"| node_execution
node_execution -->|"runs experiments"| node_kubernetes
node_eventtracker -->|"reconciles policy"| node_kubernetes
node_eventtracker -->|"triggers experiment"| node_execution
node_upgrade -->|"updates version"| node_mongodb

click node_webapp "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/app/App.tsx"
click node_workflowui "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/components/PipelineDiagram/PipelineGraph/PipelineGraph.tsx"
click node_api "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/api/core/experiments/runChaosExperiment.ts"
click node_graphql "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/server.go"
click node_experiment "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaos_experiment/ops/service.go"
click node_runs "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaos_experiment_run/service.go"
click node_infrastructure "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaos_infrastructure/service.go"
click node_hub "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaoshub/service.go"
click node_gitops "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/gitops/service.go"
click node_probe "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/probe/handler/handler.go"
click node_environment "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/environment/handler/handler.go"
click node_mongodb "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/database/mongodb/operations.go"
click node_authapi "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/api/main.go"
click node_authservice "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/services/application_service.go"
click node_session "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/services/session_service.go"
click node_authstore "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/user/repository.go"
click node_subscriber "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/subscriber/subscriber.go"
click node_engineevents "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/subscriber/pkg/events/chaosengine.go"
click node_workflowevents "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/subscriber/pkg/events/workflow.go"
click node_eventtracker "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/event-tracker/controllers/eventtrackerpolicy_controller.go"
click node_upgrade "https://github.com/litmuschaos/litmus/blob/master/chaoscenter/upgrade-agents/control-plane/versions/upgrade-manager.go"

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_webapp,node_workflowui,node_api toneBlue
class node_graphql,node_experiment,node_runs,node_infrastructure,node_hub,node_gitops,node_probe,node_environment,node_mongodb,node_upgrade toneAmber
class node_authapi,node_authservice,node_session,node_authstore toneMint
class node_subscriber,node_engineevents,node_workflowevents,node_eventtracker toneRose
class node_user,node_kubernetes,node_execution toneIndigo
```

## Components

### Chaos Center UI

- [Web application](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/app/App.tsx): `chaoscenter/web/src/app/App.tsx`
- [Workflow editor](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/components/PipelineDiagram/PipelineGraph/PipelineGraph.tsx): `chaoscenter/web/src/components/PipelineDiagram/PipelineGraph/PipelineGraph.tsx`
- [Web API hooks](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/web/src/api/core/experiments/runChaosExperiment.ts): `chaoscenter/web/src/api/core/experiments/runChaosExperiment.ts`

### Control Plane

- [GraphQL API](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/server.go): `chaoscenter/graphql/server/server.go`
- [Experiment service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaos_experiment/ops/service.go): `chaoscenter/graphql/server/pkg/chaos_experiment/ops/service.go`
- [Run service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaos_experiment_run/service.go): `chaoscenter/graphql/server/pkg/chaos_experiment_run/service.go`
- [Infrastructure service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaos_infrastructure/service.go): `chaoscenter/graphql/server/pkg/chaos_infrastructure/service.go`
- [Chaos Hub service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/chaoshub/service.go): `chaoscenter/graphql/server/pkg/chaoshub/service.go`
- [GitOps service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/gitops/service.go): `chaoscenter/graphql/server/pkg/gitops/service.go`
- [Probe service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/probe/handler/handler.go): `chaoscenter/graphql/server/pkg/probe/handler/handler.go`
- [Environment handler](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/environment/handler/handler.go): `chaoscenter/graphql/server/pkg/environment/handler/handler.go`
- [MongoDB persistence](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/graphql/server/pkg/database/mongodb/operations.go): `chaoscenter/graphql/server/pkg/database/mongodb/operations.go`
- [Control-plane upgrades](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/upgrade-agents/control-plane/versions/upgrade-manager.go): `chaoscenter/upgrade-agents/control-plane/versions/upgrade-manager.go`

### Identity

- [Authentication API](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/api/main.go): `chaoscenter/authentication/api/main.go`
- [Identity services](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/services/application_service.go): `chaoscenter/authentication/pkg/services/application_service.go`
- [Session service](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/services/session_service.go): `chaoscenter/authentication/pkg/services/session_service.go`
- [Identity repositories](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/authentication/pkg/user/repository.go): `chaoscenter/authentication/pkg/user/repository.go`

### Execution Tracking

- [Kubernetes subscriber](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/subscriber/subscriber.go): `chaoscenter/subscriber/subscriber.go`
- [Engine event watcher](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/subscriber/pkg/events/chaosengine.go): `chaoscenter/subscriber/pkg/events/chaosengine.go`
- [Workflow events](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/subscriber/pkg/events/workflow.go): `chaoscenter/subscriber/pkg/events/workflow.go`
- [Event tracker controller](https://github.com/litmuschaos/litmus/blob/master/chaoscenter/event-tracker/controllers/eventtrackerpolicy_controller.go): `chaoscenter/event-tracker/controllers/eventtrackerpolicy_controller.go`

### Other components

- **Developer / SRE**
- **Target Kubernetes**
- **Chaos execution plane**

## Connections

- Developer / SRE → Web application: uses
- Web application → Workflow editor: edits workflow
- Web application → Web API hooks: requests data
- Web API hooks → GraphQL API: calls API
- GraphQL API → Experiment service: dispatches
- GraphQL API → Run service: dispatches
- GraphQL API → Infrastructure service: dispatches
- GraphQL API → Chaos Hub service: dispatches
- GraphQL API → GitOps service: dispatches
- GraphQL API → Probe service: dispatches
- GraphQL API → Environment handler: dispatches
- Experiment service → MongoDB persistence: reads / writes
- Run service → MongoDB persistence: reads / writes
- Infrastructure service → MongoDB persistence: reads / writes
- Chaos Hub service → MongoDB persistence: reads / writes
- GitOps service → MongoDB persistence: reads / writes
- Probe service → MongoDB persistence: reads / writes
- Environment handler → MongoDB persistence: reads / writes
- Developer / SRE → Authentication API: authenticates
- Authentication API → Identity services: invokes
- Identity services → Session service: uses
- Identity services → Identity repositories: reads / writes
- Session service → Identity repositories: stores tokens
- GraphQL API → Authentication API: validates identity
- Kubernetes subscriber → Engine event watcher: starts watcher
- Engine event watcher → Target Kubernetes: watches resources
- Engine event watcher → Workflow events: emits events
- Target Kubernetes → Chaos execution plane: hosts resources
- Chaos execution plane → Target Kubernetes: runs experiments
- Event tracker controller → Target Kubernetes: reconciles policy
- Event tracker controller → Chaos execution plane: triggers experiment
- Control-plane upgrades → MongoDB persistence: updates version