# phantomcyber/splunk-soar-sdk architecture

> Architecture diagram of the GitHub repository phantomcyber/splunk-soar-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phantomcyber/splunk-soar-sdk
- Repository: https://github.com/phantomcyber/splunk-soar-sdk

## Overview

1. **Repository purpose**
   - This is the **Splunk SOAR SDK**, a Python library and command-line tool for building, converting, packaging, and testing Splunk SOAR apps.
   - The main runtime package lives in `src/soar_sdk`; the repo also includes documentation, templates, tests, CI workflows, and a small separate MCP server under `mcp_server/`.

2. **Primary product boundary: the SDK package**
   - `src/soar_sdk` is the core distribution.
   - It exposes the app authoring surface (`App`, decorators, asset/action/params models), runtime integration with Splunk SOAR, and supporting utilities for auth, rendering, packaging, and CLI workflows.
   - The README example reflects the intended architecture: app authors define an asset model, register actions with decorators, then run `app.cli()` to use the SDK tooling.

3. **App authoring and runtime model**
   - `app.py`, `asset.py`, `params.py`, `action_results.py`, `models/*`, and `input_spec.py` define the typed object model used by app developers.
   - `actions_manager.py`, `abstract.py`, and `app_client.py` bridge user-defined app code to the SOAR execution environment.
   - `async_utils.py`, `paths.py`, `field_utils.py`, `types.py`, and `compat.py` provide supporting runtime behavior and cross-version helpers.

4. **Decorator-driven registration layer**
   - `src/soar_sdk/decorators` is the main declaration mechanism for app behavior.
   - Decorators such as `action`, `test_connectivity`, `on_poll`, `on_es_poll`, `webhook`, `view_handler`, and `make_request` annotate user functions and turn them into SDK-managed app endpoints or execution hooks.
   - This is the central “user code to framework metadata” boundary.

5. **Metadata and manifest generation**
   - `src/soar_sdk/meta` models the app and its declared capabilities in a normalized internal form.
   - Subpackages under `meta/dependencies` handle dependency resolution and lockfile/package source interpretation, which is important for converting app projects and generating deployable metadata.
   - The CLI manifest tools under `src/soar_sdk/cli/manifests` serialize and deserialize app manifest data, process notices, and support conversion workflows.

6. **Authentication and API integration**
   - `src/soar_sdk/auth` contains the auth flows, client factories, token/certificate models, and `httpx` integration used for SOAR and related API authentication.
   - `src/soar_sdk/apis` exposes typed client wrappers for platform resources such as `artifact`, `container`, and `vault`.
   - These modules form the outbound integration layer from an app to Splunk SOAR services.

7. **Webhooks, polling, and event-driven execution**
   - `src/soar_sdk/webhooks` handles webhook routing and webhook models.
   - The poll-related decorators in `decorators/on_poll.py` and `decorators/on_es_poll.py` define scheduled or event-stream driven ingestion paths.
   - This separates reactive ingress mechanisms from action execution, which matters for diagramming how external events enter the app.

8. **Custom views and templated UI rendering**
   - `src/soar_sdk/views` and `src/soar_sdk/templates` implement the app’s custom-view subsystem.
   - The view parser, component registry, template renderer, and template filters translate SDK view definitions into HTML/UI fragments.
   - Built-in components like the pie chart live under `views/components`, while reusable base templates live under `templates/base` and widget templates under `templates/widgets`.

9. **Code generation and app scaffolding**
   - `src/soar_sdk/code_renderers` generates starter files and config for new apps and conversions, including `pyproject.toml`, `.pre-commit-config.yaml`, app/action/asset code, and supporting templates.
   - `src/soar_sdk/cli/init` is the scaffolding entrypoint, while `src/soar_sdk/app_templates/basic_app` provides a ready-made starter project layout.
   - This is the main “project creation” boundary between the SDK and the user’s generated app repository.

10. **CLI as the operational front door**
   - `src/soar_sdk/cli/cli.py` is the top-level `soarapps` command.
   - Subcommands are organized by purpose: `init` for project creation, `convert`/manifest tooling for migration and metadata handling, `package` for packaging-related tasks, and `test` for SDK-assisted validation.
   - `app_cli_runner.py` and `cli/utils.py` support execution of app-side flows from the command line.

11. **Legacy compatibility and shims**
   - `src/soar_sdk/shims/phantom` and `src/soar_sdk/shims/phantom_common` provide compatibility with older Phantom/BaseConnector-style apps and internal interfaces.
   - These shims are crucial for the conversion story: they let the SDK understand or emulate older app structures during migration and packaging.

12. **Extras and specialized processors**
   - `src/soar_sdk/extras/email` adds email parsing/processing support as a focused feature area.
   - This is a distinct functional subsystem, not part of the core app lifecycle, and likely supports specialized action inputs or helper workflows.

13. **MCP test assistant sidecar**
   - `mcp_server/` is a separate Python package containing `soar_test_assistant`.
   - It appears to provide a test/analyzer service used for validation or local assistance, with its own `pyproject.toml`, tests, and install script.
   - Architecturally, treat it as an auxiliary tool rather than part of the main SDK runtime.

14. **Tests, fixtures, and example app topology**
   - `tests/` is extensive and mirrors the SDK surface: unit tests for core models, CLI, auth, views, webhooks, renderers, and integration tests against example apps.
   - `tests/example_app*` contains realistic app projects used to validate conversion, packaging, webhook support, OAuth, and state handling.
   - This test layout is useful for architecture diagrams because it reveals the intended boundaries: core SDK, generated app projects, and runtime integration with Splunk SOAR.

15. **Docs and release automation**
   - `docs/` is the authoritative design and user-facing architecture documentation for app structure, authentication, custom views, CLI, and getting started flows.
   - `.github/workflows` covers code quality, integration tests, docs generation, semantic release, and commit hygiene; `.releaserc` and `commitlint.config.js` support automated versioning and release management.
   - These don’t affect runtime behavior, but they do define the repository’s delivery pipeline and quality gates.

Main entry points: [`src/soar_sdk/actions_manager.py`](https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/actions_manager.py) (Runtime bridge), [`src/soar_sdk/meta`](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/meta) (Metadata), [`src/soar_sdk`](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk) (soar_sdk), [`src/soar_sdk/cli/cli.py`](https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/cli/cli.py) (soarapps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core_sdk["SDK core"]
  node_sdk_root["soar_sdk<br/>python package"]
  node_app_model["App model<br/>authoring API<br/>[app.py]"]
  node_decorators["Decorators<br/>declaration layer"]
  node_runtime_bridge["Runtime bridge<br/>execution bridge<br/>[actions_manager.py]"]
  node_metadata["Metadata<br/>manifest model"]
  node_deps["Dependencies<br/>resolver"]
  node_auth["Auth"]
  node_apis["API clients<br/>platform clients"]
  node_webhooks["Webhooks<br/>ingress router"]
  node_extras_email["Email extras<br/>feature module"]
end

subgraph group_cli["CLI"]
  node_cli_front["soarapps<br/>cli entrypoint<br/>[cli.py]"]
  node_cli_init["Init<br/>subcommand"]
  node_cli_manifests["Manifests<br/>subcommand"]
  node_cli_package["Package<br/>subcommand"]
  node_cli_test["Test<br/>subcommand"]
end

subgraph group_ui["Views & templates"]
  node_views["Views<br/>ui renderer"]
  node_templates["Templates<br/>ui assets"]
end

subgraph group_compat["Compatibility"]
  node_shims["Phantom shims<br/>compat layer"]
end

subgraph group_aux["Auxiliary tools"]
  node_renderers["Code renderers<br/>scaffolding"]
  node_mcp_server["MCP assistant<br/>sidecar service"]
end

subgraph group_tests["Test fixtures"]
  node_example_apps["Example apps<br/>fixture apps"]
end

node_sdk_root -->|"exposes"| node_app_model
node_sdk_root -->|"exposes"| node_decorators
node_sdk_root -->|"hosts"| node_runtime_bridge
node_sdk_root -->|"models"| node_metadata
node_metadata -->|"resolves"| node_deps
node_decorators -->|"describes"| node_metadata
node_app_model -->|"invoked by"| node_runtime_bridge
node_runtime_bridge -->|"uses"| node_auth
node_runtime_bridge -->|"calls"| node_apis
node_runtime_bridge -->|"receives"| node_webhooks
node_webhooks -->|"registered by"| node_decorators
node_decorators -->|"declares"| node_views
node_views -->|"renders with"| node_templates
node_renderers -->|"powers"| node_cli_init
node_cli_front -->|"dispatches"| node_cli_init
node_cli_front -->|"dispatches"| node_cli_manifests
node_cli_front -->|"dispatches"| node_cli_package
node_cli_front -->|"dispatches"| node_cli_test
node_cli_manifests -->|"serializes"| node_metadata
node_shims -.->|"compatibility"| node_runtime_bridge
node_shims -.->|"migrates"| node_metadata
node_extras_email -->|"extends"| node_app_model
node_mcp_server -.->|"assists"| node_cli_test
node_example_apps -.->|"validated by"| node_renderers

click node_sdk_root "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk"
click node_app_model "https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/app.py"
click node_decorators "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/decorators"
click node_runtime_bridge "https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/actions_manager.py"
click node_metadata "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/meta"
click node_deps "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/meta/dependencies"
click node_auth "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/auth"
click node_apis "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/apis"
click node_webhooks "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/webhooks"
click node_views "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/views"
click node_templates "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/templates"
click node_renderers "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/code_renderers"
click node_cli_front "https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/cli/cli.py"
click node_cli_init "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/init"
click node_cli_manifests "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/manifests"
click node_cli_package "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/package"
click node_cli_test "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/test"
click node_shims "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/shims"
click node_extras_email "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/extras/email"
click node_mcp_server "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/mcp_server"
click node_example_apps "https://github.com/phantomcyber/splunk-soar-sdk/tree/main/tests/example_app"

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_sdk_root,node_app_model,node_decorators,node_runtime_bridge,node_metadata,node_deps,node_auth,node_apis,node_webhooks,node_extras_email toneBlue
class node_cli_front,node_cli_init,node_cli_manifests,node_cli_package,node_cli_test toneAmber
class node_views,node_templates toneMint
class node_shims toneRose
class node_renderers,node_mcp_server toneIndigo
class node_example_apps toneTeal
```

## Components

### SDK core

Primary Python package for app authoring, runtime integration, and metadata generation.

- [soar_sdk](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk): python package · Core distribution boundary for the SDK. · `src/soar_sdk`
- [App model](https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/app.py): authoring API · Typed app, asset, params, action results, and input specification objects. · `src/soar_sdk/app.py`
- [Decorators](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/decorators): declaration layer · Action, connectivity, polling, webhook, view, and request decorators that register app behavior. · `src/soar_sdk/decorators`
- [Runtime bridge](https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/actions_manager.py): execution bridge · Adapts user app code to the SOAR runtime and action execution model. · `src/soar_sdk/actions_manager.py`
- [Metadata](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/meta): manifest model · Normalized app, action, webhook, and dependency metadata used for packaging and conversion. · `src/soar_sdk/meta`
- [Dependencies](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/meta/dependencies): resolver · Lockfile, package source, wheel, and dependency interpretation utilities. · `src/soar_sdk/meta/dependencies`
- [Auth](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/auth): auth client · Authentication flows, token and certificate models, and httpx integration for SOAR APIs. · `src/soar_sdk/auth`
- [API clients](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/apis): platform clients · Typed wrappers for platform resources such as artifacts, containers, and vault. · `src/soar_sdk/apis`
- [Webhooks](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/webhooks): ingress router · Webhook models and routing for event-driven app entrypoints. · `src/soar_sdk/webhooks`
- [Email extras](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/extras/email): feature module · Email parsing and processing support for specialized workflows. · `src/soar_sdk/extras/email`

### CLI

Command-line entrypoints and subcommands for init, manifest handling, packaging, and testing.

- [soarapps](https://github.com/phantomcyber/splunk-soar-sdk/blob/main/src/soar_sdk/cli/cli.py): cli entrypoint · Top-level CLI front door for SDK operations. · `src/soar_sdk/cli/cli.py`
- [Init](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/init): subcommand · Project creation and scaffolding wizard. · `src/soar_sdk/cli/init`
- [Manifests](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/manifests): subcommand · Manifest serialization, deserialization, notices, and conversion helpers. · `src/soar_sdk/cli/manifests`
- [Package](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/package): subcommand · Packaging-related CLI operations and utilities. · `src/soar_sdk/cli/package`
- [Test](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/cli/test): subcommand · SDK-assisted validation and test execution from the command line. · `src/soar_sdk/cli/test`

### Views & templates

Custom view rendering, template parsing, and reusable UI fragments.

- [Views](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/views): ui renderer · Custom view parsing, component registry, filters, and template rendering. · `src/soar_sdk/views`
- [Templates](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/templates): ui assets · Base, component, and widget templates used by the custom-view subsystem. · `src/soar_sdk/templates`

### Compatibility

Legacy Phantom/BaseConnector shims and migration helpers.

- [Phantom shims](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/shims): compat layer · Compatibility wrappers for older Phantom/BaseConnector-style apps and migration support. · `src/soar_sdk/shims`

### Auxiliary tools

Sidecar MCP assistant and generated app scaffolding.

- [Code renderers](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/src/soar_sdk/code_renderers): scaffolding · Generates app files and project config for new apps and conversion workflows. · `src/soar_sdk/code_renderers`
- [MCP assistant](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/mcp_server): sidecar service · Auxiliary test assistant service packaged separately from the SDK runtime. · `mcp_server`

### Test fixtures

Representative example apps used to validate the SDK surface and conversion flows.

- [Example apps](https://github.com/phantomcyber/splunk-soar-sdk/tree/main/tests/example_app): fixture apps · Representative app projects used by tests to validate conversion, packaging, auth, webhooks, and state handling. · `tests/example_app`

## Connections

- soar_sdk → App model: exposes · The package exports the primary app authoring surface.
- soar_sdk → Decorators: exposes · Decorator APIs are part of the main public surface.
- soar_sdk → Runtime bridge: hosts · Core runtime coordination lives inside the SDK package.
- soar_sdk → Metadata: models · Metadata is derived from the app and decorator declarations.
- Metadata → Dependencies: resolves · Dependency metadata feeds lockfile and package-source handling.
- Decorators → Metadata: describes · Decorators turn user functions into normalized capability metadata.
- App model → Runtime bridge: invoked by · App objects are executed through the runtime bridge and action manager.
- Runtime bridge → Auth: uses · Runtime integrations rely on authentication flows and HTTP clients.
- Runtime bridge → API clients: calls · App execution talks to platform resources through typed API clients.
- Runtime bridge → Webhooks: receives · Webhook and poll entrypoints feed events into app execution.
- Webhooks → Decorators: registered by · Webhook-related decorators declare inbound event handlers.
- Decorators → Views: declares · View handlers and custom view declarations bind into the UI subsystem.
- Views → Templates: renders with · View parsing and rendering use shared HTML/template assets.
- Code renderers → Init: powers · Scaffolding generation is driven from the init workflow.
- soarapps → Init: dispatches · Top-level CLI routes init commands to the scaffolding subcommand.
- soarapps → Manifests: dispatches · Top-level CLI routes manifest tooling to the manifests subcommand.
- soarapps → Package: dispatches · Top-level CLI routes packaging tasks to the package subcommand.
- soarapps → Test: dispatches · Top-level CLI routes validation tasks to the test subcommand.
- Manifests → Metadata: serializes · Manifest tooling reads and writes the normalized metadata model.
- Phantom shims → Runtime bridge: compatibility · Legacy interfaces are adapted to the modern SDK runtime.
- Phantom shims → Metadata: migrates · Shims help conversion and packaging understand older app structures.
- Email extras → App model: extends · Email processing provides specialized data handling for app workflows.
- MCP assistant → Test: assists · The sidecar service appears to support analysis and local test assistance.
- Example apps → Code renderers: validated by · Representative generated apps exercise scaffolding and packaging behavior.