amit2003dh/spikeai

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