# ruvnet/agent-name-service architecture

> Architecture diagram of the GitHub repository ruvnet/agent-name-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ruvnet/agent-name-service
- Repository: https://github.com/ruvnet/agent-name-service

## Overview

##### Project type and purpose
- This is a Node.js/TypeScript–based backend service and library (an open-source tool) implementing the OWASP GenAI ANS protocol.
- Its purpose is to provide a secure, modular registry for AI agents: registration, certificate management, discovery (A2A & MCP), plus integrated threat modeling via Mastra.ai.

##### File structure
- src/
– ans.ts: entry point for AgentNamingService (register, resolve, generateMCP)
– certificate.ts: X.509 certificate issuance & validation
– database/: DB factory & interface for SQLite persistence
– protocol/: formatting for A2A agent cards & MCP manifests
– mastra.ts & mastra-simple.ts: full vs. fallback threat analysis
– types/: TypeScript definitions
- tests/: unit & integration tests covering each service
- examples/: client-side usage scripts demonstrating registration, resolution, manifest generation
- scripts/: shell workflows to automate registrations & security workflows
- sparc-agent/: a companion client library implementing MAS-TRAC agents and workflows
- docs/architecture/: high-level design and deployment guides
- package.json, tsconfig.json, Jest config, .env support

##### Additional insights from the README
- Describes four core sub-systems: Agent Registry (DB), Certificate Service, Protocol Formatters, Threat Modeling
- Supports environment-driven configuration for CA info, DB path, Mastra endpoint, feature flags
- Emphasizes modular separation of concerns and plug-in–style integration of Mastra.ai

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        ExampleScripts["Example Client Scripts"]:::client
        Scripts["CLI/Workflows Scripts"]:::client
        SparcAgent["Companion Client Library"]:::client
    end

    %% Service Layer
    subgraph "Service Layer"
        ANSEntry["ANS Entry Point"]:::service
        LoadEnv["Environment Loader (.env)"]:::config
        AgentNamingService["AgentNamingService"]:::service
        CertificateEntry["Certificate Facade"]:::service
        CertificateService["CertificateService"]:::service
        ProtocolService["ProtocolFormatter"]:::service
        ProtocolDefs["Protocol Definitions"]:::service
        ThreatModelService["ThreatModelService"]:::service
        MastraFull["Mastra Full Integration"]:::service
        MastraSimple["Mastra Simple Fallback"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        DBBootstrap["Database Bootstrap"]:::data
        DBFactory["Database Factory"]:::data
        DatabaseService["DatabaseService"]:::data
    end

    %% External Services
    subgraph "External Services"
        MastraAPI["Mastra.ai Threat Modeling API"]:::external
        Docs["Architecture Documentation"]:::external
    end

    %% Flows
    ExampleScripts -->|calls API| ANSEntry
    Scripts -->|calls API| ANSEntry
    SparcAgent -->|library calls| ANSEntry

    ANSEntry -->|loads config| LoadEnv
    LoadEnv -.->|env vars| AgentNamingService
    LoadEnv -.->|env vars| CertificateService
    LoadEnv -.->|env vars| DBFactory
    LoadEnv -.->|env vars| ThreatModelService

    ANSEntry -->|delegates| AgentNamingService

    AgentNamingService -->|uses facade| CertificateEntry
    CertificateEntry -->|issues cert| CertificateService

    AgentNamingService -->|persists/retrieves| DatabaseService
    DBBootstrap -->|initializes| DBFactory
    DBFactory -->|provides| DatabaseService

    AgentNamingService -->|formats protocol| ProtocolService
    ProtocolService -->|loads definitions| ProtocolDefs

    AgentNamingService -->|performs threat modeling| ThreatModelService
    ThreatModelService -->|full analysis| MastraFull
    ThreatModelService -->|fallback analysis| MastraSimple
    MastraFull -->|REST calls| MastraAPI
    MastraSimple -->|local offline| MastraAPI

    ANSEntry -->|docs| Docs

    %% Click Events
    click ExampleScripts "https://github.com/ruvnet/agent-name-service/tree/main/examples/"
    click Scripts "https://github.com/ruvnet/agent-name-service/tree/main/scripts/"
    click SparcAgent "https://github.com/ruvnet/agent-name-service/tree/main/sparc-agent/src/"
    click ANSEntry "https://github.com/ruvnet/agent-name-service/blob/main/src/ans.ts"
    click LoadEnv "https://github.com/ruvnet/agent-name-service/blob/main/src/load-env.ts"
    click AgentNamingService "https://github.com/ruvnet/agent-name-service/blob/main/src/core/ansService.ts"
    click CertificateEntry "https://github.com/ruvnet/agent-name-service/blob/main/src/certificate.ts"
    click CertificateService "https://github.com/ruvnet/agent-name-service/blob/main/src/certificate/certificate-service.ts"
    click ProtocolService "https://github.com/ruvnet/agent-name-service/blob/main/src/protocol/protocol-service.ts"
    click ProtocolDefs "https://github.com/ruvnet/agent-name-service/blob/main/src/protocols.ts"
    click ThreatModelService "https://github.com/ruvnet/agent-name-service/blob/main/src/threat/threat-modeling-service.ts"
    click MastraFull "https://github.com/ruvnet/agent-name-service/blob/main/src/mastra.ts"
    click MastraSimple "https://github.com/ruvnet/agent-name-service/blob/main/src/mastra-simple.ts"
    click DBBootstrap "https://github.com/ruvnet/agent-name-service/blob/main/src/db.ts"
    click DBFactory "https://github.com/ruvnet/agent-name-service/blob/main/src/database/database-service-factory.ts"
    click DatabaseService "https://github.com/ruvnet/agent-name-service/blob/main/src/database/databaseService.ts"
    click Docs "https://github.com/ruvnet/agent-name-service/blob/main/docs/architecture/ans_architecture.md"

    %% Styles
    classDef client fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef service fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef data fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#ffccbc,stroke:#333,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#333,stroke-width:1px
```
