# francescostabile/numasec architecture

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

- Interactive diagram: https://gitdiagram.com/francescostabile/numasec
- Repository: https://github.com/francescostabile/numasec

## Overview

1. **Repository shape**
   - This is a Bun-first TypeScript monorepo. The main product lives in `packages/numasec`, with supporting packages for a public SDK (`packages/sdk`), reusable shared utilities (`packages/shared`), and plugin authoring/runtime pieces (`packages/plugin`).
   - Build/test/release is organized around Bun, Turbo, and GitHub Actions, with package-local workflows rather than a single root app.

2. **Primary runtime: the terminal security agent**
   - `packages/numasec` is the actual product: a command-line security agent with a TUI, command palette, and session/operation management.
   - The operator enters through CLI commands, then spends most of the time in the TUI under `src/cli/cmd/tui`, which renders home/session views, dialogs, sidebars, and operation lenses.

3. **Core architectural idea: an “operation” as the source of truth**
   - The central domain object is the security operation. It carries target, scope, posture, agent choice, findings, evidence, replay artifacts, and report state.
   - The README’s “operation memory” and “finding lifecycle” are reflected in `src/core/operation`, `src/core/finding`-adjacent tool surfaces, `src/core/evidence`, `src/core/replay`, `src/core/plan`, and session code under `src/session`.

4. **Workflow engine: agents, runbooks, and tools**
   - `src/agent`, `src/tool`, and `src/command` define the user-facing security workflows.
   - Runbooks are the structured workflows that keep the agent from making random tool calls; tools are the callable actions; agents are posture bundles such as AppSec, Pentest, OSINT, and hacking/security variants.
   - This is the main control boundary: operator intent flows into an agent + runbook, which then chooses tools and writes back to the operation.

5. **Model/provider boundary**
   - The project is model-agnostic through `src/provider`, with provider adapters and SDKs for multiple LLM ecosystems.
   - The README explicitly names OpenAI, Anthropic, Google, xAI, Bedrock, OpenRouter, Ollama, Vercel AI Gateway, and OpenAI-compatible endpoints.
   - Session prompting is provider-aware: `src/session/prompt` contains provider/model-specific prompt templates, and `src/session/llm.ts` ties prompts to model execution.

6. **Execution layer: local shell, PTY, browser, HTTP, scanners**
   - Security work happens against the local machine and target environment through controlled execution surfaces: shell, PTY, browser automation, HTTP requests, scanners, and file operations.
   - These are implemented across `src/shell`, `src/pty`, `src/browser`, `src/scanner`, `src/file`, `src/git`, and the generic effect/runtime layer under `src/effect`.
   - The architecture assumes local tools are first-class and intentionally avoids replacing them.

7. **Permission, opsec, and autonomy as a safety boundary**
   - `src/permission`, `src/core/boundary`, and tool-level schema/evaluation code define what the agent is allowed to do.
   - The product positions this as “permissioned / auto execution,” meaning the system mediates tool calls rather than blindly executing every model request.
   - This is an important diagram boundary: model reasoning sits behind policy and execution gating.

8. **Persistence and evented state**
   - Durable state is stored in `src/storage` and the domain-specific SQL-backed modules such as `src/session/session.sql.ts`, `src/project/project.sql.ts`, `src/sync/event.sql.ts`, and migration history under `packages/numasec/migration`.
   - State appears to be event- and record-oriented rather than just flat files: sessions, operations, projects, sync events, observations, and findings are persisted so work can resume and be replayed.
   - The `docs/NUMASEC_FILE_FORMAT.md` and replay/share features suggest some derived artifacts are exported from this durable core.

9. **Knowledge and research subsystem**
   - `src/core/knowledge`, `src/tool/knowledge`, `src/tool/cve`, `src/core/methodology`, and bundled methodology data (`MITRE ATT&CK`, `PTES`, `WSTG`) form the cyber knowledge layer.
   - This subsystem enriches observed components and advisories with provenance-aware matching, applicability reasoning, and safe next actions.
   - It is intentionally separated from finding creation: intelligence can inform the operator without becoming a reportable claim by itself.

10. **Evidence, observation, finding, replay, report**
   - A major data flow is: tool output and observations → evidence store → findings → replay/report/share outputs.
   - `src/core/observation`, `src/core/evidence`, `src/core/replay`, `src/core/deliverable`, and report/share/remediation tools encode this lifecycle.
   - The architecture explicitly preserves weak signals, rejected claims, and proof semantics so report generation can be grounded in the actual operation history.

11. **Server, SDK, and multi-client access**
   - `src/server` and `src/mcp` expose runtime capabilities through server-side interfaces, including HTTP API pieces, middleware, proxying, and MCP/OAuth support.
   - `packages/sdk` contains generated client/server bindings for v1 and v2 APIs, so external tools or other apps can integrate with numasec programmatically.
   - This separates the interactive terminal product from machine-to-machine access.

12. **Plugin and extension model**
   - There is a dedicated plugin surface in `src/plugin` and a TUI plugin/runtime system in `src/cli/cmd/tui/plugin`.
   - The repo also includes a separate `packages/plugin` package, indicating external extension support and reusable plugin primitives.
   - Diagram-wise, this is a pluggable UI/action layer rather than part of the core security kernel.

13. **Supporting packages and tooling**
   - `packages/shared` holds cross-cutting filesystem, hashing, retry, slug, and effect helpers shared across packages.
   - Scripts under `script/` and `packages/numasec/script/` handle build, schema generation, migration checks, release, benchmarks, and packaging; Docker support exists for containerized use.
   - This matters architecturally because it shows the repo is designed for distributable CLI/software, not just a library or web service.

Main entry points: [`packages/numasec/src/tool/registry.ts`](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/tool/registry.ts) (Tools), [`packages/numasec/src/cli/cmd/tui/app.tsx`](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/cli/cmd/tui/app.tsx) (TUI), [`packages/numasec/src/session/session.ts`](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/session/session.ts) (Session), [`packages/numasec/src/server/server.ts`](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/server/server.ts) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_scripts["Build scripts<br/>bun/turbo automation<br/>[generate.ts]"]
  node_actions["CI/CD<br/>github workflows<br/>[ci.yml]"]
  node_shared["Shared utils<br/>cross-package helpers<br/>[hash.ts]"]
end

subgraph group_product["Numasec"]
  node_numasec_cli["CLI<br/>entrypoint<br/>[bootstrap.ts]"]
  node_numasec_tui["TUI<br/>interactive shell<br/>[app.tsx]"]
  node_numasec_session["Session<br/>conversation state<br/>[session.ts]"]
  node_numasec_operation[("Operation<br/>security domain<br/>[operation.ts]")]
  node_numasec_agent["Agent<br/>workflow policy<br/>[agent.ts]"]
  node_numasec_command["Runbooks<br/>workflow templates<br/>[command.ts]"]
  node_numasec_tool["Tools<br/>action registry<br/>[registry.ts]"]
  node_numasec_boundary{{"Policy gate<br/>permission/opsec<br/>[guard.ts]"}}
  node_numasec_provider["Providers<br/>model adapters<br/>[provider.ts]"]
  node_numasec_exec["Execution<br/>local runtime<br/>[runner.ts]"]
  node_numasec_storage[("Storage<br/>durable state<br/>[storage.ts]")]
  node_numasec_knowledge["Knowledge<br/>cyber intelligence<br/>[index.ts]"]
  node_numasec_evidence["Evidence<br/>claim lineage<br/>[store.ts]"]
  node_numasec_server["Server<br/>runtime api<br/>[server.ts]"]
end

subgraph group_sdk["SDK"]
  node_sdk_pkg["SDK pkg<br/>generated api client<br/>[index.ts]"]
end

subgraph group_plugins["Extensions"]
  node_numasec_plugin["Plugin runtime<br/>extension host<br/>[plugin.ts]"]
  node_plugin_pkg["Plugin pkg<br/>external plugin package<br/>[index.ts]"]
end

node_scripts -->|"uses helpers"| node_shared
node_actions -->|"runs"| node_scripts
node_numasec_cli -->|"opens"| node_numasec_tui
node_numasec_cli -->|"exposes"| node_numasec_server
node_numasec_tui -->|"drives"| node_numasec_session
node_numasec_tui -->|"renders"| node_numasec_operation
node_numasec_session -->|"executes"| node_numasec_provider
node_numasec_session -->|"selects"| node_numasec_agent
node_numasec_agent -->|"uses"| node_numasec_command
node_numasec_command -->|"invokes"| node_numasec_tool
node_numasec_tool -->|"gated by"| node_numasec_boundary
node_numasec_tool -->|"uses runtime"| node_numasec_exec
node_numasec_tool -->|"enriches"| node_numasec_knowledge
node_numasec_tool -->|"records"| node_numasec_evidence
node_numasec_evidence -->|"updates"| node_numasec_operation
node_numasec_operation -->|"persists"| node_numasec_storage
node_numasec_session -->|"persists"| node_numasec_storage
node_numasec_server -->|"reads/writes"| node_numasec_storage
node_numasec_server -->|"publishes api"| node_sdk_pkg
node_numasec_plugin -->|"extends"| node_plugin_pkg
node_numasec_tui -->|"hosts"| node_numasec_plugin
node_numasec_provider -->|"adapts"| node_sdk_pkg

click node_scripts "https://github.com/francescostabile/numasec/blob/main/script/generate.ts"
click node_actions "https://github.com/francescostabile/numasec/blob/main/.github/workflows/ci.yml"
click node_shared "https://github.com/francescostabile/numasec/blob/main/packages/shared/src/util/hash.ts"
click node_numasec_cli "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/cli/bootstrap.ts"
click node_numasec_tui "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/cli/cmd/tui/app.tsx"
click node_numasec_session "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/session/session.ts"
click node_numasec_operation "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/operation/operation.ts"
click node_numasec_agent "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/agent/agent.ts"
click node_numasec_command "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/command/command.ts"
click node_numasec_tool "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/tool/registry.ts"
click node_numasec_boundary "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/boundary/guard.ts"
click node_numasec_provider "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/provider/provider.ts"
click node_numasec_exec "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/effect/runner.ts"
click node_numasec_storage "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/storage/storage.ts"
click node_numasec_knowledge "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/knowledge/index.ts"
click node_numasec_evidence "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/evidence/store.ts"
click node_numasec_server "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/server/server.ts"
click node_numasec_plugin "https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/plugin/plugin.ts"
click node_plugin_pkg "https://github.com/francescostabile/numasec/blob/main/packages/plugin/src/index.ts"
click node_sdk_pkg "https://github.com/francescostabile/numasec/blob/main/packages/sdk/src/index.ts"

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_scripts,node_actions,node_shared toneBlue
class node_numasec_cli,node_numasec_tui,node_numasec_session,node_numasec_operation,node_numasec_agent,node_numasec_command,node_numasec_tool,node_numasec_boundary,node_numasec_provider,node_numasec_exec,node_numasec_storage,node_numasec_knowledge,node_numasec_evidence,node_numasec_server toneAmber
class node_sdk_pkg toneMint
class node_numasec_plugin,node_plugin_pkg toneRose
```

## Components

### Monorepo

Workspace-level build, release, and shared packages.

- [Build scripts](https://github.com/francescostabile/numasec/blob/main/script/generate.ts): bun/turbo automation · Repository-level build, generate, release, and versioning scripts. · `script/generate.ts`
- [CI/CD](https://github.com/francescostabile/numasec/blob/main/.github/workflows/ci.yml): github workflows · Automated build and release pipelines. · `.github/workflows/ci.yml`
- [Shared utils](https://github.com/francescostabile/numasec/blob/main/packages/shared/src/util/hash.ts): cross-package helpers · Common filesystem, hashing, retry, slug, and effect utilities. · `packages/shared/src/util/hash.ts`

### Numasec

Terminal security agent and its runtime surfaces.

- [CLI](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/cli/bootstrap.ts): entrypoint · Command entrypoint and top-level command routing. · `packages/numasec/src/cli/bootstrap.ts`
- [TUI](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/cli/cmd/tui/app.tsx): interactive shell · Terminal UI, routes, dialogs, and plugin-hosted views. · `packages/numasec/src/cli/cmd/tui/app.tsx`
- [Session](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/session/session.ts): conversation state · Session lifecycle, prompts, message history, compaction, and execution state. · `packages/numasec/src/session/session.ts`
- [Operation](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/operation/operation.ts): security domain · Source-of-truth operation state covering scope, posture, evidence, findings, and artifacts. · `packages/numasec/src/core/operation/operation.ts`
- [Agent](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/agent/agent.ts): workflow policy · Agent postures and prompt bundles that shape workflow behavior. · `packages/numasec/src/agent/agent.ts`
- [Runbooks](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/command/command.ts): workflow templates · Structured command and runbook templates for guided security work. · `packages/numasec/src/command/command.ts`
- [Tools](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/tool/registry.ts): action registry · Callable actions used by agents and runbooks to operate on targets and the local environment. · `packages/numasec/src/tool/registry.ts`
- [Policy gate](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/boundary/guard.ts): permission/opsec · Permission evaluation and autonomy boundaries for tool execution. · `packages/numasec/src/core/boundary/guard.ts`
- [Providers](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/provider/provider.ts): model adapters · Model/provider abstraction and provider-specific SDK integrations. · `packages/numasec/src/provider/provider.ts`
- [Execution](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/effect/runner.ts): local runtime · Shell, PTY, browser, scanner, file, git, and effect runtime surfaces. · `packages/numasec/src/effect/runner.ts`
- [Storage](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/storage/storage.ts): durable state · Database, SQL-backed persistence, storage schema, and migrations. · `packages/numasec/src/storage/storage.ts`
- [Knowledge](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/knowledge/index.ts): cyber intelligence · Methodology, NVD matching, and component knowledge enrichment. · `packages/numasec/src/core/knowledge/index.ts`
- [Evidence](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/core/evidence/store.ts): claim lineage · Observation, evidence, findings, replay, and deliverable generation pipeline. · `packages/numasec/src/core/evidence/store.ts`
- [Server](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/server/server.ts): runtime api · HTTP, middleware, proxying, MCP, and multi-client server interfaces. · `packages/numasec/src/server/server.ts`

### SDK

Generated programmatic client/server bindings.

- [SDK pkg](https://github.com/francescostabile/numasec/blob/main/packages/sdk/src/index.ts): generated api client · Generated v1/v2 SDK clients and server bindings for programmatic integration. · `packages/sdk/src/index.ts`

### Extensions

Plugin authoring and runtime surfaces.

- [Plugin runtime](https://github.com/francescostabile/numasec/blob/main/packages/numasec/src/plugin/plugin.ts): extension host · Plugin loading, metadata, shared helpers, and TUI plugin runtime. · `packages/numasec/src/plugin/plugin.ts`
- [Plugin pkg](https://github.com/francescostabile/numasec/blob/main/packages/plugin/src/index.ts): external plugin package · Reusable external plugin primitives and examples. · `packages/plugin/src/index.ts`

## Connections

- Build scripts → Shared utils: uses helpers · Workspace scripts share utility code.
- CI/CD → Build scripts: runs · CI orchestrates build and release scripts.
- CLI → TUI: opens · CLI enters the interactive terminal UI.
- CLI → Server: exposes · CLI also launches server and machine interfaces.
- TUI → Session: drives · The TUI reads and updates session state.
- TUI → Operation: renders · Operation-centric views and lenses are shown in the UI.
- Session → Providers: executes · Sessions call into provider-aware model execution.
- Session → Agent: selects · Session prompting is shaped by the active agent posture.
- Agent → Runbooks: uses · Agents rely on structured commands and runbooks.
- Runbooks → Tools: invokes · Runbooks and commands choose tools for workflow steps.
- Tools → Policy gate: gated by · Tool execution is mediated by permission and opsec policy.
- Tools → Execution: uses runtime · Tools reach shell, PTY, browser, scanner, file, and git surfaces.
- Tools → Knowledge: enriches · Knowledge tools add methodology and threat intelligence context.
- Tools → Evidence: records · Tool output is converted into observations, evidence, and findings.
- Evidence → Operation: updates · Evidence and findings write back into operation state.
- Operation → Storage: persists · Operations and related records are stored durably.
- Session → Storage: persists · Session history and state are stored durably.
- Server → Storage: reads/writes · Server endpoints serve persisted project, session, and sync data.
- Server → SDK pkg: publishes api · Server interfaces are mirrored by the generated SDK package.
- Plugin runtime → Plugin pkg: extends · The product plugin host connects to reusable plugin primitives.
- TUI → Plugin runtime: hosts · The TUI integrates plugin routes, slots, and keybinds.
- Providers → SDK pkg: adapts · Provider integrations reuse generated client/server bindings.