# bulwark-black/bb-soc-skeleton architecture

> Architecture diagram of the GitHub repository bulwark-black/bb-soc-skeleton, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bulwark-black/bb-soc-skeleton
- Repository: https://github.com/bulwark-black/bb-soc-skeleton
- Video tour (about a minute): https://gitdiagram.com/bulwark-black/bb-soc-skeleton/video

## Overview

Bulwark Black is a self-hosted SOC interface starter centered on a private operator workflow: sign in, register an application and source, ingest normalized observations, and inspect them in bounded SOC views. Separate branches cover vendor imports, Trivy report ingestion, Sentry live monitoring, documents, setup guidance, and MCP-based administration. The graph reflects README-described capabilities and source-index imports; several subsystem implementations were not excerpted, so their internal routing is not expanded.

Main entry points: [`server/reference-runtime.js`](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-runtime.js) (Connector runtime), [`server/live-monitoring.js`](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/live-monitoring.js) (Live monitoring), [`server/reference-control-plane.js`](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-control-plane.js) (Reference control plane), [`tools/ingest-contract.js`](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/ingest-contract.js) (Ingest contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_soc["SOC interface<br/>[app.js]"]
  node_ui_contracts["UI contracts"]
  node_signin["Private sign-in<br/>[private-sign-in.js]"]
  node_documents_ui["Documents library"]
end

subgraph group_control["Control and administration"]
  node_admin_contract["Administration contract"]
  node_private_app["Private application"]
  node_auth["Authentication<br/>[private-auth.js]"]
  node_control_plane["Reference control plane"]
  node_runtime["Connector runtime"]
  node_admin_runtime["Administration runtime"]
  node_admin_store[("Administration store")]
end

subgraph group_ingest["Ingestion and observation"]
  node_ingest_contract["Ingest contract<br/>[ingest-contract.js]"]
  node_reference_pages["SOC page models<br/>[reference-pages.js]"]
  node_reference_store[("Reference data store<br/>[reference-store.js]")]
  node_coverage["Observation coverage"]
end

subgraph group_integrations["Collectors and integrations"]
  node_sender["Integration sender"]
  node_vendor_import["Vendor imports<br/>[vendor-import.js]"]
  node_vendor_adapters["Vendor adapters<br/>[vendor-adapters.js]"]
  node_scanner["Trivy report import<br/>[scanner-ingest.js]"]
  node_live["Live monitoring<br/>[live-monitoring.js]"]
end

subgraph group_support["Operator support"]
  node_mcp["Agent MCP<br/>[agent-mcp.js]"]
  node_service_access["Service access<br/>[service-access.js]"]
  node_setup["Setup assistance"]
  node_docs["Technical reference<br/>[technical-docs.js]"]
  node_document_store[("Document store<br/>[document-store.js]")]
end

node_operator(("Operator"))
node_external_sentry["Sentry Cloud"]
node_external_slack["Slack"]

node_operator -->|"signs in"| node_signin
node_signin -->|"opens session"| node_private_app
node_private_app -->|"authenticates"| node_auth
node_operator -->|"uses"| node_soc
node_soc -->|"uses contracts"| node_ui_contracts
node_private_app -->|"serves control plane"| node_control_plane
node_control_plane -->|"delegates connector actions"| node_runtime
node_control_plane -->|"delegates administration"| node_admin_runtime
node_admin_runtime -->|"uses persistence"| node_admin_store
node_admin_runtime -->|"validates with"| node_admin_contract
node_runtime -->|"validates batches"| node_ingest_contract
node_runtime -->|"persists state"| node_reference_store
node_runtime -->|"validates with"| node_ui_contracts
node_soc -->|"views SOC pages"| node_reference_pages
node_reference_pages -->|"builds observation views"| node_coverage
node_operator -->|"sends normalized records"| node_sender
node_sender -->|"prepares batches"| node_ingest_contract
node_operator -->|"imports exports"| node_vendor_import
node_vendor_import -->|"normalizes events"| node_vendor_adapters
node_vendor_adapters -->|"validates records"| node_ingest_contract
node_operator -->|"submits report"| node_scanner
node_scanner -->|"validates batch"| node_ingest_contract
node_operator -->|"configures collector"| node_live
node_live -->|"collects events"| node_external_sentry
node_live -.->|"sends alerts"| node_external_slack
node_live -->|"uses mappings"| node_vendor_adapters
node_operator -->|"uses tools"| node_mcp
node_mcp -->|"issues commands"| node_control_plane
node_operator -->|"manages credentials"| node_service_access
node_operator -->|"follows guidance"| node_setup
node_setup -->|"references runbook"| node_docs
node_operator -->|"manages documents"| node_documents_ui
node_documents_ui -->|"stores versions"| node_document_store

click node_soc "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/app.js"
click node_ui_contracts "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/connector-contract.js"
click node_signin "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/private-sign-in.js"
click node_documents_ui "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/document-library.js"
click node_admin_contract "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/administration-contract.js"
click node_private_app "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/private-application.js"
click node_auth "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/private-auth.js"
click node_control_plane "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-control-plane.js"
click node_runtime "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-runtime.js"
click node_admin_runtime "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-administration-runtime.js"
click node_admin_store "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-administration-store.js"
click node_ingest_contract "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/ingest-contract.js"
click node_reference_pages "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-pages.js"
click node_reference_store "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-store.js"
click node_coverage "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/integration-coverage.js"
click node_sender "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/integration-client.js"
click node_vendor_import "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/vendor-import.js"
click node_vendor_adapters "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/vendor-adapters.js"
click node_scanner "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/scanner-ingest.js"
click node_live "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/live-monitoring.js"
click node_mcp "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/agent-mcp.js"
click node_service_access "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/service-access.js"
click node_setup "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/setup-assistance.js"
click node_docs "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/technical-docs.js"
click node_document_store "https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/document-store.js"

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_soc,node_ui_contracts,node_signin,node_documents_ui toneBlue
class node_admin_contract,node_private_app,node_auth,node_control_plane,node_runtime,node_admin_runtime,node_admin_store toneAmber
class node_ingest_contract,node_reference_pages,node_reference_store,node_coverage toneMint
class node_sender,node_vendor_import,node_vendor_adapters,node_scanner,node_live toneRose
class node_mcp,node_service_access,node_setup,node_docs,node_document_store,node_operator,node_external_sentry,node_external_slack toneIndigo
```

## Components

### Operator interface

- [SOC interface](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/app.js): `public/app.js`
- [UI contracts](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/connector-contract.js): `public/connector-contract.js`
- [Private sign-in](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/private-sign-in.js): `public/private-sign-in.js`
- [Documents library](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/document-library.js): `public/document-library.js`

### Control and administration

- [Administration contract](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/administration-contract.js): `public/administration-contract.js`
- [Private application](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/private-application.js): `server/private-application.js`
- [Authentication](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/private-auth.js): `server/private-auth.js`
- [Reference control plane](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-control-plane.js): `server/reference-control-plane.js`
- [Connector runtime](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-runtime.js): `server/reference-runtime.js`
- [Administration runtime](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-administration-runtime.js): `server/reference-administration-runtime.js`
- [Administration store](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-administration-store.js): `server/reference-administration-store.js`

### Ingestion and observation

- [Ingest contract](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/ingest-contract.js): `tools/ingest-contract.js`
- [SOC page models](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-pages.js): `server/reference-pages.js`
- [Reference data store](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/reference-store.js): `server/reference-store.js`
- [Observation coverage](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/integration-coverage.js): `server/integration-coverage.js`

### Collectors and integrations

- [Integration sender](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/integration-client.js): `tools/integration-client.js`
- [Vendor imports](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/vendor-import.js): `public/vendor-import.js`
- [Vendor adapters](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/vendor-adapters.js): `tools/vendor-adapters.js`
- [Trivy report import](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/scanner-ingest.js): `server/scanner-ingest.js`
- [Live monitoring](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/live-monitoring.js): `server/live-monitoring.js`

### Operator support

- [Agent MCP](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/tools/agent-mcp.js): `tools/agent-mcp.js`
- [Service access](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/service-access.js): `server/service-access.js`
- [Setup assistance](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/setup-assistance.js): `public/setup-assistance.js`
- [Technical reference](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/public/technical-docs.js): `public/technical-docs.js`
- [Document store](https://github.com/bulwark-black/bb-soc-skeleton/blob/main/server/document-store.js): `server/document-store.js`

### Other components

- **Operator**
- **Sentry Cloud**
- **Slack**

## Connections

- Operator → Private sign-in: signs in (evidence: `README.md`)
- Private sign-in → Private application: opens session (evidence: `README.md`)
- Private application → Authentication: authenticates (evidence: `README.md`)
- Operator → SOC interface: uses (evidence: `README.md`)
- SOC interface → UI contracts: uses contracts (evidence: `README.md`)
- Private application → Reference control plane: serves control plane (evidence: `README.md`)
- Reference control plane → Connector runtime: delegates connector actions (evidence: `server/reference-control-plane.js`)
- Reference control plane → Administration runtime: delegates administration (evidence: `server/reference-control-plane.js`)
- Administration runtime → Administration store: uses persistence (evidence: `server/reference-administration-runtime.js`)
- Administration runtime → Administration contract: validates with (evidence: `server/reference-administration-runtime.js`)
- Connector runtime → Ingest contract: validates batches (evidence: `server/reference-runtime.js`)
- Connector runtime → Reference data store: persists state (evidence: `server/reference-runtime.js`)
- Connector runtime → UI contracts: validates with (evidence: `server/reference-runtime.js`)
- SOC interface → SOC page models: views SOC pages (evidence: `README.md`)
- SOC page models → Observation coverage: builds observation views (evidence: `server/reference-pages.js`)
- Operator → Integration sender: sends normalized records (evidence: `README.md`)
- Integration sender → Ingest contract: prepares batches (evidence: `tools/integration-client.js`)
- Operator → Vendor imports: imports exports (evidence: `README.md`)
- Vendor imports → Vendor adapters: normalizes events (evidence: `README.md`)
- Vendor adapters → Ingest contract: validates records (evidence: `tools/vendor-adapters.js`)
- Operator → Trivy report import: submits report (evidence: `README.md`)
- Trivy report import → Ingest contract: validates batch (evidence: `server/scanner-ingest.js`)
- Operator → Live monitoring: configures collector (evidence: `README.md`)
- Live monitoring → Sentry Cloud: collects events (evidence: `README.md`)
- Live monitoring → Slack: sends alerts (evidence: `README.md`)
- Live monitoring → Vendor adapters: uses mappings (evidence: `server/live-monitoring.js`)
- Operator → Agent MCP: uses tools (evidence: `README.md`)
- Agent MCP → Reference control plane: issues commands (evidence: `tools/agent-mcp.js`)
- Operator → Service access: manages credentials (evidence: `README.md`)
- Operator → Setup assistance: follows guidance (evidence: `README.md`)
- Setup assistance → Technical reference: references runbook (evidence: `README.md`)
- Operator → Documents library: manages documents (evidence: `README.md`)
- Documents library → Document store: stores versions (evidence: `README.md`)
