# iamstoick/argus architecture

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

- Interactive diagram: https://gitdiagram.com/iamstoick/argus
- Repository: https://github.com/iamstoick/argus

## Overview

Argus builds a per-project structural index of supported source files, then exposes codebase search and analysis to AI coding agents over MCP. The principal workflow is workspace sync → language parsing and relationship extraction → SQLite storage → tool queries and results. Serve mode also offers an authenticated admin UI/API; hybrid search can add an optional Ollama semantic tier. The README documents additional tool and UI capabilities; some implementation details were not sampled, so uncertain internal links are omitted.

Main entry points: [`src/http.ts`](https://github.com/iamstoick/argus/blob/main/src/http.ts) (HTTP server and API), [`src/projects.ts`](https://github.com/iamstoick/argus/blob/main/src/projects.ts) (Project manager), [`src/indexer.ts`](https://github.com/iamstoick/argus/blob/main/src/indexer.ts) (File sync and watcher), [`src/tools.ts`](https://github.com/iamstoick/argus/blob/main/src/tools.ts) (Dictionary and analysis tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Indexing"]
  node_projects["Project manager<br/>[projects.ts]"]
  node_indexer["File sync and watcher<br/>[indexer.ts]"]
  node_parser["Polyglot parser<br/>[parser.ts]"]
  node_queries["Language query packs<br/>[queries.ts]"]
  node_db[("Project SQLite index<br/>[db.ts]")]
end

subgraph group_query["Query and analysis"]
  node_tools["Dictionary and analysis tools<br/>[tools.ts]"]
end

subgraph group_serving["Agent and admin access"]
  node_entry["Runtime entry<br/>[index.ts]"]
  node_server["MCP tool server<br/>[server.ts]"]
  node_http["HTTP server and API<br/>[http.ts]"]
  node_admin["Admin web UI<br/>[index.html]"]
end

subgraph group_semantic["Semantic search"]
  node_embeddings["Embedding provider and sync<br/>[embeddings.ts]"]
end

node_agent(("AI coding agent"))
node_workspace["Project workspace"]
node_ollama["Ollama"]

node_agent -->|"sends MCP requests"| node_server
node_agent -->|"uses admin/API"| node_http
node_workspace -->|"provides source files"| node_indexer
node_entry -->|"opens projects"| node_projects
node_entry -->|"starts stdio MCP"| node_server
node_entry -->|"starts HTTP"| node_http
node_projects -->|"syncs and watches"| node_indexer
node_indexer -->|"parses changed files"| node_parser
node_parser -->|"uses language queries"| node_queries
node_indexer -->|"writes index data"| node_db
node_projects -->|"opens project index"| node_db
node_projects -.->|"syncs vectors"| node_embeddings
node_server -->|"dispatches MCP tools"| node_tools
node_http -->|"creates MCP endpoint"| node_server
node_http -->|"serves analysis data"| node_tools
node_http -->|"serves UI"| node_admin
node_tools -->|"queries index"| node_db
node_tools -.->|"requests semantic matches"| node_embeddings
node_embeddings -.->|"reads and writes vectors"| node_db
node_embeddings -.->|"probes and embeds"| node_ollama

click node_entry "https://github.com/iamstoick/argus/blob/main/src/index.ts"
click node_projects "https://github.com/iamstoick/argus/blob/main/src/projects.ts"
click node_indexer "https://github.com/iamstoick/argus/blob/main/src/indexer.ts"
click node_parser "https://github.com/iamstoick/argus/blob/main/src/parser.ts"
click node_queries "https://github.com/iamstoick/argus/blob/main/src/queries.ts"
click node_db "https://github.com/iamstoick/argus/blob/main/src/db.ts"
click node_server "https://github.com/iamstoick/argus/blob/main/src/server.ts"
click node_http "https://github.com/iamstoick/argus/blob/main/src/http.ts"
click node_admin "https://github.com/iamstoick/argus/blob/main/src/admin/index.html"
click node_tools "https://github.com/iamstoick/argus/blob/main/src/tools.ts"
click node_embeddings "https://github.com/iamstoick/argus/blob/main/src/embeddings.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_projects,node_indexer,node_parser,node_queries,node_db toneBlue
class node_tools toneAmber
class node_entry,node_server,node_http,node_admin toneMint
class node_embeddings toneRose
class node_agent,node_workspace,node_ollama toneIndigo
```

## Components

### Indexing

- [Project manager](https://github.com/iamstoick/argus/blob/main/src/projects.ts): `src/projects.ts`
- [File sync and watcher](https://github.com/iamstoick/argus/blob/main/src/indexer.ts): `src/indexer.ts`
- [Polyglot parser](https://github.com/iamstoick/argus/blob/main/src/parser.ts): `src/parser.ts`
- [Language query packs](https://github.com/iamstoick/argus/blob/main/src/queries.ts): `src/queries.ts`
- [Project SQLite index](https://github.com/iamstoick/argus/blob/main/src/db.ts): `src/db.ts`

### Query and analysis

- [Dictionary and analysis tools](https://github.com/iamstoick/argus/blob/main/src/tools.ts): `src/tools.ts`

### Agent and admin access

- [Runtime entry](https://github.com/iamstoick/argus/blob/main/src/index.ts): `src/index.ts`
- [MCP tool server](https://github.com/iamstoick/argus/blob/main/src/server.ts): `src/server.ts`
- [HTTP server and API](https://github.com/iamstoick/argus/blob/main/src/http.ts): `src/http.ts`
- [Admin web UI](https://github.com/iamstoick/argus/blob/main/src/admin/index.html): `src/admin/index.html`

### Semantic search

- [Embedding provider and sync](https://github.com/iamstoick/argus/blob/main/src/embeddings.ts): `src/embeddings.ts`

### Other components

- **AI coding agent**
- **Project workspace**
- **Ollama**

## Connections

- AI coding agent → MCP tool server: sends MCP requests
- AI coding agent → HTTP server and API: uses admin/API
- Project workspace → File sync and watcher: provides source files
- Runtime entry → Project manager: opens projects
- Runtime entry → MCP tool server: starts stdio MCP
- Runtime entry → HTTP server and API: starts HTTP
- Project manager → File sync and watcher: syncs and watches
- File sync and watcher → Polyglot parser: parses changed files
- Polyglot parser → Language query packs: uses language queries
- File sync and watcher → Project SQLite index: writes index data
- Project manager → Project SQLite index: opens project index
- Project manager → Embedding provider and sync: syncs vectors
- MCP tool server → Dictionary and analysis tools: dispatches MCP tools
- HTTP server and API → MCP tool server: creates MCP endpoint
- HTTP server and API → Dictionary and analysis tools: serves analysis data
- HTTP server and API → Admin web UI: serves UI
- Dictionary and analysis tools → Project SQLite index: queries index
- Dictionary and analysis tools → Embedding provider and sync: requests semantic matches
- Embedding provider and sync → Project SQLite index: reads and writes vectors
- Embedding provider and sync → Ollama: probes and embeds