How mozilla/blurts-server works
Main Components
• Web Frontend – Representing the user interface built using Next.js. This includes public pages (the landing page, FAQ, about, etc.) and authenticated user areas (dashboard, account settings, etc.).
• API Layer / Backend – Your Next.js API routes contained in the “src/api” directory. These endpoints cover user functions (scan, email verification, unsubscribe, etc.), admin endpoints, and integration with external notifications such as HIBP and FxA.
• Database – The PostgreSQL database (with migrations in “src/db/migrations”, table definitions in “src/db/tables”) that stores user data, breach information, email preferences, and other persistent state.
• Message Broker / PubSub – The integration with GCP PubSub that is used for ingesting breach data from HIBP notifications. Also include the local emulator setup as part of the development environment.
• Cron Jobs / Background Workers – Several Node scripts (in “src/functions”, “src/scripts/cronjobs”) process tasks such as sending breach alerts, updating scan results, removing data brokers, and more.
• Email Service – The email templates (in “src/emails/templates”) and the supporting code that render and send different notifications to users (breach alerts, upcoming expirations, signup reports, etc.).
• External Services – HIBP (Have I Been Pwned), Firefox Accounts (FxA) for authentication, and possibly additional integrations such as localization through Fluent, as well as monitoring and telemetry (Glean).
Relationships and Interactions
• User Interaction Flow: The web frontend communicates through browser requests to the backend API endpoints. Users sign up, check for breaches, and view their dashboards.
• API and Database: API endpoints interact with the Postgres database to retrieve, update, or store breach, user, and settings data.
• Breach Notification Processing: HIBP sends webhook notifications (which your endpoints under “src/app/api/v1/hibp/notify” receive) that are then pushed onto a PubSub queue. A separate cron job or worker consumes those messages, processes breach data, and triggers corresponding email notifications.
• Email Processing: After processing breach data, the system uses pre-built MJML/React templates (stored under “src/emails/templates”) to generate and send emails to affected users.
• Authentication and Localization: The web frontend leverages FxA for user identity and uses Fluent for localized UI content (the “locales” directories and helper hooks in “src/app/hooks/l10n”).
• DevOps/Deployment: The application is containerized (there’s a Dockerfile and Cloud Run configuration files) and uses GitHub Actions workflows for CI/CD (see “.github/workflows/*”).
Architectural Patterns and Design Principles
• Modular Separation – The project separates concerns by dividing components into clear “app,” “api,” “db,” “emails,” “scripts,” and “functions” directories.
• Server/Client Separation – With Next.js’s file structure (using both server and client components), it clearly distinguishes between user interface code and API/backend logic.
• Event-Driven Processing – Employing PubSub for asynchronously handling breach alerts, enabling decoupled processing.
• Continuous Deployment & Testing – The repository includes extensive automated tests (unit tests via Jest, E2E tests with Playwright), and GitHub Actions work to enforce quality.
• Localization – Use of Fluent for internationalization and localization, ensuring UI text is separated from code.
Final Touches
• Verify that all key technologies (Next.js, PostgreSQL, GCP PubSub, Docker, etc.) are visually represented.