# safedep/vet architecture

> Architecture diagram of the GitHub repository safedep/vet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safedep/vet
- Repository: https://github.com/safedep/vet

## Overview

##### Project type and purpose
- This is a monolithic Go-based open-source CLI application (“vet”) with complementary server (“MCP Server”) and agent components.
- Purpose: enterprise-grade software supply-chain security—dependency scanning, malicious package detection, policy enforcement, SBOM support, reporting, and AI-driven query/analysis.

##### File structure to extract architectural layers
- **Entrypoints** (cmd/, main.go): CLI commands (`vet scan`, `vet query`, `vet server mcp`, `vet agent …`).
- **Core engine** (pkg/ + internal/ + connect.go): modules for reading inputs, parsing/manipulating SBOMs and code, policy evaluation, vulnerability & malware analysis, reporting, storage abstractions, telemetry.
- **Persistence** (ent/ + pkg/storage/ent_sqlite.go): SQLite via Ent ORM plus optional graph backends.
- **API definitions** (api/, gen/): Protocol Buffers & OpenAPI specs for inter-component & cloud communications.
- **Server** (mcp/): implements MCP server for streaming scan/query results over SSE or stdio.
- **Agents** (agent/): AI agents that consume MCP server streams and interact with LLMs.
- **External integration**: SafeDep Cloud (malware-analysis API), GitHub/GitLab, container registries, OSV, Scorecard, telemetry endpoints.

a. Main components
- **User interfaces**
- CLI Frontend (cmd/…)
- Agent Frontend (agent/)
- **Core Engine**
- Readers (pkg/readers)
- Parsers (pkg/parser)
- Analyzer & Policy Engine (pkg/analyzer, pkg/policy)
- Vulnerability/Malware Scanner (pkg/scanner + pkg/cloud)
- Reporter (pkg/reporter)
- **Persistence**
- Ent/SQLite (ent/, pkg/storage)
- **MCP Server** (mcp/)
- **External Services**
- SafeDep Cloud API
- GitHub/GitLab APIs
- Container registries
- OSV, Scorecard
- Telemetry endpoint
b. Relationships & data flows
1. **User → CLI**: user invokes `vet scan` or `vet server mcp`.
2. **CLI → Readers**: reads directory, manifest, SBOM, image.
3. **Readers → Parser**: transforms raw inputs into internal model.
4. **Parser → Analyzer/Policy**: computes usage evidence, applies CEL filters.
5. **Analyzer → Scanner**: calls local vulnerability DB or SafeDep Cloud for malware analysis.
6. **Scanner → Persistence**: stores scan data if query-mode enabled (`--json-dump-dir`) or into Ent/SQLite for MCP server.
7. **Persistence → MCP Server**: streams results on SSE or stdio.
8. **Reporter → User**: outputs console, JSON, SARIF, CSV, Markdown, SBOMs.
9. **Agent → MCP Server**: subscribes to SSE stream, calls LLM via agent/llm.go to generate reports or suggestions.
10. **Telemetry**: Core engine emits anonymized usage events to analytics endpoint.
c. Architectural patterns & design principles
- **Layered architecture**: clear separation of UI (CLI/agent), core engine (reader/parser/analyzer/scanner/reporter), persistence, server, external integrations.
- **Plug-in style extensibility**: readers, parsers, reporters, scanners as interchangeable modules.
- **Policy as code**: CEL expressions evaluated within policy engine.
- **Streaming server**: MCP server uses SSE/stdio for bi-directional streaming.
- **ORM abstraction**: Ent for relational storage; optional graph backends.
d. Key technologies & libraries
- Go modules; Cobra/Viper for CLI
- Protocol Buffers (gRPC) for API specs
- Ent ORM + SQLite
- CEL (Common Expression Language) for policies
- SafeDep Cloud HTTP API
- LLM integrations for AI agents

##### Detail
- Stage: input, normalization, analysis, storage, reporting, streaming, AI-driven queries.
- Don’t over-aggregate: show Readers vs. Parsers vs. Analyzers vs. Scanners vs. Reporters separately.
- Both local (SQLite/Ent) and remote (SafeDep Cloud, GitHub) interactions.
- Dual-mode operation: synchronous CLI pipelines vs. asynchronous MCP server streams.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User Interfaces"
        direction TB
        CLI["CLI Frontend"]:::ui
        Agent["Agent Frontend"]:::ui
    end

    %% Core Engine Pipeline
    subgraph "Core Engine Pipeline"
        direction TB
        Readers["Readers"]:::core
        Parsers["Parsers"]:::core
        Analyzer["Analyzer & Policy Engine"]:::core
        Scanner["Vulnerability/Malware Scanner"]:::core
        Reporter["Reporter"]:::core
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        EntDB["Ent/SQLite"]:::db
        GraphDB["Graph Backends"]:::db
    end

    %% Server
    MCP["MCP Server"]:::server

    %% API & Codegen
    subgraph "API Definitions & Codegen"
        direction TB
        API["API Specs"]:::api
        Gen["Generated Code"]:::api
    end

    %% Internal Support
    subgraph "Internal Support Services"
        direction TB
        Telemetry["Telemetry/Analytics"]:::internal
        Auth["Auth"]:::internal
        CmdFramework["CLI Command Framework"]:::internal
        UIHelpers["UI Helpers"]:::internal
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        SafeDep["SafeDep Cloud API"]:::external
        GitHub["GitHub/GitLab APIs"]:::external
        Registries["Container Registries"]:::external
        OSVScore["OSV & Scorecard"]:::external
        TelemetryEP["Telemetry Endpoint"]:::external
    end

    %% Data Flows
    CLI -->|"invoke scan/server"| Readers
    Readers -->|"read inputs"| Parsers
    Parsers -->|"transform model"| Analyzer
    Analyzer -->|"run scans/enforce policy"| Scanner
    Scanner -->|"store results"| EntDB
    Scanner -->|"store graph data"| GraphDB
    EntDB -->|"stream data"| MCP
    Reporter -->|"output reports"| CLI
    Agent -->|"subscribe SSE"| MCP
    Agent -->|"call LLM"| Agent
    Analyzer -->|"emit events"| TelemetryEP

    %% Click Events
    click CLI "https://github.com/safedep/vet/tree/main/cmd/"
    click Agent "https://github.com/safedep/vet/tree/main/agent/"
    click Readers "https://github.com/safedep/vet/tree/main/pkg/readers/"
    click Parsers "https://github.com/safedep/vet/tree/main/pkg/parser/"
    click Analyzer "https://github.com/safedep/vet/tree/main/pkg/analyzer/"
    click Scanner "https://github.com/safedep/vet/tree/main/pkg/scanner/"
    click Reporter "https://github.com/safedep/vet/tree/main/pkg/reporter/"
    click EntDB "https://github.com/safedep/vet/tree/main/ent/"
    click GraphDB "https://github.com/safedep/vet/blob/main/pkg/storage/graph/graph.go"
    click MCP "https://github.com/safedep/vet/tree/main/mcp/"
    click API "https://github.com/safedep/vet/tree/main/api/"
    click Gen "https://github.com/safedep/vet/tree/main/gen/"
    click Telemetry "https://github.com/safedep/vet/tree/main/internal/analytics/"
    click Auth "https://github.com/safedep/vet/tree/main/internal/auth/"
    click CmdFramework "https://github.com/safedep/vet/tree/main/internal/command/"
    click UIHelpers "https://github.com/safedep/vet/tree/main/internal/ui/"
    click SafeDep "https://github.com/safedep/vet/tree/main/pkg/cloud/"
    click GitHub "https://github.com/safedep/vet/blob/main/pkg/readers/github_reader.go"
    click Registries "https://github.com/safedep/vet/tree/main/pkg/common/registry/"
    click OSVScore "https://github.com/safedep/vet/blob/main/pkg/scanner/enrich_insights.go"

    %% Styles
    classDef ui fill:#a3d9a5,stroke:#333,stroke-width:1px,shape:parallelogram
    classDef core fill:#a5c8f0,stroke:#333,stroke-width:1px
    classDef db fill:#f0b37f,stroke:#333,stroke-width:1px,shape:cylinder
    classDef server fill:#f4c2c2,stroke:#333,stroke-width:1px
    classDef api fill:#c6b2d7,stroke:#333,stroke-width:1px,shape:hexagon
    classDef internal fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef external fill:#d7bde2,stroke:#333,stroke-width:1px,shape:cloud
```
