# amit2003dh/spikeai architecture

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

- Interactive diagram: https://gitdiagram.com/amit2003dh/spikeai
- Repository: https://github.com/amit2003dh/spikeai

## Overview

#### Purpose and API Entry Point
This is a Node.js marketing-analysis backend that answers natural-language B2B questions using GA4 analytics, Screaming Frog SEO export data, and an LLM. The HTTP boundary is an Express server exposing `POST /query` on port 8080.
- `src/app.js`
- `src/ui.html`

#### Request Control Plane
The API receives a user query plus GA4 property context, then delegates interpretation and execution to a central orchestrator. Agents do not coordinate directly; the orchestrator selects analytics, SEO, or combined processing and owns the final response path.
- `src/app.js`
- `src/orchestrator.js`

#### LLM Interpretation and Response Generation
The LLM adapter is the semantic boundary for converting natural language into structured GA4-report intent, classifying/routing queries, and producing user-facing answers. It connects through the OpenAI SDK to a LiteLLM proxy, with credentials expected from environment/configuration.
- `src/llm.js`
- `src/orchestrator.js`

#### GA4 Analytics Agent
The GA4 agent translates analytics requests into a constrained Google Analytics Data API `runReport` shape before querying a supplied property ID. This protects the external API from ambiguous terms such as “traffic,” and should return a graceful no-data result rather than failing for empty properties.
- `src/agents/ga4Agent.js`
- `src/llm.js`

#### SEO Audit Agent and Data Ingestion
The SEO agent analyzes Screaming Frog-style audit rows, especially URL/address and title-tag fields. Its data boundary is CSV loading/parsing rather than the Google Sheets API; data is converted into in-memory records for deterministic filtering such as title-length conditions.
- `src/agents/seoAgent.js`
- `src/utils/dataLoader.js`

#### Multi-Agent Fusion
For mixed questions, the orchestrator invokes GA4 and SEO work concurrently, then provides bounded raw result sets to the LLM for a semantic join. This allows fuzzy URL correspondence between GA4 paths and full audit URLs, trading token use for flexibility; inputs are limited to roughly the top 50 rows to control prompt size.
- `src/orchestrator.js`
- `src/agents/ga4Agent.js`
- `src/agents/seoAgent.js`

#### Runtime and External Dependencies
The service targets Node.js 18+ and Express. Material integrations are Google Analytics Data API via `@google-analytics/data`, CSV processing via `csv-parse`, and an OpenAI-compatible LiteLLM endpoint. Google service-account credentials are expected at deployment/runtime, and the deployment script installs dependencies and starts the server.
- `package.json`
- `deploy.sh`
- `.env`

Main entry points: [`src/orchestrator.js`](https://github.com/amit2003dh/spikeai/blob/main/src/orchestrator.js) (Orchestrator), [`src/llm.js`](https://github.com/amit2003dh/spikeai/blob/main/src/llm.js) (LLM Adapter), [`src/app.js`](https://github.com/amit2003dh/spikeai/blob/main/src/app.js) (Express API), [`src/agents/ga4Agent.js`](https://github.com/amit2003dh/spikeai/blob/main/src/agents/ga4Agent.js) (GA4 Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Node.js Service"]
  node_api["Express API<br/>HTTP server<br/>[app.js]"]
  node_orchestrator["Orchestrator<br/>request router<br/>[orchestrator.js]"]
  node_llm["LLM Adapter<br/>semantic boundary<br/>[llm.js]"]
end

subgraph group_agents["Analysis Agents"]
  node_ga4_agent["GA4 Agent<br/>analytics agent<br/>[ga4Agent.js]"]
  node_seo_agent["SEO Agent<br/>audit agent<br/>[seoAgent.js]"]
  node_csv_loader["CSV Loader<br/>data ingestion<br/>[dataLoader.js]"]
end

subgraph group_external["Data &amp; AI Services"]
  node_ga4_api{{"Google Analytics Data API<br/>analytics API"}}
  node_audit_csv["Screaming Frog CSV<br/>SEO audit export"]
  node_litellm{{"LiteLLM Proxy<br/>OpenAI-compatible endpoint"}}
end

node_ui["Query UI<br/>HTML client<br/>[ui.html]"]
node_runtime_config["Runtime Credentials<br/>environment configuration<br/>[.env]"]
node_deployment["Deployment Script<br/>runtime launcher<br/>[deploy.sh]"]

node_ui -->|"POST /query"| node_api
node_api -->|"delegate query"| node_orchestrator
node_orchestrator -->|"classify and answer"| node_llm
node_orchestrator -->|"analytics work"| node_ga4_agent
node_orchestrator -->|"SEO work"| node_seo_agent
node_orchestrator -.->|"fuse bounded results"| node_llm
node_llm -->|"structured report intent"| node_ga4_agent
node_llm -->|"OpenAI SDK"| node_litellm
node_ga4_agent -->|"runReport"| node_ga4_api
node_seo_agent -->|"load audit rows"| node_csv_loader
node_csv_loader -->|"parse CSV"| node_audit_csv
node_runtime_config -.->|"proxy credentials"| node_llm
node_runtime_config -.->|"service account"| node_ga4_api
node_deployment -->|"start service"| node_api

click node_ui "https://github.com/amit2003dh/spikeai/blob/main/src/ui.html"
click node_api "https://github.com/amit2003dh/spikeai/blob/main/src/app.js"
click node_orchestrator "https://github.com/amit2003dh/spikeai/blob/main/src/orchestrator.js"
click node_llm "https://github.com/amit2003dh/spikeai/blob/main/src/llm.js"
click node_ga4_agent "https://github.com/amit2003dh/spikeai/blob/main/src/agents/ga4Agent.js"
click node_seo_agent "https://github.com/amit2003dh/spikeai/blob/main/src/agents/seoAgent.js"
click node_csv_loader "https://github.com/amit2003dh/spikeai/blob/main/src/utils/dataLoader.js"
click node_runtime_config "https://github.com/amit2003dh/spikeai/blob/main/.env"
click node_deployment "https://github.com/amit2003dh/spikeai/blob/main/deploy.sh"

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_api,node_orchestrator,node_llm toneBlue
class node_ga4_agent,node_seo_agent,node_csv_loader toneAmber
class node_ga4_api,node_audit_csv,node_litellm toneMint
class node_ui,node_runtime_config,node_deployment toneNeutral
```

## Components

### Node.js Service

- [Express API](https://github.com/amit2003dh/spikeai/blob/main/src/app.js): HTTP server · Exposes POST /query on port 8080. · `src/app.js`
- [Orchestrator](https://github.com/amit2003dh/spikeai/blob/main/src/orchestrator.js): request router · Selects analytics, SEO, or combined processing and owns the response. · `src/orchestrator.js`
- [LLM Adapter](https://github.com/amit2003dh/spikeai/blob/main/src/llm.js): semantic boundary · Builds report intent, classifies queries, and generates answers. · `src/llm.js`

### Analysis Agents

- [GA4 Agent](https://github.com/amit2003dh/spikeai/blob/main/src/agents/ga4Agent.js): analytics agent · Constrains requests to GA4 runReport shapes and handles empty data. · `src/agents/ga4Agent.js`
- [SEO Agent](https://github.com/amit2003dh/spikeai/blob/main/src/agents/seoAgent.js): audit agent · Filters Screaming Frog audit records including title-tag conditions. · `src/agents/seoAgent.js`
- [CSV Loader](https://github.com/amit2003dh/spikeai/blob/main/src/utils/dataLoader.js): data ingestion · Parses audit CSV into in-memory records. · `src/utils/dataLoader.js`

### Data & AI Services

- **Google Analytics Data API**: analytics API
- **Screaming Frog CSV**: SEO audit export
- **LiteLLM Proxy**: OpenAI-compatible endpoint

### Other components

- [Query UI](https://github.com/amit2003dh/spikeai/blob/main/src/ui.html): HTML client · `src/ui.html`
- [Runtime Credentials](https://github.com/amit2003dh/spikeai/blob/main/.env): environment configuration · Supplies LiteLLM and Google service-account credentials. · `.env`
- [Deployment Script](https://github.com/amit2003dh/spikeai/blob/main/deploy.sh): runtime launcher · Installs dependencies and starts the Node.js service. · `deploy.sh`

## Connections

- Query UI → Express API: POST /query
- Express API → Orchestrator: delegate query
- Orchestrator → LLM Adapter: classify and answer
- Orchestrator → GA4 Agent: analytics work
- Orchestrator → SEO Agent: SEO work
- Orchestrator → LLM Adapter: fuse bounded results · Combined results are limited to roughly 50 rows.
- LLM Adapter → GA4 Agent: structured report intent
- LLM Adapter → LiteLLM Proxy: OpenAI SDK
- GA4 Agent → Google Analytics Data API: runReport
- SEO Agent → CSV Loader: load audit rows
- CSV Loader → Screaming Frog CSV: parse CSV
- Runtime Credentials → LLM Adapter: proxy credentials
- Runtime Credentials → Google Analytics Data API: service account
- Deployment Script → Express API: start service