# ruvnet/agentic-search architecture

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

- Interactive diagram: https://gitdiagram.com/ruvnet/agentic-search
- Repository: https://github.com/ruvnet/agentic-search

## Overview

1. **Repository role**
   - This repo is primarily a **documentation + landing-page shell** for the “Agentic Github Copilot Extension” / “Agentic Search” GitHub App, not a full multi-service backend. The visible architecture is lightweight and centered on a single app entrypoint plus static frontend assets.

2. **Main runtime boundary**
   - The only obvious executable entry is **`index.js`** at the repo root. That is the likely Node.js bootstrap for the extension/app runtime or local server process.
   - Everything under **`public/`** is the client-side surface that would be served to a browser.

3. **Frontend surface**
   - **`public/index.html`** is the HTML shell.
   - **`public/landingpage.tsx`** suggests the landing page is implemented in **TypeScript + React** (or a React-like JSX workflow), then bundled into the static site.
   - For an architecture diagram, this is the browser-facing UI layer.

4. **Documentation subsystem**
   - The **`docs/`** directory contains the project’s conceptual architecture and feature docs:
     - `architecture.md`
     - `intents.md`
     - `search.md`
     - `advanced.md`
   - These files are not runtime components; they are a knowledge layer that describes intended behavior, search, and advanced features.

5. **Configuration boundary**
   - **`sample.env`** indicates the app expects environment-based configuration.
   - This usually means secrets, API keys, or runtime flags are injected externally rather than hardcoded, so any diagram should show configuration entering the Node/app process from the environment.

6. **Package/tooling layer**
   - **`package.json`** and **`package-lock.json`** show the project is managed with **npm** and likely built/run through the Node ecosystem.
   - The presence of a lockfile suggests reproducible dependency installation is part of the setup.

7. **External integration**
   - The README points to a live GitHub App at **`github.com/apps/agentic-search`**.
   - That is the main external service boundary worth diagramming: the repo’s extension surfaces likely integrate with **GitHub repositories / GitHub App installation flow** rather than operating as a standalone local app.

8. **Likely data flow**
   - Typical flow in this repo is:
     - Browser loads `public/index.html`
     - Frontend script from `public/landingpage.tsx` renders the landing page
     - Any server logic or extension bootstrap runs through `index.js`
     - Configuration and credentials are supplied via environment variables
     - The app connects outward to GitHub/Agentic Search services
   - There is no visible database, job queue, or internal microservice mesh in the repository tree.

9. **Architectural shape**
   - The repo looks like a **single-process Node app with a static frontend** and documentation assets, rather than a distributed system.
   - The main architectural boundary is between:
     - **runtime code** (`index.js`, `public/`)
     - **human-facing docs** (`docs/`)
     - **external GitHub App/service** (hosted at the linked app)

10. **What to emphasize in a diagram**
   - Show the **browser/UI** as the consumer of the landing page.
   - Show **Node.js entrypoint** as the app bootstrap/configuration boundary.
   - Show **GitHub / GitHub App** as the external integration.
   - Keep docs separate as non-runtime reference material.

Main entry points: [`docs/readme.md`](https://github.com/ruvnet/agentic-search/blob/main/docs/readme.md) (Docs index), [`index.js`](https://github.com/ruvnet/agentic-search/blob/main/index.js) (index.js), [`docs/architecture.md`](https://github.com/ruvnet/agentic-search/blob/main/docs/architecture.md) (Architecture), [`README.md`](https://github.com/ruvnet/agentic-search/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_index_js["index.js<br/>node entrypoint<br/>[index.js]"]
  node_env_config["Env config<br/>runtime config<br/>[sample.env]"]
  node_npm_tooling["npm tooling<br/>package manager<br/>[package.json]"]
  node_lockfile["Lockfile<br/>dependency lock<br/>[package-lock.json]"]
end

subgraph group_frontend["Frontend"]
  node_public_shell["HTML shell<br/>static entry<br/>[index.html]"]
  node_landing_page["Landing page<br/>react ui<br/>[landingpage.tsx]"]
end

subgraph group_docs["Docs"]
  node_readme["README<br/>overview doc<br/>[README.md]"]
  node_architecture_doc["Architecture<br/>design doc<br/>[architecture.md]"]
  node_intents_doc["Intents<br/>feature doc<br/>[intents.md]"]
  node_search_doc["Search<br/>feature doc<br/>[search.md]"]
  node_advanced_doc["Advanced<br/>feature doc<br/>[advanced.md]"]
  node_docs_index["Docs index<br/>doc index<br/>[readme.md]"]
end

subgraph group_external["External"]
  node_browser_ui(("Browser UI<br/>client surface"))
  node_github_app{{"GitHub App<br/>external integration"}}
  node_github_platform{{"GitHub<br/>external platform"}}
end

node_npm_tooling -->|"runs"| node_index_js
node_lockfile -.->|"pins"| node_npm_tooling
node_env_config -->|"configures"| node_index_js
node_index_js -->|"serves"| node_public_shell
node_public_shell -->|"loads"| node_landing_page
node_landing_page -->|"renders"| node_browser_ui
node_index_js -->|"integrates"| node_github_app
node_github_app -->|"operates on"| node_github_platform
node_readme -.->|"points to"| node_github_app
node_readme -.->|"documents"| node_docs_index
node_docs_index -.->|"indexes"| node_architecture_doc
node_docs_index -.->|"indexes"| node_intents_doc
node_docs_index -.->|"indexes"| node_search_doc
node_docs_index -.->|"indexes"| node_advanced_doc
node_architecture_doc -.->|"references"| node_search_doc
node_architecture_doc -.->|"references"| node_intents_doc

click node_index_js "https://github.com/ruvnet/agentic-search/blob/main/index.js"
click node_env_config "https://github.com/ruvnet/agentic-search/blob/main/sample.env"
click node_npm_tooling "https://github.com/ruvnet/agentic-search/blob/main/package.json"
click node_lockfile "https://github.com/ruvnet/agentic-search/blob/main/package-lock.json"
click node_public_shell "https://github.com/ruvnet/agentic-search/blob/main/public/index.html"
click node_landing_page "https://github.com/ruvnet/agentic-search/blob/main/public/landingpage.tsx"
click node_readme "https://github.com/ruvnet/agentic-search/blob/main/README.md"
click node_architecture_doc "https://github.com/ruvnet/agentic-search/blob/main/docs/architecture.md"
click node_intents_doc "https://github.com/ruvnet/agentic-search/blob/main/docs/intents.md"
click node_search_doc "https://github.com/ruvnet/agentic-search/blob/main/docs/search.md"
click node_advanced_doc "https://github.com/ruvnet/agentic-search/blob/main/docs/advanced.md"
click node_docs_index "https://github.com/ruvnet/agentic-search/blob/main/docs/readme.md"

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_index_js,node_env_config,node_npm_tooling,node_lockfile toneBlue
class node_public_shell,node_landing_page toneAmber
class node_readme,node_architecture_doc,node_intents_doc,node_search_doc,node_advanced_doc,node_docs_index toneMint
class node_browser_ui,node_github_app,node_github_platform toneRose
```

## Components

### Runtime

Node.js app bootstrap and environment-driven execution boundary.

- [index.js](https://github.com/ruvnet/agentic-search/blob/main/index.js): node entrypoint · Primary Node.js bootstrap for the app or extension runtime. · `index.js`
- [Env config](https://github.com/ruvnet/agentic-search/blob/main/sample.env): runtime config · Environment-provided secrets, flags, and integration settings. · `sample.env`
- [npm tooling](https://github.com/ruvnet/agentic-search/blob/main/package.json): package manager · Dependency installation and script orchestration via npm. · `package.json`
- [Lockfile](https://github.com/ruvnet/agentic-search/blob/main/package-lock.json): dependency lock · Pinned dependency graph for reproducible installs. · `package-lock.json`

### Frontend

Browser-facing landing page assets served statically.

- [HTML shell](https://github.com/ruvnet/agentic-search/blob/main/public/index.html): static entry · Browser entry document for the landing page. · `public/index.html`
- [Landing page](https://github.com/ruvnet/agentic-search/blob/main/public/landingpage.tsx): react ui · TypeScript/JSX landing page implementation. · `public/landingpage.tsx`

### Docs

Human-facing architectural and feature documentation.

- [README](https://github.com/ruvnet/agentic-search/blob/main/README.md): overview doc · Top-level project overview and usage guidance. · `README.md`
- [Architecture](https://github.com/ruvnet/agentic-search/blob/main/docs/architecture.md): design doc · Conceptual system architecture and boundaries. · `docs/architecture.md`
- [Intents](https://github.com/ruvnet/agentic-search/blob/main/docs/intents.md): feature doc · Intent handling and behavior model documentation. · `docs/intents.md`
- [Search](https://github.com/ruvnet/agentic-search/blob/main/docs/search.md): feature doc · Search behavior and retrieval documentation. · `docs/search.md`
- [Advanced](https://github.com/ruvnet/agentic-search/blob/main/docs/advanced.md): feature doc · Advanced capabilities and usage notes. · `docs/advanced.md`
- [Docs index](https://github.com/ruvnet/agentic-search/blob/main/docs/readme.md): doc index · Documentation landing page inside the docs folder. · `docs/readme.md`

### External

Outside services and user-facing integration points.

- **Browser UI**: client surface · Rendered user-facing page loaded in the browser.
- **GitHub App**: external integration · Hosted GitHub App / Agentic Search service boundary.
- **GitHub**: external platform · Repositories, installs, and GitHub-hosted interactions.

## Connections

- npm tooling → index.js: runs · npm scripts or node execution start the main process.
- Lockfile → npm tooling: pins · Lockfile constrains installed package versions.
- Env config → index.js: configures · Runtime settings and secrets flow into the app bootstrap.
- index.js → HTML shell: serves · The Node process exposes the static browser entry.
- HTML shell → Landing page: loads · HTML shell mounts the landing page bundle/component.
- Landing page → Browser UI: renders · Client code produces the visible browser experience.
- index.js → GitHub App: integrates · App runtime connects to the GitHub App/service boundary.
- GitHub App → GitHub: operates on · The app interacts with GitHub repositories and installs.
- README → GitHub App: points to · Project overview references the live GitHub App.
- README → Docs index: documents · README links into the documentation set.
- Docs index → Architecture: indexes · Docs landing page organizes the architecture guide.
- Docs index → Intents: indexes · Docs landing page organizes intent documentation.
- Docs index → Search: indexes · Docs landing page organizes search documentation.
- Docs index → Advanced: indexes · Docs landing page organizes advanced documentation.
- Architecture → Search: references · Architecture and search concepts are related.
- Architecture → Intents: references · Architecture and intent handling are related.