How ruvnet/agentic-search works
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: readme.md Docs index · index.js index.js · architecture.md Architecture · README.md README
Components 15
Runtime
Node.js app bootstrap and environment-driven execution boundary.
- index.js · Primary Node.js bootstrap for the app or extension runtime.
index.js - Env config · Environment-provided secrets, flags, and integration settings.
sample.env - npm tooling · Dependency installation and script orchestration via npm.
package.json - Lockfile · Pinned dependency graph for reproducible installs.
package-lock.json
Frontend
Browser-facing landing page assets served statically.
- HTML shell · Browser entry document for the landing page.
public/index.html - Landing page · TypeScript/JSX landing page implementation.
public/landingpage.tsx
Docs
Human-facing architectural and feature documentation.
- README · Top-level project overview and usage guidance.
README.md - Architecture · Conceptual system architecture and boundaries.
docs/architecture.md - Intents · Intent handling and behavior model documentation.
docs/intents.md - Search · Search behavior and retrieval documentation.
docs/search.md - Advanced · Advanced capabilities and usage notes.
docs/advanced.md - Docs index · Documentation landing page inside the docs folder.
docs/readme.md
External
Outside services and user-facing integration points.
- Browser UI · Rendered user-facing page loaded in the browser.
- GitHub App · Hosted GitHub App / Agentic Search service boundary.
- GitHub · Repositories, installs, and GitHub-hosted interactions.
Connections 16
- 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.