> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipsec.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> System design and module responsibilities for ShipSec Studio

## What is ShipSec Studio?

ShipSec Studio is an open-source, no-code security workflow orchestration platform. Build, execute, and monitor security automation workflows through a visual interface — focus on security, not infrastructure.

***

## System Overview

```
┌────────────────────────────────────────────────────────────────────────┐
│                              FRONTEND                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Visual    │  │  Terminal   │  │  Timeline   │  │   Config    │    │
│  │   Builder   │  │   Viewer    │  │   Replay    │  │    Panel    │    │
│  │ (ReactFlow) │  │  (xterm.js) │  │  (Zustand)  │  │  (Forms)    │    │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ REST API + Unified SSE
┌───────────────────────────────────▼─────────────────────────────────────┐
│                               BACKEND                                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │Workflows │ │ Secrets  │ │ Storage  │ │  Trace   │ │  Auth    │       │
│  │  + DSL   │ │(AES-256) │ │ (MinIO)  │ │ Events   │ │ (Clerk)  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Webhooks │ │Schedules │ │ Agents   │ │Human     │ │Integr-   │       │
│  │          │ │ (CRON)   │ │          │ │Inputs    │ │ations    │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Temporal Client
┌───────────────────────────────────▼─────────────────────────────────────┐
│                              TEMPORAL                                   │
│            Workflow Orchestration • Retry Logic • Durability            │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ Activity Execution
┌───────────────────────────────────▼─────────────────────────────────────┐
│                               WORKER                                    │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    COMPONENT REGISTRY                           │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐            │    │
│  │  │  Tools   │ │    AI    │ │  Human   │ │   Core   │            │    │
│  │  │(Security)│ │  Agents  │ │ in Loop  │ │  Utils   │            │    │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                      SERVICE ADAPTERS                           │    │
│  │  Secrets │ Storage │ Artifacts │ Trace │ Terminal │ Logs        │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                           INFRASTRUCTURE                                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │PostgreSQL│ │  MinIO   │ │  Redis   │ │Redpanda  │ │   Loki   │       │
│  │  (Data)  │ │ (Files)  │ │(Terminal)│ │ (Kafka)  │ │  (Logs)  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────────────────┘
```

***

## Technology Stack

| Layer              | Stack                                                                           |
| ------------------ | ------------------------------------------------------------------------------- |
| **Frontend**       | React 19, TypeScript, Vite, TailwindCSS, Radix UI, ReactFlow, xterm.js, Zustand |
| **Backend**        | NestJS, TypeScript, Bun, Drizzle ORM, Clerk Auth                                |
| **Worker**         | Node.js, TypeScript, Temporal SDK, Docker                                       |
| **Infrastructure** | PostgreSQL 16, Temporal, MinIO, Redis, Redpanda (Kafka), Loki                   |

***

## Core Deep-Dives

To keep this guide concise, complicated subsystems are documented in their own dedicated files:

* **[Workflow Compilation (DSL)](/architecture/workflow-compilation)**: How visual graphs are transformed into executable instructions.
* **[Temporal Orchestration](/architecture/temporal-orchestration)**: How we use Temporal for durability and worker scaling.
* **[Streaming Pipelines](/architecture/streaming-pipelines)**: How terminal, logs, and events are delivered in real-time.
* **[Human-in-the-Loop](/architecture/human-in-the-loop)**: How we pause workflows for manual approvals and forms.

***

## Component Categories

Components are the building blocks of workflows:

| Category          | Description                             | Examples                                                |
| ----------------- | --------------------------------------- | ------------------------------------------------------- |
| **security**      | Security scanning and enumeration tools | Subfinder, DNSX, Nuclei, Naabu, HTTPx, TruffleHog       |
| **ai**            | AI/ML and agent components              | LLM Generate, AI Agent, MCP Providers                   |
| **core**          | Utility and data processing             | HTTP Request, File Loader, Logic Script, JSON Transform |
| **notification**  | Alerts and messaging                    | Slack, Email                                            |
| **manual-action** | Human-in-the-loop                       | Approvals, Forms, Selection                             |
| **github**        | GitHub integrations                     | Remove Org Membership                                   |

***

## Security Architecture

### Authentication & Multi-tenancy

* **Clerk Integration** — Production-ready authentication for hosted environments.
* **Local Auth** — Default for local setup using `ADMIN_USERNAME` / `ADMIN_PASSWORD`.
* **Organization Isolation** — All data scoped by `organization_id`.

### Secrets Management

* **AES-256-GCM** encryption at rest.
* **Versioned secrets** with active/inactive tracking.
* **Master key** via `SECRET_STORE_MASTER_KEY` environment variable.

### Container Isolation

* **IsolatedContainerVolume** — Per-tenant, per-run Docker volumes. See **[Isolated Volumes](/development/isolated-volumes)**.
* **Network isolation** — Components run with `network: none` or `bridge`.
* **Automatic cleanup** — Volumes destroyed after execution.

***

## Development URLs

All application services are accessible through nginx on port 80:

| Service          | URL                                                        |
| ---------------- | ---------------------------------------------------------- |
| Frontend         | [http://localhost/](http://localhost/)                     |
| Backend API      | [http://localhost/api/](http://localhost/api/)             |
| Analytics        | [http://localhost/analytics/](http://localhost/analytics/) |
| Temporal UI      | [http://localhost:8081](http://localhost:8081)             |
| MinIO Console    | [http://localhost:9001](http://localhost:9001)             |
| Redpanda Console | [http://localhost:8082](http://localhost:8082)             |
| Loki             | [http://localhost:3100](http://localhost:3100)             |

<Note>
  Individual service ports (5173, 3211, 5601) are available for debugging but should not be used in normal development. All traffic flows through nginx on port 80.
</Note>

***

## Learn More

* **Component Development**: `/development/component-development`
* **Getting Started**: `/getting-started`