# myaggression/flaky-guard architecture

> Architecture diagram of the GitHub repository myaggression/flaky-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/myaggression/flaky-guard
- Repository: https://github.com/myaggression/flaky-guard

## Overview

1. **Overall shape**
   - Flaky Guard is a **Next.js + PostgreSQL** application centered on **GitHub App webhook ingestion**.
   - The system has two main faces: a **server-side ingestion/analytics pipeline** and a **read-only dashboard/API layer** for viewing repository health, test insights, regressions, and risk.

2. **Primary runtime boundary**
   - The repo is mostly the `web/` app, which contains the Next.js server, API routes, pages, and all processing logic.
   - Persistence is through **Prisma** to **PostgreSQL** using the schema in `prisma/schema.prisma` and migrations under `prisma/migrations`.

3. **Event ingestion path**
   - The key entrypoint is `POST /webhooks/github`.
   - GitHub sends `workflow_run` events when Actions runs complete; the handler verifies the webhook signature, rejects oversized payloads, and then starts ingestion.
   - This is the main boundary where external GitHub activity enters the system.

4. **Workflow-run processing pipeline**
   - On a completed run, the app upserts the **Repository** and **WorkflowRun** records.
   - If the run is tied to a pull request, it resolves and stores the PR number.
   - It then downloads workflow artifacts from GitHub, unpacks them, and parses JUnit XML to persist **TestRun** and **TestCaseResult** data.

5. **Analytics engines**
   - After raw test data lands in the database, the system recomputes derived intelligence using several internal engines in `web/src/lib/`:
     - **JUnit parsing** for test result extraction
     - **Flaky detection** for pass/fail switching behavior
     - **Regression detection** for new broken/flaky/performance issues
     - **Insight engine** for classifying tests into categories like broken, flaky, timing unstable, risky, stable
     - **Risk engine** for repo-level risk snapshots and trends
   - These are server-side computation modules, not client-side logic.

6. **PR comment automation**
   - If the webhook originated from a pull request workflow run, the app builds a summary comment containing workflow status, regressions, and flaky tests.
   - It upserts that comment back to GitHub using a stable marker (`<!-- flaky-guard -->`) so repeated runs update the same PR comment instead of creating duplicates.

7. **Read model / dashboard APIs**
   - The UI does not read raw tables directly; it uses API routes under `web/src/app/api/`.
   - Main endpoints are:
     - `/api/health` for service/DB health
     - `/api/health/:owner/:repo` for the repository dashboard payload
     - `/api/health/:owner/:repo/tests` for test-level flaky data
     - `/api/insights/:owner/:repo`
     - `/api/regressions/:owner/:repo`
     - `/api/risk/:owner/:repo`
     - `/api/repositories` for multi-repo listing
   - This split creates a clear boundary between stored operational data and the API-shaped data used by the UI.

8. **UI surfaces**
   - The dashboard is delivered by Next.js pages under `web/src/app/`, including:
     - `/:owner/:repo` for the repository view
     - `/repos` for the multi-repo listing
   - These pages are likely server-rendered or data-fed via the API layer, keeping the presentation layer thin compared with the backend analytics.

9. **Data model**
   - The schema and migrations indicate a history-oriented model built around:
     - repositories
     - workflow runs and attempts
     - test runs
     - individual test case results
     - test case insights
     - regression records
     - risk snapshots
   - This supports time-series style analytics such as trends, last-48h regressions, and per-branch/workflow comparisons.

10. **External integrations**
    - The only major external service is **GitHub**:
      - GitHub App installation permissions
      - Webhook delivery
      - Artifact downloads
      - PR comment updates
      - Repository/workflow metadata
    - The database is the other core dependency; there is no separate message queue or worker service in this repo.

11. **Operational/deployment model**
    - The app can run locally or in Docker, with `docker-compose.yml` providing the app and Postgres.
    - Health checks are exposed for orchestration, and the readme emphasizes running Prisma migrations before startup.
    - This suggests a single deployable Node/Next.js service with database-backed state, rather than a distributed microservice architecture.

12. **Important architectural boundary**
    - There is **no user login layer** in the current design.
    - Access is repo-scoped and based on GitHub App installation plus webhook-fed data, so the security boundary is primarily **GitHub permissions + webhook verification + database isolation by repository**.

Main entry points: [`prisma/schema.prisma`](https://github.com/myaggression/flaky-guard/blob/main/prisma/schema.prisma) (Prisma schema), [`web/src/app/webhooks/github/route.ts`](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/webhooks/github/route.ts) (GitHub webhook), [`web/src/app/[owner]/[repo]/page.tsx`](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/[owner]/[repo]/page.tsx) (Repo page), [`web/src/lib/junit-parser.ts`](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/junit-parser.ts) (JUnit parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_web["Next.js app"]
  node_n_webhook["GitHub webhook<br/>route<br/>[route.ts]"]
  node_n_server["Server core<br/>runtime<br/>[server.ts]"]
  node_n_github["GitHub client<br/>integration<br/>[github.ts]"]
  node_n_artifacts["Artifact processor<br/>pipeline"]
  node_n_junit["JUnit parser<br/>[junit-parser.ts]"]
  node_n_flaky["Flaky detector<br/>analysis<br/>[test-flaky.ts]"]
  node_n_regressions["Regression detector<br/>analysis"]
  node_n_insights["Insight engine<br/>classifier<br/>[insight-engine.ts]"]
  node_n_risk["Risk engine<br/>analytics<br/>[risk-engine.ts]"]
  node_n_comment["PR comment<br/>automation<br/>[pr-comment.ts]"]
  node_n_api_health["Health API<br/>[route.ts]"]
  node_n_api_repo["Repo health API<br/>[route.ts]"]
  node_n_api_tests["Tests API<br/>[route.ts]"]
  node_n_api_insights["Insights API<br/>[route.ts]"]
  node_n_api_regressions["Regressions API<br/>[route.ts]"]
  node_n_api_risk["Risk API<br/>[route.ts]"]
  node_n_api_repos["Repos API<br/>[route.ts]"]
  node_n_page_repo["Repo page<br/>[page.tsx]"]
  node_n_page_repos["Repos page<br/>[page.tsx]"]
end

subgraph group_grp_data["Persistence"]
  node_n_prisma[("Prisma schema<br/>[schema.prisma]")]
  node_n_migrations["Migrations"]
end

subgraph group_grp_ext["External systems"]
  node_n_db[("PostgreSQL<br/>database")]
  node_n_github_ext(("GitHub<br/>external service"))
end

node_n_webhook -->|"handled by"| node_n_server
node_n_webhook -->|"delivered from"| node_n_github_ext
node_n_webhook -->|"calls"| node_n_github
node_n_webhook -->|"ingests"| node_n_artifacts
node_n_artifacts -->|"parses with"| node_n_junit
node_n_junit -->|"feeds"| node_n_flaky
node_n_junit -->|"feeds"| node_n_regressions
node_n_flaky -->|"categorizes into"| node_n_insights
node_n_regressions -->|"categorizes into"| node_n_insights
node_n_junit -->|"feeds"| node_n_risk
node_n_insights -->|"feeds"| node_n_risk
node_n_webhook -->|"may write"| node_n_comment
node_n_comment -->|"upserts via"| node_n_github
node_n_api_repo -->|"reads"| node_n_prisma
node_n_api_tests -->|"reads"| node_n_prisma
node_n_api_insights -->|"reads"| node_n_prisma
node_n_api_regressions -->|"reads"| node_n_prisma
node_n_api_risk -->|"reads"| node_n_prisma
node_n_api_repos -->|"reads"| node_n_prisma
node_n_page_repo -->|"loads"| node_n_api_repo
node_n_page_repo -->|"loads"| node_n_api_tests
node_n_page_repo -->|"loads"| node_n_api_insights
node_n_page_repo -->|"loads"| node_n_api_regressions
node_n_page_repo -->|"loads"| node_n_api_risk
node_n_page_repos -->|"loads"| node_n_api_repos
node_n_prisma -->|"persists to"| node_n_db
node_n_migrations -->|"evolves"| node_n_prisma

click node_n_webhook "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/webhooks/github/route.ts"
click node_n_server "https://github.com/myaggression/flaky-guard/blob/main/web/src/server.ts"
click node_n_github "https://github.com/myaggression/flaky-guard/blob/main/web/src/github.ts"
click node_n_artifacts "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/artifact-processor.ts"
click node_n_junit "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/junit-parser.ts"
click node_n_flaky "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/test-flaky.ts"
click node_n_regressions "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/regression-detector.ts"
click node_n_insights "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/insight-engine.ts"
click node_n_risk "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/risk-engine.ts"
click node_n_comment "https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/pr-comment.ts"
click node_n_api_health "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/health/route.ts"
click node_n_api_repo "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/health/[owner]/[repo]/route.ts"
click node_n_api_tests "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/health/[owner]/[repo]/tests/route.ts"
click node_n_api_insights "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/insights/[owner]/[repo]/route.ts"
click node_n_api_regressions "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/regressions/[owner]/[repo]/route.ts"
click node_n_api_risk "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/risk/[owner]/[repo]/route.ts"
click node_n_api_repos "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/repositories/route.ts"
click node_n_page_repo "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/[owner]/[repo]/page.tsx"
click node_n_page_repos "https://github.com/myaggression/flaky-guard/blob/main/web/src/app/repos/page.tsx"
click node_n_prisma "https://github.com/myaggression/flaky-guard/blob/main/prisma/schema.prisma"
click node_n_migrations "https://github.com/myaggression/flaky-guard/tree/main/prisma/migrations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_webhook,node_n_server,node_n_github,node_n_artifacts,node_n_junit,node_n_flaky,node_n_regressions,node_n_insights,node_n_risk,node_n_comment,node_n_api_health,node_n_api_repo,node_n_api_tests,node_n_api_insights,node_n_api_regressions,node_n_api_risk,node_n_api_repos,node_n_page_repo,node_n_page_repos toneBlue
class node_n_prisma,node_n_migrations toneAmber
class node_n_db,node_n_github_ext toneMint
```

## Components

### Next.js app

Single deployable web/runtime boundary containing routes, pages, and server-side processing.

- [GitHub webhook](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/webhooks/github/route.ts): route · Ingress for completed workflow_run events; verifies signature and starts ingestion. · `web/src/app/webhooks/github/route.ts`
- [Server core](https://github.com/myaggression/flaky-guard/blob/main/web/src/server.ts): runtime · Main server bootstrap and request handling boundary for the Next.js app. · `web/src/server.ts`
- [GitHub client](https://github.com/myaggression/flaky-guard/blob/main/web/src/github.ts): integration · Wrapper for GitHub API calls, artifact download, and PR comment updates. · `web/src/github.ts`
- [Artifact processor](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/artifact-processor.ts): pipeline · Downloads and unpacks workflow artifacts before parsing test outputs. · `web/src/lib/artifact-processor.ts`
- [JUnit parser](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/junit-parser.ts): parser · Extracts structured test cases from JUnit XML. · `web/src/lib/junit-parser.ts`
- [Flaky detector](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/test-flaky.ts): analysis · Detects pass/fail switching and other flaky behavior. · `web/src/lib/test-flaky.ts`
- [Regression detector](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/regression-detector.ts): analysis · Identifies new broken, flaky, or performance regressions. · `web/src/lib/regression-detector.ts`
- [Insight engine](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/insight-engine.ts): classifier · Classifies tests into broken, flaky, timing-unstable, risky, or stable. · `web/src/lib/insight-engine.ts`
- [Risk engine](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/risk-engine.ts): analytics · Computes repository-level risk snapshots and trends. · `web/src/lib/risk-engine.ts`
- [PR comment](https://github.com/myaggression/flaky-guard/blob/main/web/src/lib/pr-comment.ts): automation · Builds and upserts the stable-marker pull request summary comment. · `web/src/lib/pr-comment.ts`
- [Health API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/health/route.ts): api · Service and database health endpoint. · `web/src/app/api/health/route.ts`
- [Repo health API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/health/[owner]/[repo]/route.ts): api · Repository dashboard payload endpoint. · `web/src/app/api/health/[owner]/[repo]/route.ts`
- [Tests API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/health/[owner]/[repo]/tests/route.ts): api · Test-level flaky data endpoint for a repository. · `web/src/app/api/health/[owner]/[repo]/tests/route.ts`
- [Insights API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/insights/[owner]/[repo]/route.ts): api · Repository insight summaries for the dashboard. · `web/src/app/api/insights/[owner]/[repo]/route.ts`
- [Regressions API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/regressions/[owner]/[repo]/route.ts): api · Regression summaries and recent issue feeds. · `web/src/app/api/regressions/[owner]/[repo]/route.ts`
- [Risk API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/risk/[owner]/[repo]/route.ts): api · Repository risk snapshot and trend endpoint. · `web/src/app/api/risk/[owner]/[repo]/route.ts`
- [Repos API](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/api/repositories/route.ts): api · Multi-repository listing endpoint. · `web/src/app/api/repositories/route.ts`
- [Repo page](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/[owner]/[repo]/page.tsx): page · Repository dashboard surface for a single owner/repo. · `web/src/app/[owner]/[repo]/page.tsx`
- [Repos page](https://github.com/myaggression/flaky-guard/blob/main/web/src/app/repos/page.tsx): page · Multi-repository listing surface. · `web/src/app/repos/page.tsx`

### Persistence

Prisma schema, migrations, and database access layer.

- [Prisma schema](https://github.com/myaggression/flaky-guard/blob/main/prisma/schema.prisma): schema · Database model for repositories, runs, tests, insights, regressions, and risk. · `prisma/schema.prisma`
- [Migrations](https://github.com/myaggression/flaky-guard/tree/main/prisma/migrations): db migrations · Schema evolution history for the PostgreSQL-backed data model. · `prisma/migrations`

### External systems

GitHub and PostgreSQL dependencies outside the repo.

- **PostgreSQL**: database · Primary persistence store for raw and derived repository health data.
- **GitHub**: external service · Webhook source, artifact host, and pull request target.

## Connections

- GitHub webhook → Server core: handled by · Webhook requests enter the Next.js server runtime.
- GitHub webhook → GitHub: delivered from · GitHub sends workflow_run events.
- GitHub webhook → GitHub client: calls · Uses GitHub API for metadata and artifact access.
- GitHub webhook → Artifact processor: ingests · Completed runs trigger artifact retrieval and unpacking.
- Artifact processor → JUnit parser: parses with · Extracted artifacts are turned into structured test records.
- JUnit parser → Flaky detector: feeds · Parsed test outcomes are analyzed for flakiness.
- JUnit parser → Regression detector: feeds · Test results drive regression detection.
- Flaky detector → Insight engine: categorizes into · Flaky signals contribute to the insight classifications.
- Regression detector → Insight engine: categorizes into · Regression signals contribute to the insight classifications.
- JUnit parser → Risk engine: feeds · Historical test data informs risk snapshots and trends.
- Insight engine → Risk engine: feeds · Insight classifications contribute to repository risk.
- GitHub webhook → PR comment: may write · Pull request runs trigger summary comment updates.
- PR comment → GitHub client: upserts via · Uses a stable marker to update the same PR comment.
- Repo health API → Prisma schema: reads · Repository dashboard data is shaped from persisted records.
- Tests API → Prisma schema: reads · Test-level API reads database state.
- Insights API → Prisma schema: reads · Insight API reads computed classification data.
- Regressions API → Prisma schema: reads · Regression API reads regression records.
- Risk API → Prisma schema: reads · Risk API reads repository risk snapshots.
- Repos API → Prisma schema: reads · Listing endpoint reads repository inventory.
- Repo page → Repo health API: loads · Repository page consumes the dashboard payload endpoint.
- Repo page → Tests API: loads · Repository page fetches test-level detail.
- Repo page → Insights API: loads · Repository page fetches insights.
- Repo page → Regressions API: loads · Repository page fetches regressions.
- Repo page → Risk API: loads · Repository page fetches risk data.
- Repos page → Repos API: loads · Repos page consumes the multi-repo listing.
- Prisma schema → PostgreSQL: persists to · Prisma maps the schema to PostgreSQL.
- Migrations → Prisma schema: evolves · Migrations track schema changes.
