# supercheck-io/supercheck architecture

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

- Interactive diagram: https://gitdiagram.com/supercheck-io/supercheck
- Repository: https://github.com/supercheck-io/supercheck

## Overview

Supercheck combines browser/API and k6 test automation, synthetic monitoring, incident communication, and AI-assisted SRE. The principal test workflow is: users configure jobs in the web app; the app schedules work through Redis/BullMQ; location-aware workers run isolated workloads; results and artifacts are surfaced for review. Other major branches include monitor checks and alerts, public status pages, and evidence-based SRE investigations. The README documents deployment and storage relationships; sampled source confirms selected SRE client behavior and requirement coverage updates, but not the full API or worker wiring.

Main entry points: [`app/src/app/api`](https://github.com/supercheck-io/supercheck/tree/main/app/src/app/api) (Application API), [`app/src/app/api/sre/investigate/route.ts`](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/sre/investigate/route.ts) (SRE investigation), [`worker/src`](https://github.com/supercheck-io/supercheck/tree/main/worker/src) (Location workers), [`app/src/app/api/monitors/route.ts`](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/monitors/route.ts) (Synthetic monitors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web application"]
  node_web["Web interface<br/>[page.tsx]"]
  node_api["Application API"]
  node_governance["Access and governance<br/>[route.ts]"]
end

subgraph group_execution["Test execution"]
  node_testjobs["Test jobs<br/>[route.ts]"]
  node_worker["Location workers"]
  node_sandbox["Isolated execution"]
  node_requirements["Coverage snapshots"]
  node_artifacts["Run artifacts<br/>[route.ts]"]
end

subgraph group_monitoring["Monitoring and status"]
  node_monitors["Synthetic monitors<br/>[route.ts]"]
  node_notifications["Alerts and notifications"]
  node_status["Public status pages<br/>[route.ts]"]
end

subgraph group_sre["AI SRE"]
  node_sre["SRE investigation<br/>[route.ts]"]
  node_evidence["Evidence graph"]
  node_connectors["Read-only connectors<br/>[policy-engine.ts]"]
  node_incidents["SRE incidents<br/>[route.ts]"]
end

subgraph group_platform["Platform state"]
  node_queue["Work queue"]
  node_database[("PostgreSQL")]
  node_artstore[("S3 artifact storage")]
end

node_users(("Users / CI"))
node_external["Configured integrations"]
node_kubernetes["Kubernetes / gVisor"]

node_users -->|"use"| node_web
node_web -->|"request"| node_api
node_api -->|"authorize"| node_governance
node_api -->|"read / write"| node_database
node_api -->|"manage jobs"| node_testjobs
node_testjobs -->|"schedule"| node_queue
node_queue -->|"dispatch"| node_worker
node_worker -->|"launch workloads"| node_kubernetes
node_worker -->|"produce results"| node_artifacts
node_artifacts -->|"store"| node_artstore
node_worker -->|"update coverage"| node_requirements
node_requirements -->|"write snapshots"| node_database
node_api -->|"manage checks"| node_monitors
node_monitors -->|"schedule checks"| node_queue
node_monitors -->|"trigger alerts"| node_notifications
node_notifications -.->|"notify"| node_external
node_api -->|"manage pages"| node_status
node_status -.->|"publish updates"| node_external
node_api -->|"investigate"| node_sre
node_sre -->|"assemble evidence"| node_evidence
node_sre -->|"manage incidents"| node_incidents
node_sre -->|"query under policy"| node_connectors
node_connectors -.->|"read evidence"| node_external
node_sre -->|"read platform data"| node_database

click node_web "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/(main)/page.tsx"
click node_api "https://github.com/supercheck-io/supercheck/tree/main/app/src/app/api"
click node_governance "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/organizations/route.ts"
click node_testjobs "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/jobs/route.ts"
click node_worker "https://github.com/supercheck-io/supercheck/tree/main/worker/src"
click node_requirements "https://github.com/supercheck-io/supercheck/blob/main/worker/src/execution/services/requirement-coverage.service.ts"
click node_artifacts "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/test-results/%5B...path%5D/route.ts"
click node_monitors "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/monitors/route.ts"
click node_notifications "https://github.com/supercheck-io/supercheck/blob/main/app/src/actions/send-incident-notifications.ts"
click node_status "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/status-pages/route.ts"
click node_sre "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/sre/investigate/route.ts"
click node_evidence "https://github.com/supercheck-io/supercheck/blob/main/app/src/actions/sre-evidence-graph.ts"
click node_connectors "https://github.com/supercheck-io/supercheck/blob/main/app/src/lib/sre/connectors/policy-engine.ts"
click node_incidents "https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/sre/incidents/route.ts"

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_web,node_api,node_governance,node_users toneBlue
class node_testjobs,node_worker,node_sandbox,node_requirements,node_artifacts toneAmber
class node_monitors,node_notifications,node_status toneMint
class node_sre,node_evidence,node_connectors,node_incidents toneRose
class node_queue,node_database,node_artstore,node_external,node_kubernetes toneIndigo
```

## Components

### Web application

- [Web interface](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/(main)/page.tsx): `app/src/app/(main)/page.tsx`
- [Application API](https://github.com/supercheck-io/supercheck/tree/main/app/src/app/api): `app/src/app/api`
- [Access and governance](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/organizations/route.ts): `app/src/app/api/organizations/route.ts`

### Test execution

- [Test jobs](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/jobs/route.ts): `app/src/app/api/jobs/route.ts`
- [Location workers](https://github.com/supercheck-io/supercheck/tree/main/worker/src): `worker/src`
- **Isolated execution**
- [Coverage snapshots](https://github.com/supercheck-io/supercheck/blob/main/worker/src/execution/services/requirement-coverage.service.ts): `worker/src/execution/services/requirement-coverage.service.ts`
- [Run artifacts](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/test-results/%5B...path%5D/route.ts): `app/src/app/api/test-results/[...path]/route.ts`

### Monitoring and status

- [Synthetic monitors](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/monitors/route.ts): `app/src/app/api/monitors/route.ts`
- [Alerts and notifications](https://github.com/supercheck-io/supercheck/blob/main/app/src/actions/send-incident-notifications.ts): `app/src/actions/send-incident-notifications.ts`
- [Public status pages](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/status-pages/route.ts): `app/src/app/api/status-pages/route.ts`

### AI SRE

- [SRE investigation](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/sre/investigate/route.ts): `app/src/app/api/sre/investigate/route.ts`
- [Evidence graph](https://github.com/supercheck-io/supercheck/blob/main/app/src/actions/sre-evidence-graph.ts): `app/src/actions/sre-evidence-graph.ts`
- [Read-only connectors](https://github.com/supercheck-io/supercheck/blob/main/app/src/lib/sre/connectors/policy-engine.ts): `app/src/lib/sre/connectors/policy-engine.ts`
- [SRE incidents](https://github.com/supercheck-io/supercheck/blob/main/app/src/app/api/sre/incidents/route.ts): `app/src/app/api/sre/incidents/route.ts`

### Platform state

- **Work queue**
- **PostgreSQL**
- **S3 artifact storage**

### Other components

- **Users / CI**
- **Configured integrations**
- **Kubernetes / gVisor**

## Connections

- Users / CI → Web interface: use
- Web interface → Application API: request
- Application API → Access and governance: authorize
- Application API → PostgreSQL: read / write
- Application API → Test jobs: manage jobs
- Test jobs → Work queue: schedule
- Work queue → Location workers: dispatch
- Location workers → Kubernetes / gVisor: launch workloads
- Location workers → Run artifacts: produce results
- Run artifacts → S3 artifact storage: store
- Location workers → Coverage snapshots: update coverage
- Coverage snapshots → PostgreSQL: write snapshots
- Application API → Synthetic monitors: manage checks
- Synthetic monitors → Work queue: schedule checks
- Synthetic monitors → Alerts and notifications: trigger alerts
- Alerts and notifications → Configured integrations: notify
- Application API → Public status pages: manage pages
- Public status pages → Configured integrations: publish updates
- Application API → SRE investigation: investigate
- SRE investigation → Evidence graph: assemble evidence
- SRE investigation → SRE incidents: manage incidents
- SRE investigation → Read-only connectors: query under policy
- Read-only connectors → Configured integrations: read evidence
- SRE investigation → PostgreSQL: read platform data