How alphagov/govuk-chat works
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.