# cloro-dev/geo-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/cloro-dev/geo-tracker
- Repository: https://github.com/cloro-dev/geo-tracker

## Overview

geo-tracker is an agent-driven GEO/SEO tracker: clients configure prompts, schedule or trigger engine runs, and query stored answers and brand visibility. Runs are submitted asynchronously to cloro; results arrive by webhook or are recovered by polling, then derived source and brand data is refreshed. The graph includes the REST and MCP interfaces, scheduler, extraction, persistence, and documented Grafana use. Some route and integration links rely on README or SOURCE INDEX references because their implementation excerpts were not shown.

Main entry points: [`lib/runner.ts`](https://github.com/cloro-dev/geo-tracker/blob/main/lib/runner.ts) (Run scheduler), [`lib/db/schema.ts`](https://github.com/cloro-dev/geo-tracker/blob/main/lib/db/schema.ts) (Postgres tables), [`lib/auth.ts`](https://github.com/cloro-dev/geo-tracker/blob/main/lib/auth.ts) (Request auth), [`app/api/brands/route.ts`](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/brands/route.ts) (Brand API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP tools<br/>[route.ts]"]
  node_promptsapi["Prompt API<br/>[route.ts]"]
  node_runapi["Run endpoint<br/>[route.ts]"]
  node_resultsapi["Results API<br/>[route.ts]"]
  node_brandsapi["Brand API<br/>[route.ts]"]
  node_auth["Request auth<br/>[auth.ts]"]
  node_validation["Input validation<br/>[validation.ts]"]
end

subgraph group_scheduling["Run orchestration"]
  node_cronroute["Cron route<br/>[route.ts]"]
  node_runner["Run scheduler<br/>[runner.ts]"]
  node_engines["Engine mapping<br/>[engines.ts]"]
  node_webhookroute["Webhook route<br/>[route.ts]"]
  node_webhooks["Webhook security<br/>[webhooks.ts]"]
end

subgraph group_analysis["Answer analysis"]
  node_extract["Response extraction<br/>[extract.ts]"]
  node_refresh["Derived data refresh<br/>[refresh.ts]"]
end

subgraph group_storage["Postgres data"]
  node_postgres[("Postgres tables<br/>[schema.ts]")]
end

subgraph group_observability["Reporting"]
  node_grafana["Grafana starter<br/>[dashboard.json]"]
end

node_agent(("Agent client"))
node_httpclient(("HTTP client"))
node_cronservice(("Vercel Cron"))
node_cloro{{"cloro API"}}

node_agent -->|"calls tools"| node_mcp
node_httpclient -->|"configures prompts"| node_promptsapi
node_httpclient -->|"triggers runs"| node_runapi
node_mcp -->|"checks access"| node_auth
node_promptsapi -->|"checks access"| node_auth
node_runapi -->|"checks access"| node_auth
node_resultsapi -->|"checks access"| node_auth
node_brandsapi -->|"checks access"| node_auth
node_promptsapi -->|"validates input"| node_validation
node_brandsapi -->|"validates input"| node_validation
node_mcp -->|"reads and writes"| node_postgres
node_promptsapi -->|"reads and writes"| node_postgres
node_runapi -->|"submits prompt"| node_runner
node_runapi -->|"reads prompt"| node_postgres
node_resultsapi -->|"queries results"| node_postgres
node_brandsapi -->|"reads and writes"| node_postgres
node_brandsapi -->|"queues re-extraction"| node_refresh
node_cronservice -->|"ticks schedule"| node_cronroute
node_cronroute -->|"checks cron access"| node_auth
node_cronroute -->|"runs tick"| node_runner
node_runner -->|"claims and stores runs"| node_postgres
node_runner -->|"selects engine task"| node_engines
node_runner -->|"submits and polls"| node_cloro
node_runner -->|"builds callback URL"| node_webhooks
node_cloro -->|"posts completion"| node_webhookroute
node_webhookroute -->|"verifies callback"| node_webhooks
node_webhookroute -->|"completes task"| node_runner
node_runner -->|"refreshes derived data"| node_refresh
node_refresh -->|"extracts response data"| node_extract
node_refresh -->|"writes derived rows"| node_postgres
node_postgres -->|"charts stored data"| node_grafana

click node_mcp "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/mcp/route.ts"
click node_promptsapi "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/prompts/route.ts"
click node_runapi "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/prompts/%5Bid%5D/run/route.ts"
click node_resultsapi "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/results/route.ts"
click node_brandsapi "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/brands/route.ts"
click node_auth "https://github.com/cloro-dev/geo-tracker/blob/main/lib/auth.ts"
click node_validation "https://github.com/cloro-dev/geo-tracker/blob/main/lib/validation.ts"
click node_cronroute "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/cron/route.ts"
click node_runner "https://github.com/cloro-dev/geo-tracker/blob/main/lib/runner.ts"
click node_engines "https://github.com/cloro-dev/geo-tracker/blob/main/lib/engines.ts"
click node_webhookroute "https://github.com/cloro-dev/geo-tracker/blob/main/app/api/webhook/route.ts"
click node_webhooks "https://github.com/cloro-dev/geo-tracker/blob/main/lib/webhooks.ts"
click node_extract "https://github.com/cloro-dev/geo-tracker/blob/main/lib/extract.ts"
click node_refresh "https://github.com/cloro-dev/geo-tracker/blob/main/lib/refresh.ts"
click node_postgres "https://github.com/cloro-dev/geo-tracker/blob/main/lib/db/schema.ts"
click node_grafana "https://github.com/cloro-dev/geo-tracker/blob/main/grafana/dashboard.json"

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_mcp,node_promptsapi,node_runapi,node_resultsapi,node_brandsapi,node_auth,node_validation,node_agent,node_httpclient toneBlue
class node_cronroute,node_runner,node_engines,node_webhookroute,node_webhooks toneAmber
class node_extract,node_refresh,node_cloro toneMint
class node_postgres toneRose
class node_grafana,node_cronservice toneIndigo
```

## Components

### Agent interfaces

- [MCP tools](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/mcp/route.ts): `app/api/mcp/route.ts`
- [Prompt API](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/prompts/route.ts): `app/api/prompts/route.ts`
- [Run endpoint](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/prompts/%5Bid%5D/run/route.ts): `app/api/prompts/[id]/run/route.ts`
- [Results API](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/results/route.ts): `app/api/results/route.ts`
- [Brand API](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/brands/route.ts): `app/api/brands/route.ts`
- [Request auth](https://github.com/cloro-dev/geo-tracker/blob/main/lib/auth.ts): `lib/auth.ts`
- [Input validation](https://github.com/cloro-dev/geo-tracker/blob/main/lib/validation.ts): `lib/validation.ts`

### Run orchestration

- [Cron route](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/cron/route.ts): `app/api/cron/route.ts`
- [Run scheduler](https://github.com/cloro-dev/geo-tracker/blob/main/lib/runner.ts): `lib/runner.ts`
- [Engine mapping](https://github.com/cloro-dev/geo-tracker/blob/main/lib/engines.ts): `lib/engines.ts`
- [Webhook route](https://github.com/cloro-dev/geo-tracker/blob/main/app/api/webhook/route.ts): `app/api/webhook/route.ts`
- [Webhook security](https://github.com/cloro-dev/geo-tracker/blob/main/lib/webhooks.ts): `lib/webhooks.ts`

### Answer analysis

- [Response extraction](https://github.com/cloro-dev/geo-tracker/blob/main/lib/extract.ts): `lib/extract.ts`
- [Derived data refresh](https://github.com/cloro-dev/geo-tracker/blob/main/lib/refresh.ts): `lib/refresh.ts`

### Postgres data

- [Postgres tables](https://github.com/cloro-dev/geo-tracker/blob/main/lib/db/schema.ts): `lib/db/schema.ts`

### Reporting

- [Grafana starter](https://github.com/cloro-dev/geo-tracker/blob/main/grafana/dashboard.json): `grafana/dashboard.json`

### Other components

- **Agent client**
- **HTTP client**
- **Vercel Cron**
- **cloro API**

## Connections

- Agent client → MCP tools: calls tools (evidence: `README.md`)
- HTTP client → Prompt API: configures prompts (evidence: `README.md`)
- HTTP client → Run endpoint: triggers runs (evidence: `README.md`)
- MCP tools → Request auth: checks access (evidence: `app/api/mcp/route.ts`)
- Prompt API → Request auth: checks access (evidence: `app/api/prompts/route.ts`)
- Run endpoint → Request auth: checks access (evidence: `app/api/prompts/[id]/run/route.ts`)
- Results API → Request auth: checks access (evidence: `app/api/results/route.ts`)
- Brand API → Request auth: checks access (evidence: `app/api/brands/route.ts`)
- Prompt API → Input validation: validates input (evidence: `app/api/prompts/route.ts`)
- Brand API → Input validation: validates input (evidence: `app/api/brands/route.ts`)
- MCP tools → Postgres tables: reads and writes (evidence: `app/api/mcp/route.ts`)
- Prompt API → Postgres tables: reads and writes (evidence: `app/api/prompts/route.ts`)
- Run endpoint → Run scheduler: submits prompt (evidence: `app/api/prompts/[id]/run/route.ts`)
- Run endpoint → Postgres tables: reads prompt (evidence: `app/api/prompts/[id]/run/route.ts`)
- Results API → Postgres tables: queries results (evidence: `app/api/results/route.ts`)
- Brand API → Postgres tables: reads and writes (evidence: `app/api/brands/route.ts`)
- Brand API → Derived data refresh: queues re-extraction (evidence: `app/api/brands/route.ts`)
- Vercel Cron → Cron route: ticks schedule (evidence: `README.md`)
- Cron route → Request auth: checks cron access (evidence: `app/api/cron/route.ts`)
- Cron route → Run scheduler: runs tick (evidence: `app/api/cron/route.ts`)
- Run scheduler → Postgres tables: claims and stores runs (evidence: `lib/runner.ts`)
- Run scheduler → Engine mapping: selects engine task (evidence: `lib/runner.ts`)
- Run scheduler → cloro API: submits and polls (evidence: `lib/runner.ts`)
- Run scheduler → Webhook security: builds callback URL (evidence: `lib/runner.ts`)
- cloro API → Webhook route: posts completion (evidence: `README.md`)
- Webhook route → Webhook security: verifies callback (evidence: `app/api/webhook/route.ts`)
- Webhook route → Run scheduler: completes task (evidence: `app/api/webhook/route.ts`)
- Run scheduler → Derived data refresh: refreshes derived data (evidence: `lib/runner.ts`)
- Derived data refresh → Response extraction: extracts response data (evidence: `lib/refresh.ts`)
- Derived data refresh → Postgres tables: writes derived rows (evidence: `lib/refresh.ts`)
- Postgres tables → Grafana starter: charts stored data (evidence: `README.md`)
