AskAnalytics is a web application used exclusively by GOV.UK staff for querying data insights from our Google Analytics 4 dataset using natural language and receiving responses in natural language.
The application is structured around two core components:
-
Frontend Application
- Developed using ReactJS, adhering to the GOV.UK design system.
- Responsible for rendering the user interface and sending queries to the backend API.
-
Backend API
- Implemented with Python3 using FastAPI.
- Manages CRUD operations for updating a PostgreSQL database that stores analytics usage data.
- Utilises LLM (Large Language Model) models via the LangChain framework to process user queries and generate SQL queries for the GA4 dataset.
AskAnalytics integrates closely with LangFuse, an open-source dashboard designed to log and visualise the execution flow of each LLM chain initiated by users. This integration serves as a crucial debugging tool, offering detailed diagrams for monitoring and troubleshooting application performance.
LangFuse can be set up locally using Docker Compose or accessed via a Cloud Run-hosted dashboard, providing flexibility in monitoring and managing application activities.
-
Python Version Management with pyenv
- Install and manage the required Python version specified in
backend/pyproject.tomlusing pyenv. Follow the installation instructions from pyenv GitHub.pyenv install 3.11.4 pyenv local 3.11.4
- Install and manage the required Python version specified in
-
Virtual Environment Management with Poetry
- Use Poetry for managing dependencies and creating a virtual environment specific to the project. Follow the installation guide on Poetry's official documentation.
poetry shell poetry install - Poetry manages package installation, virtual environments, and dependencies, ensuring project isolation and reproducibility.
- Use Poetry for managing dependencies and creating a virtual environment specific to the project. Follow the installation guide on Poetry's official documentation.
-
Running Dependencies
- Start PostgreSQL and LangFuse services using Docker Compose to ensure backend functionality:
docker-compose up -d db docker-compose up -d langfuse
- Start PostgreSQL and LangFuse services using Docker Compose to ensure backend functionality:
-
Environment Variables Management with direnv
- Copy
.envrc.templateto.envrc:cp .envrc.template .envrc - Use direnv for loading the
.envrcfile into the shell. Install direnv following the installation guide. - Allow direnv in the project directory:
direnv allow - Ensure the minimum required variables are set in
.envrc:ENV=your_environment DB_URL_LOCAL=your_database_url
- Copy
-
Launching the Backend
- Execute the following command within the
backend/directory to run the backend locally:make run-local
- Execute the following command within the
-
NodeJS and Yarn Setup
- Ensure NodeJS is installed using NVM with the correct version and install yarn globally:
npm i -g yarn
- Ensure NodeJS is installed using NVM with the correct version and install yarn globally:
-
Installing and Running
-
Navigate to the
frontend/directory and install frontend dependencies:cd frontend/ yarn -
Start the frontend development server:
yarn dev
-
- GitHub CI with Pre-commit
- GitHub enforces code quality checks with
pre-commit, ensuring adherence to coding standards (formatting, linting) on every commit. Commits failing these checks cannot be merged.# In repo root folder: make code-quality
- GitHub enforces code quality checks with
-
While the application currently has limited testing coverage, the backend includes unit tests implemented using pyenv:
cd backend/ pyenv .
-
Hosting on GCP Cloud Run
-
Before deploying to Cloud Run, ensure the frontend is compiled to the latest build:
cd frontend/ yarn build -
Contact the repository admin for deployment instructions tailored to our Cloud Run environment.
-
Future Enhancements
-
Work is underway to establish an automated deployment pipeline to streamline deployment processes and improve overall deployment efficiency.