Architecture

Frontend (React 19) ←→ Backend (NestJS) ←→ Temporal ←→ Worker (Node.js)
     ↓                      ↓                  ↓              ↓
  Visual Builder         REST API          Workflow        Component
  & Timeline             & Auth          Orchestration     Execution

shipsec-studio/
├── packages/
│   ├── component-sdk/          # Framework-agnostic component SDK
│   ├── backend-client/         # Generated TypeScript API client
│   └── shared/                 # Shared types and schemas
│
├── worker/                     # Component execution engine
│   └── src/
│       ├── components/         # Security component implementations
│       ├── adapters/           # Service interface implementations
│       └── temporal/           # Workflow orchestration
│
├── backend/                    # REST API and orchestration
│   └── src/
│       ├── workflows/          # Workflow CRUD + compilation
│       ├── storage/            # File upload/download API
│       ├── secrets/            # Encrypted secrets management
│       └── temporal/           # Temporal client wrapper
│
└── frontend/                   # React workflow builder
    └── src/
        ├── components/
        │   ├── workflow-builder/  # ReactFlow visual editor
        │   ├── terminal/          # Real-time terminal display
        │   └── timeline/          # Execution timeline
        ├── store/                 # Zustand state management
        └── hooks/                 # API and real-time hooks

interface ComponentDefinition<Input, Output> {
  id: string;
  label: string;
  category: 'triggers' | 'discovery' | 'transform' | 'output';
  runner: DockerRunnerConfig | InlineRunnerConfig;
  inputSchema: ZodSchema<Input>;
  outputSchema: ZodSchema<Output>;
  execute: (input: Input, context: ExecutionContext) => Promise<Output>;
}

interface IFileStorageService {
  upload(buffer: Buffer, mimeType: string): Promise<string>;
  download(key: string): Promise<Buffer>;
  delete(key: string): Promise<void>;
}

interface ISecretsService {
  getSecret(secretId: string): Promise<string>;
  rotateSecret(secretId: string, newValue: string): Promise<void>;
}

interface ITraceService {
  record(event: TraceEvent): Promise<void>;
  setRunMetadata(runId: RunMetadata): void;
  finalizeRun(runId: string): void;
}

async function runComponentActivity(
  componentId: string,
  input: unknown,
  context: ActivityContext
): Promise<unknown> {
  const component = componentRegistry.getComponent(componentId);
  const executionContext = createExecutionContext({
    storage: globalStorage,
    secrets: allowSecrets ? globalSecrets : undefined,
    artifacts: scopedArtifacts,
    trace: globalTrace,
    logCollector: globalLogs,
    terminalCollector: globalTerminal,
  });

  return await component.execute(input, executionContext);
}

1. Frontend creates workflow graph (ReactFlow)
   └─> POST /api/v1/workflows with nodes & edges

2. Backend validates and compiles
   └─> Validates nodes against componentRegistry
   └─> Compiles graph → DSL (topological sort + join strategies)
   └─> Stores in PostgreSQL
   └─> Calls TemporalService.startWorkflow()

3. Temporal orchestrates execution
   └─> Schedules workflow on "shipsec-workflows" queue
   └─> Worker picks up and executes components via activities

4. Component execution in Worker
   └─> runComponentActivity() looks up component in registry
   └─> Creates ExecutionContext with injected services
   └─> Executes in Docker container with isolation
   └─> Streams logs, events, and terminal output in real-time

5. Real-time monitoring
   └─> Events → Kafka → Backend → WebSocket to Frontend
   └─> Terminal → Redis Streams → SSE to Frontend
   └─> Logs → Kafka → Loki → Backend API queries

-- Workflow definitions
workflows (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  graph JSONB NOT NULL,
  compiled_definition JSONB,
  organization_id VARCHAR
);

-- Workflow execution instances
workflow_runs (
  run_id TEXT PRIMARY KEY,
  workflow_id UUID NOT NULL,
  temporal_run_id TEXT,
  inputs JSONB NOT NULL,
  status VARCHAR,
  started_at TIMESTAMP,
  completed_at TIMESTAMP
);

-- Component execution results
workflow_nodes (
  id UUID PRIMARY KEY,
  run_id TEXT NOT NULL,
  node_ref TEXT NOT NULL,
  component_id TEXT NOT NULL,
  inputs JSONB,
  outputs JSONB,
  status VARCHAR,
  error_message TEXT
);

-- Secure storage
secrets (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL UNIQUE,
  current_version INTEGER DEFAULT 1,
  versions JSONB NOT NULL,
  organization_id VARCHAR
);