# arm/metis architecture

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

- Interactive diagram: https://gitdiagram.com/arm/metis
- Repository: https://github.com/arm/metis

## Overview

##### Project type and purpose
- Metis is an open-source, AI-powered CLI tool for deep security code review.
- It’s designed as a plugin-based, extensible system that indexes source code into a vector database, uses LLMs for semantic analysis, and emits structured security findings (SARIF).

##### File structure
- Top-level dirs:
- src/metis: core Python package
- src/metis/cli: command-line interface entry points and commands
- src/metis/engine.py: orchestration of indexing and review workflows
- src/metis/plugins: language plugins (C, Python, Rust) + plugin metadata
- src/metis/providers: LLM providers (OpenAI, Azure)
- src/metis/vector_store: vector database backends (Chroma, pgvector)
- src/metis/sarif: SARIF result writer
- config files: metis.yaml (defaults), plugins.yaml (prompt & chunking)
- docker/docker-compose: PostgreSQL + pgvector setup
- examples, docs, tests illustrate usage and deployments

##### README for additional insights
- Core flow: CLI → index → review_code / review_file / review_patch → SARIF output
- RAG pattern: split code chunks → embed → store/retrieve similar contexts → prompt LLM
- Two vector backends supported (Chroma for local, Postgres+pgvector for scale)
- Single LLM provider now, pluggable to add more

##### Components & interactions
a. Main components
- User → CLI layer
- CLI commands → Engine
- Engine
- Loader & chunker (reads code, splits into chunks)
- Embedding client (calls LLM embed API)
- Vector store adapter (Chroma or Postgres)
- Review coordinator (retrieval, prompting via LLM provider)
- SARIF writer
- Plugins
- Language plugin logic (tokenization, prompts)
- Providers
- OpenAI/Azure client
- Data stores
- Local ChromaDB
- Remote PostgreSQL + pgvector
- External services
- OpenAI/Azure LLM endpoint

b. Relationships & data flow
1. User invokes CLI command
2. CLI calls Engine with config
3. Engine loads source files, applies language plugins
4. Engine calls embedding provider → embeddings
5. Embeddings stored in vector store
6. During review, Engine queries vector store for similar chunks
7. Engine assembles context + prompts via provider
8. LLM returns analysis → Engine formats results
9. SARIF writer outputs structured findings
10. CLI renders or writes SARIF JSON

c. Architectural patterns & principles
- Plugin-based architecture for languages & providers
- Adapter pattern around vector stores (common interface)
- Separation of concerns: CLI, engine orchestration, I/O, plugins, providers
- RAG (Retrieval-Augmented Generation) flow
- Configuration-driven via YAML (runtime parameters, prompts, chunking)

d. Key technologies
- Python 3.12+, Click or argparse for CLI
- ChromaDB (local) or PostgreSQL + pgvector (scale)
- OpenAI/Azure openai-compatible APIs
- SARIF format for output
- Docker Compose for self-hosted Postgres

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI_main["__main__.py"]:::core
        CLI_entry["entry.py"]:::core
        CLI_cmds["commands.py"]:::core
        CLI_utils["utils.py"]:::core
    end
    CLI_main -->|invokes| Engine
    CLI_entry -->|calls| Engine
    CLI_cmds -->|executes| Engine

    %% Configuration
    subgraph "Configuration"
        Config_default["metis.yaml"]:::config
        Config_loader["configuration.py"]:::config
        Plugin_yaml["plugins.yaml"]:::config
    end
    Engine -->|loads| Config_default
    Engine -->|loads| Config_loader
    Engine -->|loads| Plugin_yaml

    %% Core Engine and its components
    Engine["Engine"]:::core
    click Engine "https://github.com/arm/metis/blob/main/src/metis/engine.py"
    subgraph "Core Engine Components"
        Chunker["Loader & Chunker"]:::core
        EmbedClient["Embedding Client"]:::core
        VectorAdapter["VectorStore Adapter"]:::core
        ReviewCoord["Review Coordinator"]:::core
        SARIFWriter["SARIF Writer"]:::core
    end
    Engine --> Chunker
    Engine --> EmbedClient
    Engine --> VectorAdapter
    Engine --> ReviewCoord
    Engine --> SARIFWriter

    Chunker -->|code chunks| EmbedClient
    EmbedClient -->|vectors| VectorAdapter
    VectorAdapter -->|store/retrieve| DataStores
    ReviewCoord -->|requests embeddings| VectorAdapter
    ReviewCoord -->|builds prompt| EmbedClient
    ReviewCoord -->|sends prompt| Providers
    Providers -->|analysis| ReviewCoord
    SARIFWriter -->|writes findings| CLI_utils

    %% Language Plugins
    subgraph "Language Plugins"
        PL_base["base.py"]:::plugin
        PL_C["c_plugin.py"]:::plugin
        PL_PY["python_plugin.py"]:::plugin
        PL_RS["rust_plugin.py"]:::plugin
    end
    click PL_base "https://github.com/arm/metis/blob/main/src/metis/plugins/base.py"
    click PL_C "https://github.com/arm/metis/blob/main/src/metis/plugins/c_plugin.py"
    click PL_PY "https://github.com/arm/metis/blob/main/src/metis/plugins/python_plugin.py"
    click PL_RS "https://github.com/arm/metis/blob/main/src/metis/plugins/rust_plugin.py"
    Chunker -->|uses| PL_base
    Chunker -->|uses| PL_C
    Chunker -->|uses| PL_PY
    Chunker -->|uses| PL_RS

    %% LLM Provider Adapters
    subgraph "LLM Providers"
        Prov_base["base.py"]:::provider
        Prov_OAI["openai.py"]:::provider
        Prov_Azure["azure_openai.py"]:::provider
    end
    click Prov_base "https://github.com/arm/metis/blob/main/src/metis/providers/base.py"
    click Prov_OAI "https://github.com/arm/metis/blob/main/src/metis/providers/openai.py"
    click Prov_Azure "https://github.com/arm/metis/blob/main/src/metis/providers/azure_openai.py"
    ReviewCoord -->|adapter| Prov_base
    Prov_base --> Prov_OAI
    Prov_base --> Prov_Azure

    %% Vector Store Adapters
    subgraph "Vector Store Adapters"
        VS_base["base.py"]:::datastore
        VS_Chroma["chroma_store.py"]:::datastore
        VS_PG["pgvector_store.py"]:::datastore
    end
    click VS_base "https://github.com/arm/metis/blob/main/src/metis/vector_store/base.py"
    click VS_Chroma "https://github.com/arm/metis/blob/main/src/metis/vector_store/chroma_store.py"
    click VS_PG "https://github.com/arm/metis/blob/main/src/metis/vector_store/pgvector_store.py"
    VectorAdapter -->|adapter| VS_base
    VS_base --> VS_Chroma
    VS_base --> VS_PG

    %% Data Stores
    subgraph "Data Stores"
        ChromaDB["ChromaDB"]:::datastore
        Postgres["Postgres + pgvector"]:::datastore
    end
    VS_Chroma --> ChromaDB
    VS_PG --> Postgres

    %% SARIF Module
    subgraph "SARIF Module"
        SARIF_utils["utils.py"]:::core
        SARIF_wr["writer.py"]:::core
    end
    click SARIF_utils "https://github.com/arm/metis/blob/main/src/metis/sarif/utils.py"
    click SARIF_wr "https://github.com/arm/metis/blob/main/src/metis/sarif/writer.py"
    SARIFWriter --> SARIF_utils
    SARIFWriter --> SARIF_wr

    %% Utilities & Exceptions
    subgraph "Utilities"
        Utils["utils.py"]:::core
        Exc["exceptions.py"]:::core
    end
    click Utils "https://github.com/arm/metis/blob/main/src/metis/utils.py"
    click Exc "https://github.com/arm/metis/blob/main/src/metis/exceptions.py"
    Engine --> Utils
    Engine --> Exc

    %% Docker Setup
    subgraph "Docker Setup"
        DC["docker-compose.yml"]:::external
        DBinit["init-vector.sql"]:::external
    end
    click DC "https://github.com/arm/metis/blob/main/docker-compose.yml"
    click DBinit "https://github.com/arm/metis/blob/main/docker/db-init/init-vector.sql"
    DC --> Postgres
    DC -->|initializes| DBinit

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Azure["Azure OpenAI API"]:::external
    end
    Prov_OAI --> OpenAI
    Prov_Azure --> Azure

    %% Styling
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef provider fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#9370DB,stroke:#333,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
