# shipsecai/studio architecture

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

- Interactive diagram: https://gitdiagram.com/shipsecai/studio
- Repository: https://github.com/shipsecai/studio

## Overview

ShipSec Studio is a security-workflow authoring, execution, and monitoring platform. A user designs a workflow in the visual builder, submits it through the backend management plane, and the workflow is compiled and run durably by Temporal-backed workers using security components and integrations. The backend also exposes workflow APIs and product capabilities such as scheduling, human approvals, MCP discovery, templates, and artifact storage. Telemetry flows from workers through Kafka ingestion to monitoring stores. Some subsystem links are documented rather than visible in sampled implementation excerpts.

Main entry points: [`backend/src/workflows/workflows.service.ts`](https://github.com/shipsecai/studio/blob/main/backend/src/workflows/workflows.service.ts) (Workflow service), [`backend/src/temporal/temporal.service.ts`](https://github.com/shipsecai/studio/blob/main/backend/src/temporal/temporal.service.ts) (Temporal orchestration), [`backend/src/database/schema/index.ts`](https://github.com/shipsecai/studio/blob/main/backend/src/database/schema/index.ts) (PostgreSQL state), [`worker/src/components/index.ts`](https://github.com/shipsecai/studio/blob/main/worker/src/components/index.ts) (Workflow worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Workflow authoring"]
  node_builder["Visual builder"]
  node_frontend_api["Frontend API<br/>[api.ts]"]
end

subgraph group_management["Management plane"]
  node_workflow_api["Workflow API"]
  node_workflow_service["Workflow service"]
  node_dsl["DSL compiler<br/>[compiler.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_schedules["Scheduling"]
  node_human_input["Human approvals"]
  node_templates["Workflow templates"]
  node_mcp["MCP discovery"]
end

subgraph group_execution["Execution plane"]
  node_temporal["Temporal orchestration"]
  node_worker["Workflow worker<br/>[index.ts]"]
  node_components["Security components"]
  node_integrations["External tooling"]
end

subgraph group_monitoring["Monitoring"]
  node_telemetry["Telemetry adapters"]
  node_ingestion["Event ingestion"]
  node_logs["Log ingestion"]
  node_kafka["Kafka"]
  node_loki[("Loki")]
end

subgraph group_state["State and integrations"]
  node_db[("PostgreSQL state<br/>[index.ts]")]
  node_storage["Artifact storage<br/>[storage.service.ts]"]
  node_minio[("MinIO")]
end

node_user(("Security team"))

node_user -->|"designs"| node_builder
node_builder -->|"submits workflow"| node_frontend_api
node_frontend_api -->|"calls API"| node_workflow_api
node_workflow_api -->|"delegates"| node_workflow_service
node_workflow_service -->|"compiles graph"| node_dsl
node_workflow_service -->|"starts runs"| node_temporal
node_temporal -->|"dispatches work"| node_worker
node_worker -->|"executes nodes"| node_components
node_components -->|"invokes tools"| node_integrations
node_workflow_service -->|"persists workflow state"| node_db
node_auth -.->|"reads identity state"| node_db
node_schedules -->|"schedules runs"| node_temporal
node_human_input -->|"pauses workflows"| node_temporal
node_templates -->|"provides workflows"| node_workflow_service
node_mcp -->|"starts discovery"| node_temporal
node_worker -->|"publishes telemetry"| node_kafka
node_kafka -->|"delivers events"| node_ingestion
node_kafka -->|"delivers logs"| node_logs
node_ingestion -->|"appends traces"| node_db
node_logs -->|"pushes logs"| node_loki
node_logs -->|"updates metadata"| node_db
node_storage -->|"stores files"| node_minio

click node_builder "https://github.com/shipsecai/studio/blob/main/frontend/src/features/workflow-builder/WorkflowBuilder.tsx"
click node_frontend_api "https://github.com/shipsecai/studio/blob/main/frontend/src/services/api.ts"
click node_workflow_api "https://github.com/shipsecai/studio/blob/main/backend/src/workflows/workflows.controller.ts"
click node_workflow_service "https://github.com/shipsecai/studio/blob/main/backend/src/workflows/workflows.service.ts"
click node_dsl "https://github.com/shipsecai/studio/blob/main/backend/src/dsl/compiler.ts"
click node_auth "https://github.com/shipsecai/studio/blob/main/backend/src/auth/auth.service.ts"
click node_schedules "https://github.com/shipsecai/studio/blob/main/backend/src/schedules/schedules.service.ts"
click node_human_input "https://github.com/shipsecai/studio/blob/main/backend/src/human-inputs/human-inputs.service.ts"
click node_templates "https://github.com/shipsecai/studio/blob/main/backend/src/templates/templates.service.ts"
click node_mcp "https://github.com/shipsecai/studio/blob/main/backend/src/mcp/mcp-discovery-orchestrator.service.ts"
click node_temporal "https://github.com/shipsecai/studio/blob/main/backend/src/temporal/temporal.service.ts"
click node_worker "https://github.com/shipsecai/studio/blob/main/worker/src/components/index.ts"
click node_components "https://github.com/shipsecai/studio/tree/main/worker/src/components/core"
click node_integrations "https://github.com/shipsecai/studio/tree/main/worker/src/components"
click node_telemetry "https://github.com/shipsecai/studio/tree/main/worker/src/adapters"
click node_ingestion "https://github.com/shipsecai/studio/blob/main/backend/src/events/event-ingest.service.ts"
click node_logs "https://github.com/shipsecai/studio/blob/main/backend/src/logging/log-ingest.service.ts"
click node_db "https://github.com/shipsecai/studio/blob/main/backend/src/database/schema/index.ts"
click node_storage "https://github.com/shipsecai/studio/blob/main/backend/src/storage/storage.service.ts"

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_builder,node_frontend_api toneBlue
class node_workflow_api,node_workflow_service,node_dsl,node_auth,node_schedules,node_human_input,node_templates,node_mcp toneAmber
class node_temporal,node_worker,node_components,node_integrations toneMint
class node_telemetry,node_ingestion,node_logs,node_kafka,node_loki toneRose
class node_db,node_storage,node_minio,node_user toneIndigo
```

## Components

### Workflow authoring

- [Visual builder](https://github.com/shipsecai/studio/blob/main/frontend/src/features/workflow-builder/WorkflowBuilder.tsx): `frontend/src/features/workflow-builder/WorkflowBuilder.tsx`
- [Frontend API](https://github.com/shipsecai/studio/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Management plane

- [Workflow API](https://github.com/shipsecai/studio/blob/main/backend/src/workflows/workflows.controller.ts): `backend/src/workflows/workflows.controller.ts`
- [Workflow service](https://github.com/shipsecai/studio/blob/main/backend/src/workflows/workflows.service.ts): `backend/src/workflows/workflows.service.ts`
- [DSL compiler](https://github.com/shipsecai/studio/blob/main/backend/src/dsl/compiler.ts): `backend/src/dsl/compiler.ts`
- [Authentication](https://github.com/shipsecai/studio/blob/main/backend/src/auth/auth.service.ts): `backend/src/auth/auth.service.ts`
- [Scheduling](https://github.com/shipsecai/studio/blob/main/backend/src/schedules/schedules.service.ts): `backend/src/schedules/schedules.service.ts`
- [Human approvals](https://github.com/shipsecai/studio/blob/main/backend/src/human-inputs/human-inputs.service.ts): `backend/src/human-inputs/human-inputs.service.ts`
- [Workflow templates](https://github.com/shipsecai/studio/blob/main/backend/src/templates/templates.service.ts): `backend/src/templates/templates.service.ts`
- [MCP discovery](https://github.com/shipsecai/studio/blob/main/backend/src/mcp/mcp-discovery-orchestrator.service.ts): `backend/src/mcp/mcp-discovery-orchestrator.service.ts`

### Execution plane

- [Temporal orchestration](https://github.com/shipsecai/studio/blob/main/backend/src/temporal/temporal.service.ts): `backend/src/temporal/temporal.service.ts`
- [Workflow worker](https://github.com/shipsecai/studio/blob/main/worker/src/components/index.ts): `worker/src/components/index.ts`
- [Security components](https://github.com/shipsecai/studio/tree/main/worker/src/components/core): `worker/src/components/core`
- [External tooling](https://github.com/shipsecai/studio/tree/main/worker/src/components): `worker/src/components`

### Monitoring

- [Telemetry adapters](https://github.com/shipsecai/studio/tree/main/worker/src/adapters): `worker/src/adapters`
- [Event ingestion](https://github.com/shipsecai/studio/blob/main/backend/src/events/event-ingest.service.ts): `backend/src/events/event-ingest.service.ts`
- [Log ingestion](https://github.com/shipsecai/studio/blob/main/backend/src/logging/log-ingest.service.ts): `backend/src/logging/log-ingest.service.ts`
- **Kafka**
- **Loki**

### State and integrations

- [PostgreSQL state](https://github.com/shipsecai/studio/blob/main/backend/src/database/schema/index.ts): `backend/src/database/schema/index.ts`
- [Artifact storage](https://github.com/shipsecai/studio/blob/main/backend/src/storage/storage.service.ts): `backend/src/storage/storage.service.ts`
- **MinIO**

### Other components

- **Security team**

## Connections

- Security team → Visual builder: designs
- Visual builder → Frontend API: submits workflow
- Frontend API → Workflow API: calls API
- Workflow API → Workflow service: delegates
- Workflow service → DSL compiler: compiles graph
- Workflow service → Temporal orchestration: starts runs
- Temporal orchestration → Workflow worker: dispatches work
- Workflow worker → Security components: executes nodes
- Security components → External tooling: invokes tools
- Workflow service → PostgreSQL state: persists workflow state
- Authentication → PostgreSQL state: reads identity state
- Scheduling → Temporal orchestration: schedules runs
- Human approvals → Temporal orchestration: pauses workflows
- Workflow templates → Workflow service: provides workflows
- MCP discovery → Temporal orchestration: starts discovery
- Workflow worker → Kafka: publishes telemetry
- Kafka → Event ingestion: delivers events
- Kafka → Log ingestion: delivers logs
- Event ingestion → PostgreSQL state: appends traces
- Log ingestion → Loki: pushes logs
- Log ingestion → PostgreSQL state: updates metadata
- Artifact storage → MinIO: stores files