# alphagov/govuk-chat architecture

> Architecture diagram of the GitHub repository alphagov/govuk-chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alphagov/govuk-chat
- Repository: https://github.com/alphagov/govuk-chat

## Overview

##### And Label Main Components
- Web Client & Frontend: Represent browsers or other clients that interact with the Rails views (HTML/JS/CSS assets). This layer renders the chat, onboarding flows, administrative dashboards, and other static/dynamic pages.
- Rails Application Server: At the core, structure the application as per the MVC pattern. Illustrate Controllers (chat, onboarding, sessions, admin, errors, etc.), Models (representing Questions, Answers, Conversations, Users, etc.), and Views (templates for rendering pages and emails).
- Background Processing Layer: Highlight Sidekiq-based background jobs (as seen in app/jobs and config/initializers/sidekiq.rb) that handle asynchronous tasks such as answer composition, notifications, and processing data (e.g., job classes like ComposeAnswerJob, NotifySlackWaitingListFullJob).
- Answer Composition Pipeline: Show a dedicated subsystem (from lib/answer_composition) that orchestrates multiple pipelines for answer generation. Break out components for:
○ LLM integrations with OpenAI and Claude (each with rephrasers, routers, and structured answer composers)
○ Guardrails / validations to ensure safe responses (lib/guardrails modules and related pipelines)
○ Search and content chunking (referencing lib/chunking and lib/search modules)
- Database: Include the persistence layer using the configured database (details in config/database.yml and numerous migration files). Indicate key data sources for Conversations, Questions, Answers, and User-related records.
- External Integrations and Dependencies:
○ OpenSearch: Represent the search engine integration (with healthchecks and configuration in config/opensearch.yml) used to retrieve or rank GOV.UK content.
○ Message Queue: Show components for messaging (lib/message_queue) that handle content synchronization and processing requests.
○ Slack: Represent the integration (lib/slack_poster) for administrative or alert notifications.
- Infrastructure and Deployment:
○ Include Docker & govuk_docker as the containerization and orchestration framework (Dockerfile, .dockerignore, and associated docs).
○ Identify CI/CD pipelines (GitHub Actions workflows listed in .github/workflows) that automate testing, deployment, and releases.

##### Relationships and Data Flow
- Inside the Rails Application, show flows from Controllers to Models (data retrieval and persistence) and from Controllers to Views (presentation logic).
- How background jobs decouple complex processes: for instance, a chat question received by a controller triggers a background job which invokes the answer composition pipeline.
- Data flow from admin actions (through administrative controllers and mailers) into system logs, metrics collection (lib/prometheus_metrics), and monitoring tools.

##### Architectural Patterns and Design Principles
- MVC: Clearly show the segregation of responsibilities between Controllers, Views, and Models.
- Asynchronous Processing: Distinguish how background jobs (via Sidekiq) manage long-running tasks, ensuring smooth API response times.
- External API Integrations: Emphasize decoupling of LLM providers so business logic can easily extend support for additional services.
- Resilience & Monitoring: Include error-handling components (errors_controller, healthcheck modules) and integrations with monitoring (Prometheus and Slack).

##### Implementation Steps for the Principal Software Engineer
- Break out the Rails application into its logical components (controllers, models, views) and show how the background job system integrates with these.
- Detail the answer composition subsystem by mapping out the LLM integrations, chain-of-pipelines (including question rephrasers and router modules), and the guardrails modules.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Web Client & Frontend
    subgraph "Web Client & Frontend"
        WC1["Browser/Client"]:::frontend
        WC2["Rails Views (Frontend)"]:::frontend
        WC3["Rails Assets"]:::frontend
    end

    %% Rails Application Server (MVC)
    subgraph "Rails Application Server (MVC)"
        RA1["Controllers"]:::rails
        RA2["Models"]:::rails
        RA3["Views (Rails MVC)"]:::rails
    end

    %% Background Processing Layer
    subgraph "Background Processing (Sidekiq)"
        BP1["Job Classes"]:::background
        BP2["Sidekiq Config"]:::background
        BP3["Sidekiq YAML"]:::background
    end

    %% Answer Composition Pipeline
    subgraph "Answer Composition Pipeline"
        AC1["Pipeline Logic"]:::pipeline
        AC2["Pipeline Runner"]:::pipeline
        AC3["OpenAI Integration"]:::pipeline
        AC4["Claude Integration"]:::pipeline
    end

    %% Database Layer
    subgraph "Database"
        DB1["Database Config"]:::database
        DB2["Database Migrations"]:::database
        DB3["Database Schema"]:::database
    end

    %% External Integrations
    subgraph "External Integrations"
        EI1["OpenSearch Integration"]:::external
        EI2["BigQuery Export"]:::external
        EI3["Message Queue"]:::external
        EI4["Slack Notifications"]:::external
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        ID1["Docker Configuration"]:::infrastructure
        ID2["CI/CD Pipelines"]:::infrastructure
        ID3["Environment Configuration"]:::infrastructure
    end

    %% Data Flow Connections
    WC1 -->|"HTTP_Request"| RA1
    WC2 -->|"Asset_Load"| RA1
    WC3 -->|"Asset_Load"| RA1

    RA1 -->|"enqueue_job"| BP1
    RA1 -->|"initiate_pipeline"| AC1
    RA1 -->|"CRUD_ops"| DB1
    RA1 -->|"admin_alert"| EI4

    BP1 -->|"trigger_processing"| AC1
    BP1 -->|"update_db"| DB1

    AC1 -->|"run_pipeline"| AC2
    AC2 -->|"call_OpenAI"| AC3
    AC2 -->|"call_Claude"| AC4
    AC1 -->|"search_query"| EI1
    AC1 -->|"export_data"| EI2
    AC1 -->|"sync_message"| EI3
    AC1 -->|"notify"| EI4

    %% Infrastructure Deployment Connections (dotted lines)
    ID1 ---|"deployed_on"| RA1
    ID1 ---|"deployed_on"| BP1
    ID1 ---|"deployed_on"| AC1
    ID2 ---|"automated_deploy"| RA1
    ID2 ---|"automated_deploy"| BP1
    ID2 ---|"automated_deploy"| AC1
    ID3 ---|"env_configured"| RA1
    ID3 ---|"env_configured"| BP1
    ID3 ---|"env_configured"| AC1
    ID3 ---|"env_configured"| DB1
    ID3 ---|"env_configured"| EI1

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef rails fill:#F8D7DA,stroke:#721C24,stroke-width:2px;
    classDef background fill:#FFF3CD,stroke:#856404,stroke-width:2px;
    classDef pipeline fill:#D4EDDA,stroke:#155724,stroke-width:2px;
    classDef database fill:#CCE5FF,stroke:#004085,stroke-width:2px;
    classDef external fill:#E2E3E5,stroke:#383D41,stroke-width:2px;
    classDef infrastructure fill:#FDFD96,stroke:#777,stroke-width:2px;

    %% Click Events for Component Mapping
    click WC2 "https://github.com/alphagov/govuk-chat/tree/main/app/views"
    click WC3 "https://github.com/alphagov/govuk-chat/tree/main/app/assets"
    click RA1 "https://github.com/alphagov/govuk-chat/tree/main/app/controllers"
    click RA2 "https://github.com/alphagov/govuk-chat/tree/main/app/models"
    click RA3 "https://github.com/alphagov/govuk-chat/tree/main/app/views"
    click BP1 "https://github.com/alphagov/govuk-chat/tree/main/app/jobs"
    click BP2 "https://github.com/alphagov/govuk-chat/blob/main/config/initializers/sidekiq.rb"
    click BP3 "https://github.com/alphagov/govuk-chat/blob/main/config/sidekiq.yml"
    click AC1 "https://github.com/alphagov/govuk-chat/tree/main/lib/answer_composition"
    click AC2 "https://github.com/alphagov/govuk-chat/blob/main/lib/answer_composition/pipeline_runner.rb"
    click AC3 "https://github.com/alphagov/govuk-chat/tree/main/lib/answer_composition/pipeline/openai"
    click AC4 "https://github.com/alphagov/govuk-chat/tree/main/lib/answer_composition/pipeline/claude"
    click DB1 "https://github.com/alphagov/govuk-chat/blob/main/config/database.yml"
    click DB2 "https://github.com/alphagov/govuk-chat/tree/main/db/migrate"
    click DB3 "https://github.com/alphagov/govuk-chat/blob/main/db/schema.rb"
    click EI1 "https://github.com/alphagov/govuk-chat/blob/main/config/opensearch.yml"
    click EI2 "https://github.com/alphagov/govuk-chat/tree/main/lib/bigquery"
    click EI3 "https://github.com/alphagov/govuk-chat/tree/main/lib/message_queue"
    click EI4 "https://github.com/alphagov/govuk-chat/blob/main/lib/slack_poster.rb"
    click ID1 "https://github.com/alphagov/govuk-chat/tree/main/Dockerfile"
    click ID2 "https://github.com/alphagov/govuk-chat/tree/main/.github/workflows"
    click ID3 "https://github.com/alphagov/govuk-chat/tree/main/Procfile"
```
