# joon-solutions/looker-explore-assistant architecture

> Architecture diagram of the GitHub repository joon-solutions/looker-explore-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joon-solutions/looker-explore-assistant
- Repository: https://github.com/joon-solutions/looker-explore-assistant

## Overview

##### Project type and purpose
- This is a full-stack Looker Extension / API plugin that lets end users write natural-language prompts to generate Looker Explore queries.
- Frontend: a React + TypeScript single‐page application embedded in Looker via the Looker Extension SDK.
- Backend: Google Cloud–hosted services (Cloud Functions, Cloud Run) managed by Terraform, integrating with Vertex AI and BigQuery/Cloud SQL.
- Supporting tooling: example-generation scripts to populate BigQuery with prompt/response pairs, and a training notebook.

##### File structure
Top-level directories:
- explore-assistant-extension: React/TS front end, Redux slices, Webpack/Tailwind config, Looker Extension manifest
- explore-assistant-cloud-run: Python service (main.py) containerized for Cloud Run
- explore-assistant-backend: Terraform code to provision GCP resources (BigQuery datasets, Cloud Functions, Cloud Run, Cloud SQL)
- explore-assistant-examples: scripts to generate and load example prompt/response data into BigQuery
- explore-assistant-training: notebook and data for one-off model-training example generation

Key config files: Dockerfile and docker-compose.yml for cloud-run service, requirements.txt for Python dependencies, Terraform .tf files under terraform/*.

##### README for additional insights
- The extension queries Vertex AI to translate human text into a Looker Explore URL.
- User history is kept in browser localStorage; structured logs (input/output tokens) are streamed to BigQuery.
- BigQuery holds both example prompt/response pairs and the analytics logs.
- Deployment leverages Terraform (GCS backend, BigQuery, Cloud Functions, Cloud Run, Cloud SQL).

##### Main components & their interactions
a. User & Looker Client
- The user interacts with the Looker UI. The extension is loaded into Looker via the Embed/Extension SDK.
b. Frontend Extension
- React app (explore-assistant-extension) handles user input, history, and UI rendering.
- On prompt submission it calls the Backend API endpoint.
c. Backend API
- Cloud Run service (container: explore-assistant-cloud-run/main.py) or Cloud Function (terraform/cloud_function) exposes HTTP endpoints.
- Fetches example prompts from BigQuery and potentially Cloud SQL (for schema and state).
- Composes a one-shot prompt, calls Vertex AI REST API, receives generated Explore query.
- Logs request/response metadata (token counts, timestamps) into BigQuery or Cloud SQL.
d. Vertex AI
- Receives the composed prompt, returns the LLM output.
e. Data Stores
- BigQuery – host of example prompt/response pairs, log sink for structured logs.
- Cloud SQL – optional relational store for internal schema or other state.
f. Deployment & Provisioning
- Terraform modules under explore-assistant-backend/terraform create GCP resources.
- Cloud Storage backend for Terraform state.

##### Architectural patterns & design principles
- Clear separation of concerns: UI, API/service layer, data stores.
- Serverless compute (Cloud Run + Cloud Functions) for auto-scaling.
- Infrastructure as Code (Terraform) for reproducible deployments.
- Eventual consistency between logs and BigQuery sinks.
- One-shot prompt technique (no dedicated vector store for embeddings).

##### Essential elements
- Frontend: React/TS code, localStorage history, Looker Extension SDK
- Backend: Cloud Run and/or Cloud Function code, Python entrypoint, Dockerfile
- ML: Vertex AI service endpoint
- Data: BigQuery (examples + logs), Cloud SQL schema
- Infra as Code: Terraform modules, state backend

## Diagram (Mermaid)

```mermaid
graph TD
    User["End User"]:::external
    LookerUI["Looker UI"]:::external

    subgraph "Frontend Layer"
        RExt["React Extension"]:::frontend
        click RExt "https://github.com/joon-solutions/looker-explore-assistant/tree/main/explore-assistant-extension/"
        Index["index.tsx"]:::frontend
        click Index "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/index.tsx"
        App["App.tsx"]:::frontend
        click App "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/App.tsx"
        Slice1["assistantSlice.ts"]:::frontend
        click Slice1 "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/slices/assistantSlice.ts"
        Slice2["authSlice.ts"]:::frontend
        click Slice2 "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/slices/authSlice.ts"
        Hook1["useBigQueryExamples.ts"]:::frontend
        click Hook1 "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/hooks/useBigQueryExamples.ts"
        Hook2["useLocalStorageHistory.ts"]:::frontend
        click Hook2 "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/hooks/useLocalStorageHistory.ts"
        Hook3["useOAuthAuthentication.ts"]:::frontend
        click Hook3 "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/hooks/useOAuthAuthentication.ts"
        Hook4["useSendVertexMessage.ts"]:::frontend
        click Hook4 "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/src/hooks/useSendVertexMessage.ts"
        Manifest["manifest.lkml"]:::frontend
        click Manifest "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-extension/manifest.lkml"
    end

    subgraph "Backend Layer"
        CRS["Cloud Run Service"]:::compute
        click CRS "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-cloud-run/main.py"
        DF["Dockerfile"]:::compute
        click DF "https://github.com/joon-solutions/looker-explore-assistant/tree/main/explore-assistant-cloud-run/Dockerfile"
        Req["requirements.txt"]:::compute
        click Req "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-cloud-run/requirements.txt"
        DC["docker-compose.yml"]:::compute
        click DC "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-cloud-run/docker-compose.yml"
        CF["Cloud Function"]:::compute
        click CF "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/cloud_function/main.tf"
    end

    subgraph "Data Stores"
        BQ["BigQuery"]:::datastore
        click BQ "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/bigquery/main.tf"
        BQEX["bigquery_examples.tf"]:::datastore
        click BQEX "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/bigquery_examples.tf"
        SQL["Cloud SQL"]:::datastore
        click SQL "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/cloud_sql/main.tf"
        SQLsch["schema.sql"]:::datastore
        click SQLsch "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/cloud_sql/schema.sql"
        SQLtab["create_tables.py"]:::datastore
        click SQLtab "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/cloud_sql/create_tables.py"
    end

    VertexAI["Vertex AI"]:::ml

    subgraph "Terraform Infra"
        TFRoot["Root Config"]:::infra
        click TFRoot "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/main.tf"
        TFVar["variables.tf"]:::infra
        click TFVar "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/variables.tf"
        TFBack["GCS Backend"]:::infra
        click TFBack "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/backends/backend-gcs.tf"
        CRMod["cloud_run module"]:::infra
        click CRMod "https://github.com/joon-solutions/looker-explore-assistant/blob/main/explore-assistant-backend/terraform/cloud_run/main.tf"
    end

    User -->|"interacts with"| LookerUI
    LookerUI -->|"loads extension"| RExt
    RExt -->|"HTTP/REST"| CRS
    RExt -->|"logs history & tokens"| BQ

    CRS -->|"SQL queries & logs"| BQ
    CRS -->|"SQL queries"| SQL
    CRS -->|"REST call"| VertexAI
    VertexAI -->|"LLM response"| CRS
    CRS -->|"HTTP response"| RExt

    TFRoot -.->|"provisions"| CRS
    CRMod -.-> CRS
    TFRoot -.->|"provisions"| CF
    TFRoot -.->|"provisions"| BQ
    TFRoot -.->|"provisions"| BQEX
    TFRoot -.->|"provisions"| SQL
    TFRoot -.->|"provisions"| SQLsch
    TFRoot -.-> TFBack

    classDef frontend fill:#E3F2FD,stroke:#2196F3;
    classDef compute fill:#E8F5E9,stroke:#4CAF50;
    classDef datastore fill:#FFF3E0,stroke:#FB8C00;
    classDef ml fill:#F3E5F5,stroke:#9C27B0;
    classDef infra fill:#ECEFF1,stroke:#78909C;
    classDef external fill:#CFD8DC,stroke:#607D8B;
```
