# mozilla/blurts-server architecture

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

- Interactive diagram: https://gitdiagram.com/mozilla/blurts-server
- Repository: https://github.com/mozilla/blurts-server

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UserBrowser["User Browser"]:::external
    WebFrontend["Web Frontend (Next.js Client UI)"]:::frontend
    Localization["Localization (Fluent)"]:::localization
    Api["API Layer / Backend (Next.js API routes)"]:::backend
    HibpNotify["HIBP Notify Endpoint"]:::backend
    Database["PostgreSQL Database"]:::database
    PubSub["GCP PubSub"]:::external
    Cron["Cron Jobs / Background Workers"]:::worker
    Email["Email Service"]:::email
    ExtHibp["HIBP"]:::external
    ExtFxA["Firefox Accounts"]:::external
    DevOps["DevOps Deployment (Docker & GitHub Actions)"]:::devops

    %% User Flow
    UserBrowser -->|"browses"| WebFrontend
    Localization -->|"localizedUI"| WebFrontend
    WebFrontend -->|"APIcalls"| Api
    Api -->|"CRUD"| Database

    %% External Service Integrations
    ExtFxA -->|"authenticate"| Api
    ExtHibp -->|"webhook"| HibpNotify
    Api --- HibpNotify
    HibpNotify -->|"pushBreachData"| PubSub
    PubSub -->|"deliverMessages"| Cron
    Cron -->|"triggerEmails"| Email
    Email -->|"sendNotification"| UserBrowser

    %% Deployment
    DevOps -->|"deploys"| Api
    DevOps -->|"deploys"| Cron

    %% Click Events for Component Mapping
    click WebFrontend "https://github.com/mozilla/blurts-server/tree/main/src/app/(proper_react)/(redesign)/(public)"
    click Api "https://github.com/mozilla/blurts-server/tree/main/src/app/api/v1"
    click Database "https://github.com/mozilla/blurts-server/tree/main/src/db/migrations"
    click Database "https://github.com/mozilla/blurts-server/tree/main/src/db/tables"
    click Cron "https://github.com/mozilla/blurts-server/tree/main/src/scripts/cronjobs"
    click Cron "https://github.com/mozilla/blurts-server/tree/main/src/app/functions/cronjobs"
    click Email "https://github.com/mozilla/blurts-server/tree/main/src/emails/templates"
    click Email "https://github.com/mozilla/blurts-server/blob/main/src/emails/renderEmail.ts"
    click HibpNotify "https://github.com/mozilla/blurts-server/tree/main/src/app/api/v1/hibp/notify"
    click ExtFxA "https://github.com/mozilla/blurts-server/blob/main/src/app/api/auth/[...nextauth]"
    click Localization "https://github.com/mozilla/blurts-server/tree/main/src/app/hooks/l10n"
    click Localization "https://github.com/mozilla/blurts-server/tree/main/src/app/functions/l10n"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#f9a825,stroke-width:2px;
    classDef worker fill:#ffcc80,stroke:#f57c00,stroke-width:2px;
    classDef email fill:#f8bbd0,stroke:#c2185b,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
    classDef localization fill:#c5e1a5,stroke:#558b2f,stroke-width:2px;
    classDef devops fill:#eeeeee,stroke:#424242,stroke-width:2px;
```
