# svuillaume/forticnapp-ai architecture

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

- Interactive diagram: https://gitdiagram.com/svuillaume/forticnapp-ai
- Repository: https://github.com/svuillaume/forticnapp-ai

## Overview

FortiCNAPP LQL Agent turns a natural-language security question into a schema-aware, validated and executed query, then returns a certainty-scored result. The documented workflow is driven by a Claude Code sub-agent using a read-only stdio MCP server; the server also provides policy-query search, local query memory and result tables. The agent definition and iteration logic were not sampled, so those links rely on README documentation; server-side tool and API links use the sampled server excerpt.

Main entry points: [`.claude/agents/lql-agent.md`](https://github.com/svuillaume/forticnapp-ai/blob/main/.claude/agents/lql-agent.md) (LQL agent), [`lql_mcp/server.py`](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py) (API client), [`lql_mcp/render.py`](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/render.py) (Result renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Query authoring"]
  node_agent["LQL agent<br/>[lql-agent.md]"]
end

subgraph group_mcp["MCP tools"]
  node_server["MCP server<br/>[server.py]"]
  node_policy["Policy search<br/>[server.py]"]
  node_datasources["Datasource tools<br/>[server.py]"]
  node_validation["Query validation<br/>[server.py]"]
  node_execution["Query execution<br/>[server.py]"]
  node_api["API client<br/>[server.py]"]
  node_auth["Token exchange<br/>[server.py]"]
  node_allowlist["Endpoint allowlist<br/>[server.py]"]
end

subgraph group_memory["Local memory"]
  node_cache_search["Cache search<br/>[server.py]"]
  node_cache_save["Cache save<br/>[server.py]"]
  node_cache[("Local query cache")]
end

subgraph group_results["Result presentation"]
  node_render["Result renderer<br/>[render.py]"]
end

node_user(("Engineer"))
node_claude["Claude Code"]
node_forti["FortiCNAPP API"]

node_user -->|"asks question"| node_claude
node_claude -->|"routes question"| node_agent
node_agent -->|"uses tools"| node_server
node_server -->|"exposes"| node_policy
node_server -->|"exposes"| node_datasources
node_server -->|"exposes"| node_validation
node_server -->|"exposes"| node_execution
node_agent -->|"checks schema"| node_datasources
node_agent -->|"validates drafts"| node_validation
node_agent -->|"tests queries"| node_execution
node_policy -->|"requests policies"| node_api
node_datasources -->|"requests schemas"| node_api
node_validation -->|"validates LQL"| node_api
node_execution -->|"runs LQL"| node_api
node_api -->|"checks endpoint"| node_allowlist
node_api -->|"sends API requests"| node_forti
node_api -->|"exchanges credentials"| node_auth
node_auth -->|"requests token"| node_forti
node_agent -->|"looks up prior queries"| node_cache_search
node_agent -->|"saves strong queries"| node_cache_save
node_cache_search -->|"reads"| node_cache
node_cache_save -->|"writes"| node_cache
node_server -->|"uses renderer"| node_render
node_agent -->|"renders results"| node_render

click node_agent "https://github.com/svuillaume/forticnapp-ai/blob/main/.claude/agents/lql-agent.md"
click node_server "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_policy "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_datasources "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_validation "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_execution "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_api "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_auth "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_allowlist "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_cache_search "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_cache_save "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py"
click node_render "https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/render.py"

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_agent toneBlue
class node_server,node_policy,node_datasources,node_validation,node_execution,node_api,node_auth,node_allowlist toneAmber
class node_cache_search,node_cache_save,node_cache,node_forti toneMint
class node_render toneRose
class node_user,node_claude toneIndigo
```

## Components

### Query authoring

- [LQL agent](https://github.com/svuillaume/forticnapp-ai/blob/main/.claude/agents/lql-agent.md): `.claude/agents/lql-agent.md`

### MCP tools

- [MCP server](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Policy search](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Datasource tools](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Query validation](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Query execution](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [API client](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Token exchange](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Endpoint allowlist](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`

### Local memory

- [Cache search](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- [Cache save](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/server.py): `lql_mcp/server.py`
- **Local query cache**

### Result presentation

- [Result renderer](https://github.com/svuillaume/forticnapp-ai/blob/main/lql_mcp/render.py): `lql_mcp/render.py`

### Other components

- **Engineer**
- **Claude Code**
- **FortiCNAPP API**

## Connections

- Engineer → Claude Code: asks question (evidence: `README.md`)
- Claude Code → LQL agent: routes question (evidence: `README.md`)
- LQL agent → MCP server: uses tools (evidence: `README.md`)
- MCP server → Policy search: exposes (evidence: `lql_mcp/server.py`)
- MCP server → Datasource tools: exposes (evidence: `lql_mcp/server.py`)
- MCP server → Query validation: exposes (evidence: `lql_mcp/server.py`)
- MCP server → Query execution: exposes (evidence: `lql_mcp/server.py`)
- LQL agent → Datasource tools: checks schema (evidence: `README.md`)
- LQL agent → Query validation: validates drafts (evidence: `README.md`)
- LQL agent → Query execution: tests queries (evidence: `README.md`)
- Policy search → API client: requests policies (evidence: `lql_mcp/server.py`)
- Datasource tools → API client: requests schemas (evidence: `lql_mcp/server.py`)
- Query validation → API client: validates LQL (evidence: `lql_mcp/server.py`)
- Query execution → API client: runs LQL (evidence: `lql_mcp/server.py`)
- API client → Endpoint allowlist: checks endpoint (evidence: `lql_mcp/server.py`)
- API client → FortiCNAPP API: sends API requests (evidence: `lql_mcp/server.py`)
- API client → Token exchange: exchanges credentials (evidence: `lql_mcp/server.py`)
- Token exchange → FortiCNAPP API: requests token (evidence: `lql_mcp/server.py`)
- LQL agent → Cache search: looks up prior queries (evidence: `README.md`)
- LQL agent → Cache save: saves strong queries (evidence: `README.md`)
- Cache search → Local query cache: reads (evidence: `README.md`)
- Cache save → Local query cache: writes (evidence: `README.md`)
- MCP server → Result renderer: uses renderer (evidence: `lql_mcp/server.py`)
- LQL agent → Result renderer: renders results (evidence: `README.md`)
