# harlequincs/veritas architecture

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

- Interactive diagram: https://gitdiagram.com/harlequincs/veritas
- Repository: https://github.com/harlequincs/veritas

## Overview

VERITAS is presented as a web vulnerability scanner and security command centre. The visible user workflow is account creation or sign-in, followed by dashboard review of scan sessions and vulnerability summaries, then inspection of findings and a report with remediation-oriented patch content. The tree also exposes target setup, live scans, tickets, notifications, and threat-map surfaces. Evidence is uneven: several product areas are represented only by routes, and the sampled FastAPI backend demonstrates health and database connectivity rather than scan execution.

Main entry points: [`utils/supabase/server.ts`](https://github.com/harlequincs/veritas/blob/main/utils/supabase/server.ts) (Supabase server client), [`app/auth/callback/route.ts`](https://github.com/harlequincs/veritas/blob/main/app/auth/callback/route.ts) (OAuth callback), [`app/(app)/dashboard/page.tsx`](https://github.com/harlequincs/veritas/blob/main/app/(app)/dashboard/page.tsx) (Security dashboard), [`app/register/page.tsx`](https://github.com/harlequincs/veritas/blob/main/app/register/page.tsx) (Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth_ui["Auth screens<br/>[page.tsx]"]
  node_registration["Registration<br/>[page.tsx]"]
  node_auth_actions["Auth actions<br/>[auth.ts]"]
  node_oauth_callback["OAuth callback<br/>[route.ts]"]
  node_email_confirm["Email confirmation<br/>[route.ts]"]
  node_supabase_server["Supabase server client<br/>[server.ts]"]
  node_supabase_admin["Supabase admin client<br/>[admin.ts]"]
  node_welcome_email["Welcome email<br/>[welcome-email.ts]"]
end

subgraph group_security["Scanner workspace"]
  node_dashboard["Security dashboard<br/>[page.tsx]"]
  node_scan_sessions["Scan sessions"]
  node_scan_activity["Scan activity views"]
  node_target_setup["Target setup<br/>[page.tsx]"]
  node_live_scans["Live scans<br/>[page.tsx]"]
  node_threat_map["Threat map API<br/>[route.ts]"]
end

subgraph group_findings["Findings and remediation"]
  node_vulnerability_list["Vulnerability list<br/>[page.tsx]"]
  node_vulnerability_detail["Finding detail<br/>[page.tsx]"]
  node_reports["Reports<br/>[page.tsx]"]
  node_report_view["Report and patch view<br/>[page.tsx]"]
  node_tickets["Remediation tickets<br/>[page.tsx]"]
end

subgraph group_public["Public product site"]
  node_marketing_site["Marketing site<br/>[page.tsx]"]
end

subgraph group_backend["Backend services"]
  node_fastapi["FastAPI endpoints<br/>[main.py]"]
  node_sqlalchemy["SQLAlchemy sessions<br/>[database.py]"]
end

node_visitor(("Visitor"))
node_supabase_auth_db[("Supabase Auth and data")]
node_postgres[("Postgres database")]

node_visitor -->|"creates account"| node_registration
node_registration -->|"submits signup"| node_auth_actions
node_auth_actions -->|"creates client"| node_supabase_server
node_supabase_server -->|"auth and data access"| node_supabase_auth_db
node_visitor -.->|"signs in"| node_auth_ui
node_oauth_callback -->|"exchanges code"| node_supabase_server
node_oauth_callback -->|"admin cleanup"| node_supabase_admin
node_oauth_callback -->|"sends welcome email"| node_welcome_email
node_oauth_callback -->|"checks user row"| node_supabase_auth_db
node_email_confirm -->|"verifies token"| node_supabase_server
node_dashboard -->|"loads user and scans"| node_supabase_server
node_dashboard -->|"renders"| node_scan_sessions
node_dashboard -->|"renders"| node_scan_activity
node_vulnerability_detail -.->|"related report data"| node_reports
node_fastapi -->|"gets database session"| node_sqlalchemy
node_sqlalchemy -.->|"opens SQL connection"| node_postgres

click node_auth_ui "https://github.com/harlequincs/veritas/blob/main/app/auth/page.tsx"
click node_registration "https://github.com/harlequincs/veritas/blob/main/app/register/page.tsx"
click node_auth_actions "https://github.com/harlequincs/veritas/blob/main/app/actions/auth.ts"
click node_oauth_callback "https://github.com/harlequincs/veritas/blob/main/app/auth/callback/route.ts"
click node_email_confirm "https://github.com/harlequincs/veritas/blob/main/app/auth/confirm/route.ts"
click node_supabase_server "https://github.com/harlequincs/veritas/blob/main/utils/supabase/server.ts"
click node_supabase_admin "https://github.com/harlequincs/veritas/blob/main/utils/supabase/admin.ts"
click node_welcome_email "https://github.com/harlequincs/veritas/blob/main/lib/welcome-email.ts"
click node_dashboard "https://github.com/harlequincs/veritas/blob/main/app/(app)/dashboard/page.tsx"
click node_scan_sessions "https://github.com/harlequincs/veritas/blob/main/components/scan-session-table.tsx"
click node_scan_activity "https://github.com/harlequincs/veritas/blob/main/components/live-activity-rail.tsx"
click node_target_setup "https://github.com/harlequincs/veritas/blob/main/app/(app)/targets/new/page.tsx"
click node_live_scans "https://github.com/harlequincs/veritas/blob/main/app/(app)/scans/live/page.tsx"
click node_vulnerability_list "https://github.com/harlequincs/veritas/blob/main/app/(app)/vulnerabilities/page.tsx"
click node_vulnerability_detail "https://github.com/harlequincs/veritas/blob/main/app/(app)/vulnerabilities/%5Bid%5D/page.tsx"
click node_reports "https://github.com/harlequincs/veritas/blob/main/app/(app)/reports/page.tsx"
click node_report_view "https://github.com/harlequincs/veritas/blob/main/app/report/page.tsx"
click node_tickets "https://github.com/harlequincs/veritas/blob/main/app/(app)/tickets/page.tsx"
click node_threat_map "https://github.com/harlequincs/veritas/blob/main/app/api/threat-map/route.ts"
click node_marketing_site "https://github.com/harlequincs/veritas/blob/main/app/(marketing)/page.tsx"
click node_fastapi "https://github.com/harlequincs/veritas/blob/main/backend/main.py"
click node_sqlalchemy "https://github.com/harlequincs/veritas/blob/main/backend/database.py"

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_auth_ui,node_registration,node_auth_actions,node_oauth_callback,node_email_confirm,node_supabase_server,node_supabase_admin,node_welcome_email toneBlue
class node_dashboard,node_scan_sessions,node_scan_activity,node_target_setup,node_live_scans,node_threat_map,node_supabase_auth_db,node_postgres toneAmber
class node_vulnerability_list,node_vulnerability_detail,node_reports,node_report_view,node_tickets toneMint
class node_marketing_site toneRose
class node_fastapi,node_sqlalchemy,node_visitor toneIndigo
```

## Components

### Identity and access

- [Auth screens](https://github.com/harlequincs/veritas/blob/main/app/auth/page.tsx): `app/auth/page.tsx`
- [Registration](https://github.com/harlequincs/veritas/blob/main/app/register/page.tsx): `app/register/page.tsx`
- [Auth actions](https://github.com/harlequincs/veritas/blob/main/app/actions/auth.ts): `app/actions/auth.ts`
- [OAuth callback](https://github.com/harlequincs/veritas/blob/main/app/auth/callback/route.ts): `app/auth/callback/route.ts`
- [Email confirmation](https://github.com/harlequincs/veritas/blob/main/app/auth/confirm/route.ts): `app/auth/confirm/route.ts`
- [Supabase server client](https://github.com/harlequincs/veritas/blob/main/utils/supabase/server.ts): `utils/supabase/server.ts`
- [Supabase admin client](https://github.com/harlequincs/veritas/blob/main/utils/supabase/admin.ts): `utils/supabase/admin.ts`
- [Welcome email](https://github.com/harlequincs/veritas/blob/main/lib/welcome-email.ts): `lib/welcome-email.ts`

### Scanner workspace

- [Security dashboard](https://github.com/harlequincs/veritas/blob/main/app/(app)/dashboard/page.tsx): `app/(app)/dashboard/page.tsx`
- [Scan sessions](https://github.com/harlequincs/veritas/blob/main/components/scan-session-table.tsx): `components/scan-session-table.tsx`
- [Scan activity views](https://github.com/harlequincs/veritas/blob/main/components/live-activity-rail.tsx): `components/live-activity-rail.tsx`
- [Target setup](https://github.com/harlequincs/veritas/blob/main/app/(app)/targets/new/page.tsx): `app/(app)/targets/new/page.tsx`
- [Live scans](https://github.com/harlequincs/veritas/blob/main/app/(app)/scans/live/page.tsx): `app/(app)/scans/live/page.tsx`
- [Threat map API](https://github.com/harlequincs/veritas/blob/main/app/api/threat-map/route.ts): `app/api/threat-map/route.ts`

### Findings and remediation

- [Vulnerability list](https://github.com/harlequincs/veritas/blob/main/app/(app)/vulnerabilities/page.tsx): `app/(app)/vulnerabilities/page.tsx`
- [Finding detail](https://github.com/harlequincs/veritas/blob/main/app/(app)/vulnerabilities/%5Bid%5D/page.tsx): `app/(app)/vulnerabilities/[id]/page.tsx`
- [Reports](https://github.com/harlequincs/veritas/blob/main/app/(app)/reports/page.tsx): `app/(app)/reports/page.tsx`
- [Report and patch view](https://github.com/harlequincs/veritas/blob/main/app/report/page.tsx): `app/report/page.tsx`
- [Remediation tickets](https://github.com/harlequincs/veritas/blob/main/app/(app)/tickets/page.tsx): `app/(app)/tickets/page.tsx`

### Public product site

- [Marketing site](https://github.com/harlequincs/veritas/blob/main/app/(marketing)/page.tsx): `app/(marketing)/page.tsx`

### Backend services

- [FastAPI endpoints](https://github.com/harlequincs/veritas/blob/main/backend/main.py): `backend/main.py`
- [SQLAlchemy sessions](https://github.com/harlequincs/veritas/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Visitor**
- **Supabase Auth and data**
- **Postgres database**

## Connections

- Visitor → Registration: creates account (evidence: `app/register/page.tsx`)
- Registration → Auth actions: submits signup (evidence: `app/register/page.tsx`)
- Auth actions → Supabase server client: creates client (evidence: `app/actions/auth.ts`)
- Supabase server client → Supabase Auth and data: auth and data access
- Visitor → Auth screens: signs in
- OAuth callback → Supabase server client: exchanges code (evidence: `app/auth/callback/route.ts`)
- OAuth callback → Supabase admin client: admin cleanup (evidence: `app/auth/callback/route.ts`)
- OAuth callback → Welcome email: sends welcome email (evidence: `app/auth/callback/route.ts`)
- OAuth callback → Supabase Auth and data: checks user row (evidence: `app/auth/callback/route.ts`)
- Email confirmation → Supabase server client: verifies token (evidence: `app/auth/confirm/route.ts`)
- Security dashboard → Supabase server client: loads user and scans (evidence: `app/(app)/dashboard/page.tsx`)
- Security dashboard → Scan sessions: renders (evidence: `app/(app)/dashboard/page.tsx`)
- Security dashboard → Scan activity views: renders (evidence: `app/(app)/dashboard/page.tsx`)
- Finding detail → Reports: related report data
- FastAPI endpoints → SQLAlchemy sessions: gets database session (evidence: `backend/main.py`)
- SQLAlchemy sessions → Postgres database: opens SQL connection
