Scout

Active

Three Services, One Intelligence Layer

AI analytics platform for automotive dealership marketing. Three independent services — a Go/Echo API, a Python/Flask RAG pipeline, and a Go/ADK chat system — share a single AlloyDB instance (PostgreSQL + pgvector) to deliver AI-generated analyses and conversational follow-up across six dealership performance domains.

GoPythonBigQueryVertex AIAlloyDBCloud Run

High-level view — Users, Scout platform (3 services on Cloud Run), GCP infrastructure, and external services

100%

📱

Client App

Dealership dashboard

🔐

JWT + RBAC

HS256, 24h TTL, 3-tier

⚡

Echo API

30+ REST endpoints

📨

Cloud Tasks

OIDC auth dispatch

🎯

4-Phase Orch.

Init → Gather → Generate → Finalize

📊

BigQuery

SQL from .sql files

📈

Looker

OAuth2 PDF export

🧠

Vertex AI

Gemini 3 Pro + Flash

📁

GCS Buckets

3 buckets: API, RAG, ADK

🗄️

AlloyDB

10 tables + pgvector

API•Core API (Go/Echo)•Tap a node for details

Key component

Infrastructure

Data flow

Core API (Go/Echo)

API

The central orchestrator. 30+ REST endpoints across auth, sessions, messages, tasks, users, groups, and analysis types. Cloud Tasks dispatches analysis jobs through a 4-phase pipeline: Initialize (validate session, load analysis type) → Data Gathering (parallel Looker PDF + BigQuery CSV) → Content Generation (Vertex AI Gemini 3 Pro, 8x retry on bad JSON) → Finalize (save markdown + summary + PDF, create initial chat message).

What Ships

→30+ REST endpoints across auth, sessions, messages, tasks, users, groups, and analysis types

→JWT auth (HS256, 24h TTL) + Stytch user management with 3-tier RBAC (user / admin_read_only / admin_write)

→4-phase analysis orchestrator: Initialize → Data Gathering → Content Generation → Finalize

→Cloud Tasks async dispatch with OIDC auth and W3C traceparent header propagation

→BigQuery parameterized SQL from .sql files with stored procedure support and GCS CSV export

→Looker OAuth2 integration for dashboard PDF fetching

→Vertex AI (Gemini 3 Pro for analysis, Flash for formatting/detection) with 5x model retry

→AI-powered analysis type detection using Gemini Flash with structured JSON output

→Gotenberg HTML-to-PDF conversion for analysis reports

→OpenTelemetry distributed tracing with Cloud Trace exporter

→Redis-backed rate limiting on analysis and chat endpoints

→Background watchdog for stalled task_executions (auto-timeout)

Impact

Dealerships get AI-powered analyses of their marketing spend, GA4 traffic, Google Ads performance, inventory VDP insights, and NCM 20 Group benchmarks — orchestrated from a single API that coordinates BigQuery data extraction, Looker dashboard PDF capture, and Vertex AI narrative generation into polished PDF reports.

Capability Comparison

	API: Core API (Go/Echo)	RAG: RAG Pipeline (Python/Flask)	Chat: Chat ADK (Go/ADK)
Language	Go 1.22+ (Echo v4)	Python 3.11+ (Flask)	Go 1.22+ (ADK)
Primary Role	Orchestration + REST API	Knowledge sync + chunking	Conversational AI
Database Tables	9 tables (sessions, users, tasks...)	1 table (rag_knowledge_base)	Reads RAG + writes token_usage_logs
GCS Usage	Write PDFs + CSVs to SCOUT_AI_BUCKET	Read markdown from RAG bucket	Read artifacts from SCOUT_AI_BUCKET
AI Model	Gemini 3 Pro + Flash (Vertex AI)	None (AlloyDB trigger embeds)	Gemini Flash (via ADK + code exec)
Auth	JWT (HS256) + Stytch + RBAC	GCP service account only	OIDC via Cloud Tasks dispatch
Async Pattern	Cloud Tasks dispatch + receive	Synchronous POST /	Receives from Cloud Tasks
Observability	OpenTelemetry + Cloud Trace	Cloud Run logs	Structured logging + token tracking