# securityreviewai/securityreview-kit architecture

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

- Interactive diagram: https://gitdiagram.com/securityreviewai/securityreview-kit
- Repository: https://github.com/securityreviewai/securityreview-kit

## Overview

1. **What this repo is**
   - This is a Node.js CLI package that bootstraps the SRAI security-review MCP setup into a workspace.
   - Its job is not to run the security review itself, but to install IDE/CLI-specific configuration so assistants like Cursor, Claude Code, VS Code Copilot, Windsurf, Codex, Gemini CLI, and Antigravity consult security guidance before code generation.

2. **Top-level architecture**
   - The executable entrypoint is `bin/securityreview-kit.js`, which hands control to `src/cli.js`.
   - `src/cli.js` dispatches into three user-facing commands: `init`, `status`, and `switch-project`.
   - The rest of the code is split into two main subsystems:
     - **Generators**: create target-specific MCP configs, rules, skills, hooks, and command files.
     - **Utilities**: filesystem, detection, install, and profiling helpers.

3. **Primary workflow: `init`**
   - `src/commands/init.js` is the orchestration layer.
   - It gathers target selection, SRAI API settings, and optional profiling flags, then coordinates installation of:
     - MCP server config for the selected target(s)
     - Workspace rules and supporting files
   - The install is designed to be idempotent: it updates existing workspace files rather than duplicating content.

4. **Project selection and SRAI API integration**
   - When MCP setup is enabled, the tool fetches available projects from the SRAI platform using `GET /api/projects/` with a bearer token.
   - The selected project name is injected into installed rule content so the IDE/CLI instructions are tied to one SRAI project.
   - This data flow matters architecturally: SRAI API → interactive project selection → generated workspace instructions.

5. **Target-specific generation**
   - The `src/generators/mcp/` directory contains adapters for each supported tool: `claude`, `codex`, `cursor`, `gemini`, `vscode`, and `windsurf`.
   - These generators produce the target’s MCP configuration file in its expected location, for example:
     - `.cursor/mcp.json`
     - `.mcp.json`
     - `.vscode/mcp.json`
     - `.windsurf/mcp_config.json`
     - `.codex/config.toml`
     - `.gemini/settings.json`
   - The key architectural boundary is that each target gets its own config format and path, but they all point to the same underlying `security-review-mcp` launch model.

6. **Workspace rules and assistant instructions**
   - `src/generators/rules/` contains target-specific rule emitters and shared content.
   - These write the assistant-facing guidance files into tool-specific locations such as:
     - `.cursor/rules/...`
     - `.claude/CLAUDE.md`
     - `.github/copilot-instructions.md`
     - `.windsurf/rules/...`
     - `.codex/AGENTS.md`
     - `GEMINI.md`
     - `.agents/rules/...`
   - Shared content lives in `content.md` and related templates, so the repository can reuse the same security policy narrative across different assistant ecosystems.

7. **Supporting assets: skills, commands, and hooks**
   - The repo doesn’t only install a single rule file; it also lays down auxiliary assets that shape assistant behavior.
   - Examples include:
     - Threat modelling skills under multiple tool-specific skill folders
     - `guardrails-init-profile.md` command content
     - `hooks.json` / session-policy files for tools that support hooks
   - These files form a second layer of enforcement around the main rule text, helping assistants follow the same security workflow consistently.

8. **Status and project switching**
   - `src/commands/status.js` inspects the current workspace and reports which target configurations are present.
   - `src/commands/switch-project.js` reuses the installed configuration but updates the mapped workspace rules to point to a different SRAI project.
   - This is a separate operational path from initial install: status is read-only, while switch-project is a targeted update of existing generated files.

9. **Profiling and guardrails subsystem**
   - The repo includes a profiling flow for generating or refining guardrails using bundled skills under `src/generators/rules/guardrails-profiler` and `guardrails-selection`.
   - `src/utils/guardrails-profiler-bundle.js` and `src/utils/profiler-agent.js` support running these profiler workflows.
   - The `init` command can optionally trigger profiling after setup, and it has target-specific login helpers for Claude, GitHub Copilot, and Codex.
   - Architecturally, this is an optional post-install pipeline that feeds on the installed workspace state.

10. **Cross-cutting utilities and boundaries**
   - `src/utils/fs-helpers.js`, `detect.js`, `constants.js`, and `ide-cli-install.js` handle filesystem writes, environment/tool detection, and installation mechanics.
   - `cursor-agent-path.js` and `cursor-cli-permissions.js` reflect tool-specific constraints for Cursor.
   - `src/utils/srai.js` centralizes SRAI-specific network or project-related behavior.
   - The repo’s boundary is clear: it reads and writes local workspace files, talks to the SRAI API when needed, and configures external IDE/CLI assistants to launch `security-review-mcp` via `npx`.

11. **How to think about the system diagram**
   - Put the CLI at the center, with three command flows branching out: initial install, status inspection, and project switching.
   - On one side, show target-specific generators writing into workspace locations.
   - On another, show the SRAI API as the source of project metadata used to parameterize rules.
   - If included, show the profiling subsystem as an optional downstream path that consumes the installed setup and produces guardrail/profile artifacts.

Main entry points: [`src/commands/init.js`](https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/init.js) (init), [`src/generators/mcp`](https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/mcp) (MCP generators), [`src/cli.js`](https://github.com/securityreviewai/securityreview-kit/blob/main/src/cli.js) (CLI router), [`src/commands/switch-project.js`](https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/switch-project.js) (switch project)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI flow"]
  node_bin_entry["bin script<br/>node entrypoint"]
  node_cli_main["CLI router<br/>command dispatcher<br/>[cli.js]"]
  node_cmd_init["init<br/>workspace install<br/>[init.js]"]
  node_cmd_status["status<br/>workspace inspect<br/>[status.js]"]
  node_cmd_switch["switch project<br/>workspace update<br/>[switch-project.js]"]
end

subgraph group_gen["Generators"]
  node_mcp_factory["MCP generators<br/>config adapters"]
  node_rule_factory["Rule generators<br/>instruction adapters"]
  node_claude_mcp["Claude MCP<br/>mcp adapter<br/>[claude.js]"]
  node_codex_mcp["Codex MCP<br/>mcp adapter<br/>[codex.js]"]
  node_cursor_mcp["Cursor MCP<br/>mcp adapter<br/>[cursor.js]"]
  node_gemini_mcp["Gemini MCP<br/>mcp adapter<br/>[gemini.js]"]
  node_vscode_mcp["VS Code MCP<br/>mcp adapter<br/>[vscode.js]"]
  node_windsurf_mcp["Windsurf MCP<br/>mcp adapter<br/>[windsurf.js]"]
  node_content_tpl["Shared content<br/>rule content<br/>[content.md]"]
  node_profile_assets["Profiler assets<br/>guardrails bundle"]
end

subgraph group_util["Utilities"]
  node_fs_install["Install helpers<br/>workspace writer<br/>[ide-cli-install.js]"]
  node_detect_util["Detect tools<br/>environment detect<br/>[detect.js]"]
  node_srai_util["SRAI client<br/>api helper<br/>[srai.js]"]
  node_profiler_util["Profiler runtime<br/>profile runner<br/>[profiler-agent.js]"]
end

subgraph group_ext["External systems"]
  node_srai_api[("SRAI API<br/>project metadata")]
  node_workspace_targets["Workspace tools<br/>assistant runtimes"]
end

node_bin_entry -->|"start"| node_cli_main
node_cli_main -->|"init"| node_cmd_init
node_cli_main -->|"status"| node_cmd_status
node_cli_main -->|"switch"| node_cmd_switch
node_cmd_init -->|"detect"| node_detect_util
node_cmd_init -->|"projects"| node_srai_util
node_srai_util -->|"GET /api/projects"| node_srai_api
node_cmd_init -->|"generate"| node_mcp_factory
node_cmd_init -->|"generate"| node_rule_factory
node_mcp_factory -->|"adapter"| node_claude_mcp
node_mcp_factory -->|"adapter"| node_codex_mcp
node_mcp_factory -->|"adapter"| node_cursor_mcp
node_mcp_factory -->|"adapter"| node_gemini_mcp
node_mcp_factory -->|"adapter"| node_vscode_mcp
node_mcp_factory -->|"adapter"| node_windsurf_mcp
node_rule_factory -->|"shared text"| node_content_tpl
node_rule_factory -->|"bundles"| node_profile_assets
node_cmd_init -->|"write"| node_fs_install
node_fs_install -->|"configure"| node_workspace_targets
node_cmd_status -->|"inspect"| node_detect_util
node_cmd_switch -->|"remap"| node_srai_util
node_cmd_switch -->|"update"| node_fs_install
node_cmd_init -.->|"optional profile"| node_profiler_util
node_profiler_util -->|"uses"| node_profile_assets

click node_bin_entry "https://github.com/securityreviewai/securityreview-kit/blob/main/bin/securityreview-kit.js"
click node_cli_main "https://github.com/securityreviewai/securityreview-kit/blob/main/src/cli.js"
click node_cmd_init "https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/init.js"
click node_cmd_status "https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/status.js"
click node_cmd_switch "https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/switch-project.js"
click node_mcp_factory "https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/mcp"
click node_rule_factory "https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/rules"
click node_claude_mcp "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/claude.js"
click node_codex_mcp "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/codex.js"
click node_cursor_mcp "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/cursor.js"
click node_gemini_mcp "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/gemini.js"
click node_vscode_mcp "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/vscode.js"
click node_windsurf_mcp "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/windsurf.js"
click node_content_tpl "https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/rules/content.md"
click node_profile_assets "https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/rules/guardrails-profiler"
click node_fs_install "https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/ide-cli-install.js"
click node_detect_util "https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/detect.js"
click node_srai_util "https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/srai.js"
click node_profiler_util "https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/profiler-agent.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_bin_entry,node_cli_main,node_cmd_init,node_cmd_status,node_cmd_switch toneBlue
class node_mcp_factory,node_rule_factory,node_claude_mcp,node_codex_mcp,node_cursor_mcp,node_gemini_mcp,node_vscode_mcp,node_windsurf_mcp,node_content_tpl,node_profile_assets toneAmber
class node_fs_install,node_detect_util,node_srai_util,node_profiler_util toneMint
class node_srai_api,node_workspace_targets toneRose
```

## Components

### CLI flow

Entry points and user-facing commands.

- [bin script](https://github.com/securityreviewai/securityreview-kit/blob/main/bin/securityreview-kit.js): node entrypoint · Package executable that hands off to the main CLI. · `bin/securityreview-kit.js`
- [CLI router](https://github.com/securityreviewai/securityreview-kit/blob/main/src/cli.js): command dispatcher · Dispatches to init, status, and switch-project commands. · `src/cli.js`
- [init](https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/init.js): workspace install · Orchestrates target selection, SRAI project selection, and installation. · `src/commands/init.js`
- [status](https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/status.js): workspace inspect · Reports which target configurations are present in the workspace. · `src/commands/status.js`
- [switch project](https://github.com/securityreviewai/securityreview-kit/blob/main/src/commands/switch-project.js): workspace update · Updates generated workspace rules to point at a different SRAI project. · `src/commands/switch-project.js`

### Generators

Target-specific installers for MCP configs, rules, skills, and supporting files.

- [MCP generators](https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/mcp): config adapters · Builds tool-specific MCP launch/config files for supported assistants. · `src/generators/mcp`
- [Rule generators](https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/rules): instruction adapters · Builds tool-specific workspace guidance and supporting rule files. · `src/generators/rules`
- [Claude MCP](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/claude.js): mcp adapter · Generates Claude-specific MCP configuration. · `src/generators/mcp/claude.js`
- [Codex MCP](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/codex.js): mcp adapter · Generates Codex-specific MCP configuration. · `src/generators/mcp/codex.js`
- [Cursor MCP](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/cursor.js): mcp adapter · Generates Cursor-specific MCP configuration. · `src/generators/mcp/cursor.js`
- [Gemini MCP](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/gemini.js): mcp adapter · Generates Gemini-specific MCP configuration. · `src/generators/mcp/gemini.js`
- [VS Code MCP](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/vscode.js): mcp adapter · Generates VS Code-specific MCP configuration. · `src/generators/mcp/vscode.js`
- [Windsurf MCP](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/mcp/windsurf.js): mcp adapter · Generates Windsurf-specific MCP configuration. · `src/generators/mcp/windsurf.js`
- [Shared content](https://github.com/securityreviewai/securityreview-kit/blob/main/src/generators/rules/content.md): rule content · Reusable security guidance and templates shared across targets. · `src/generators/rules/content.md`
- [Profiler assets](https://github.com/securityreviewai/securityreview-kit/tree/main/src/generators/rules/guardrails-profiler): guardrails bundle · Bundled guardrails profiler and selection skills used for optional post-install profiling. · `src/generators/rules/guardrails-profiler`

### Utilities

Shared helpers for detection, installation, filesystem, and profiling.

- [Install helpers](https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/ide-cli-install.js): workspace writer · Applies idempotent filesystem updates into the workspace. · `src/utils/ide-cli-install.js`
- [Detect tools](https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/detect.js): environment detect · Identifies available targets and workspace capabilities. · `src/utils/detect.js`
- [SRAI client](https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/srai.js): api helper · Centralizes SRAI-related project and network behavior. · `src/utils/srai.js`
- [Profiler runtime](https://github.com/securityreviewai/securityreview-kit/blob/main/src/utils/profiler-agent.js): profile runner · Supports running guardrails profiling workflows after installation. · `src/utils/profiler-agent.js`

### External systems

Workspace targets and the SRAI platform.

- **SRAI API**: project metadata · Source of available projects used to parameterize installed guidance.
- **Workspace tools**: assistant runtimes · Local IDE/CLI assistants whose config and instructions are generated.

## Connections

- bin script → CLI router: start · Executable entrypoint invokes the CLI router.
- CLI router → init: init · Routes to workspace bootstrapping.
- CLI router → status: status · Routes to workspace inspection.
- CLI router → switch project: switch · Routes to project remapping.
- init → Detect tools: detect · Finds available assistant targets and capabilities.
- init → SRAI client: projects · Fetches project metadata for selection.
- SRAI client → SRAI API: GET /api/projects · Reads available projects from the platform.
- init → MCP generators: generate · Builds target-specific MCP config files.
- init → Rule generators: generate · Builds assistant guidance files and supporting assets.
- MCP generators → Claude MCP: adapter · Claude MCP config generation.
- MCP generators → Codex MCP: adapter · Codex MCP config generation.
- MCP generators → Cursor MCP: adapter · Cursor MCP config generation.
- MCP generators → Gemini MCP: adapter · Gemini MCP config generation.
- MCP generators → VS Code MCP: adapter · VS Code MCP config generation.
- MCP generators → Windsurf MCP: adapter · Windsurf MCP config generation.
- Rule generators → Shared content: shared text · Reuses common security guidance across assistants.
- Rule generators → Profiler assets: bundles · Includes guardrails profiling and selection assets.
- init → Install helpers: write · Applies idempotent workspace updates.
- Install helpers → Workspace tools: configure · Writes config and instructions for local assistants.
- status → Detect tools: inspect · Checks installed target configuration in the workspace.
- switch project → SRAI client: remap · Updates installed rules to a different SRAI project.
- switch project → Install helpers: update · Rewrites the generated workspace files in place.
- init → Profiler runtime: optional profile · Can trigger guardrails profiling after setup.
- Profiler runtime → Profiler assets: uses · Runs bundled profiler workflows and skills.