# xellanix/qr-validator architecture

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

- Interactive diagram: https://gitdiagram.com/xellanix/qr-validator
- Repository: https://github.com/xellanix/qr-validator

## Overview

This repository appears to be PreMark, a browser-based project and presence-management app with a Go backend and realtime Socket.IO services; the README describes a different QR-scanner product, so its workflow details are not treated as evidence for these modules. The visible frontend entry point leads to home and console experiences, while the backend serves authentication, dataset, download, and report endpoints and registers realtime domain handlers. Several frontend capabilities are clear from the tree but their wiring was not sampled, so those relationships are omitted.

Main entry points: [`server/sockets/index.go`](https://github.com/xellanix/qr-validator/blob/main/server/sockets/index.go) (Socket event registry), [`server/main.go`](https://github.com/xellanix/qr-validator/blob/main/server/main.go) (HTTP server), [`frontend/router.tsx`](https://github.com/xellanix/qr-validator/blob/main/frontend/router.tsx) (App routes), [`server/handlers/auth.go`](https://github.com/xellanix/qr-validator/blob/main/server/handlers/auth.go) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_main["Frontend entry<br/>[main.tsx]"]
  node_router["App routes<br/>[router.tsx]"]
  node_home["Home workflow<br/>[index.tsx]"]
  node_console["Console<br/>[index.tsx]"]
  node_authui["Authentication UI<br/>[auth.tsx]"]
  node_authclient["Auth client<br/>[auth.ts]"]
  node_projects["Project management<br/>[index.tsx]"]
  node_scanner["Scanner and generators<br/>[index.tsx]"]
  node_historyui["History view<br/>[history.tsx]"]
  node_reports["Report experience<br/>[report.tsx]"]
end

subgraph group_api["HTTP backend"]
  node_server["HTTP server<br/>[main.go]"]
  node_authhandler["Auth endpoints<br/>[auth.go]"]
  node_authlib["JWT security<br/>[auth.go]"]
  node_datasetapi["Dataset endpoints<br/>[csv.go]"]
  node_downloadapi["Downloads<br/>[download.go]"]
  node_reportapi["Report generation<br/>[generate.go]"]
end

subgraph group_realtime["Realtime services"]
  node_socketserver["Socket event registry<br/>[index.go]"]
  node_socketauth["Socket authentication<br/>[auth.go]"]
  node_presence["Presence events<br/>[presence.go]"]
  node_projectevents["Project events<br/>[project.go]"]
  node_datasetevents["Dataset events<br/>[dataset.go]"]
  node_historyevents["History events<br/>[history.go]"]
end

subgraph group_data["Persistence"]
  node_projectdb[("Project storage<br/>[project.go]")]
  node_datasetdb[("Dataset storage<br/>[dataset.go]")]
  node_historydb[("Presence history storage")]
  node_userdb[("User storage<br/>[user.go]")]
end

node_user(("User"))

node_main -->|"renders"| node_router
node_router -->|"routes to"| node_home
node_router -->|"routes to"| node_console
node_home -->|"renders"| node_historyui
node_user -->|"provides credentials"| node_authui
node_authui -->|"calls"| node_authclient
node_server -->|"routes requests"| node_authhandler
node_server -->|"routes requests"| node_datasetapi
node_server -->|"routes requests"| node_downloadapi
node_server -->|"routes requests"| node_reportapi
node_server -->|"mounts handler"| node_socketserver
node_authhandler -->|"looks up users"| node_userdb
node_authhandler -->|"signs and verifies"| node_authlib
node_socketserver -->|"registers checks"| node_socketauth
node_socketserver -->|"registers listeners"| node_presence
node_socketserver -->|"registers listeners"| node_projectevents
node_socketserver -->|"registers listeners"| node_datasetevents
node_socketserver -->|"registers listeners"| node_historyevents

click node_main "https://github.com/xellanix/qr-validator/blob/main/frontend/main.tsx"
click node_router "https://github.com/xellanix/qr-validator/blob/main/frontend/router.tsx"
click node_home "https://github.com/xellanix/qr-validator/blob/main/frontend/app/index.tsx"
click node_console "https://github.com/xellanix/qr-validator/blob/main/frontend/components/console/index.tsx"
click node_authui "https://github.com/xellanix/qr-validator/blob/main/frontend/components/auth.tsx"
click node_authclient "https://github.com/xellanix/qr-validator/blob/main/frontend/lib/auth.ts"
click node_projects "https://github.com/xellanix/qr-validator/blob/main/frontend/components/dialogs/projects/index.tsx"
click node_scanner "https://github.com/xellanix/qr-validator/blob/main/frontend/components/generators/index.tsx"
click node_historyui "https://github.com/xellanix/qr-validator/blob/main/frontend/components/history.tsx"
click node_reports "https://github.com/xellanix/qr-validator/blob/main/frontend/components/report.tsx"
click node_server "https://github.com/xellanix/qr-validator/blob/main/server/main.go"
click node_authhandler "https://github.com/xellanix/qr-validator/blob/main/server/handlers/auth.go"
click node_authlib "https://github.com/xellanix/qr-validator/blob/main/server/lib/auth.go"
click node_datasetapi "https://github.com/xellanix/qr-validator/blob/main/server/handlers/csv.go"
click node_downloadapi "https://github.com/xellanix/qr-validator/blob/main/server/handlers/download.go"
click node_reportapi "https://github.com/xellanix/qr-validator/blob/main/server/handlers/generate.go"
click node_socketserver "https://github.com/xellanix/qr-validator/blob/main/server/sockets/index.go"
click node_socketauth "https://github.com/xellanix/qr-validator/blob/main/server/sockets/auth.go"
click node_presence "https://github.com/xellanix/qr-validator/blob/main/server/sockets/presence.go"
click node_projectevents "https://github.com/xellanix/qr-validator/blob/main/server/sockets/project.go"
click node_datasetevents "https://github.com/xellanix/qr-validator/blob/main/server/sockets/dataset.go"
click node_historyevents "https://github.com/xellanix/qr-validator/blob/main/server/sockets/history.go"
click node_projectdb "https://github.com/xellanix/qr-validator/blob/main/server/db/project.go"
click node_datasetdb "https://github.com/xellanix/qr-validator/blob/main/server/db/dataset.go"
click node_historydb "https://github.com/xellanix/qr-validator/blob/main/server/db/presence_history.go"
click node_userdb "https://github.com/xellanix/qr-validator/blob/main/server/db/user.go"

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_main,node_router,node_home,node_console,node_authui,node_authclient,node_projects,node_scanner,node_historyui,node_reports,node_user toneBlue
class node_server,node_authhandler,node_authlib,node_datasetapi,node_downloadapi,node_reportapi toneAmber
class node_socketserver,node_socketauth,node_presence,node_projectevents,node_datasetevents,node_historyevents toneMint
class node_projectdb,node_datasetdb,node_historydb,node_userdb toneRose
```

## Components

### Web application

- [Frontend entry](https://github.com/xellanix/qr-validator/blob/main/frontend/main.tsx): `frontend/main.tsx`
- [App routes](https://github.com/xellanix/qr-validator/blob/main/frontend/router.tsx): `frontend/router.tsx`
- [Home workflow](https://github.com/xellanix/qr-validator/blob/main/frontend/app/index.tsx): `frontend/app/index.tsx`
- [Console](https://github.com/xellanix/qr-validator/blob/main/frontend/components/console/index.tsx): `frontend/components/console/index.tsx`
- [Authentication UI](https://github.com/xellanix/qr-validator/blob/main/frontend/components/auth.tsx): `frontend/components/auth.tsx`
- [Auth client](https://github.com/xellanix/qr-validator/blob/main/frontend/lib/auth.ts): `frontend/lib/auth.ts`
- [Project management](https://github.com/xellanix/qr-validator/blob/main/frontend/components/dialogs/projects/index.tsx): `frontend/components/dialogs/projects/index.tsx`
- [Scanner and generators](https://github.com/xellanix/qr-validator/blob/main/frontend/components/generators/index.tsx): `frontend/components/generators/index.tsx`
- [History view](https://github.com/xellanix/qr-validator/blob/main/frontend/components/history.tsx): `frontend/components/history.tsx`
- [Report experience](https://github.com/xellanix/qr-validator/blob/main/frontend/components/report.tsx): `frontend/components/report.tsx`

### HTTP backend

- [HTTP server](https://github.com/xellanix/qr-validator/blob/main/server/main.go): `server/main.go`
- [Auth endpoints](https://github.com/xellanix/qr-validator/blob/main/server/handlers/auth.go): `server/handlers/auth.go`
- [JWT security](https://github.com/xellanix/qr-validator/blob/main/server/lib/auth.go): `server/lib/auth.go`
- [Dataset endpoints](https://github.com/xellanix/qr-validator/blob/main/server/handlers/csv.go): `server/handlers/csv.go`
- [Downloads](https://github.com/xellanix/qr-validator/blob/main/server/handlers/download.go): `server/handlers/download.go`
- [Report generation](https://github.com/xellanix/qr-validator/blob/main/server/handlers/generate.go): `server/handlers/generate.go`

### Realtime services

- [Socket event registry](https://github.com/xellanix/qr-validator/blob/main/server/sockets/index.go): `server/sockets/index.go`
- [Socket authentication](https://github.com/xellanix/qr-validator/blob/main/server/sockets/auth.go): `server/sockets/auth.go`
- [Presence events](https://github.com/xellanix/qr-validator/blob/main/server/sockets/presence.go): `server/sockets/presence.go`
- [Project events](https://github.com/xellanix/qr-validator/blob/main/server/sockets/project.go): `server/sockets/project.go`
- [Dataset events](https://github.com/xellanix/qr-validator/blob/main/server/sockets/dataset.go): `server/sockets/dataset.go`
- [History events](https://github.com/xellanix/qr-validator/blob/main/server/sockets/history.go): `server/sockets/history.go`

### Persistence

- [Project storage](https://github.com/xellanix/qr-validator/blob/main/server/db/project.go): `server/db/project.go`
- [Dataset storage](https://github.com/xellanix/qr-validator/blob/main/server/db/dataset.go): `server/db/dataset.go`
- [Presence history storage](https://github.com/xellanix/qr-validator/blob/main/server/db/presence_history.go): `server/db/presence_history.go`
- [User storage](https://github.com/xellanix/qr-validator/blob/main/server/db/user.go): `server/db/user.go`

### Other components

- **User**

## Connections

- Frontend entry → App routes: renders (evidence: `frontend/main.tsx`)
- App routes → Home workflow: routes to (evidence: `frontend/router.tsx`)
- App routes → Console: routes to (evidence: `frontend/router.tsx`)
- Home workflow → History view: renders (evidence: `frontend/app/index.tsx`)
- User → Authentication UI: provides credentials (evidence: `frontend/components/auth.tsx`)
- Authentication UI → Auth client: calls (evidence: `frontend/components/auth.tsx`)
- HTTP server → Auth endpoints: routes requests (evidence: `server/main.go`)
- HTTP server → Dataset endpoints: routes requests (evidence: `server/main.go`)
- HTTP server → Downloads: routes requests (evidence: `server/main.go`)
- HTTP server → Report generation: routes requests (evidence: `server/main.go`)
- HTTP server → Socket event registry: mounts handler (evidence: `server/main.go`)
- Auth endpoints → User storage: looks up users (evidence: `server/handlers/auth.go`)
- Auth endpoints → JWT security: signs and verifies (evidence: `server/handlers/auth.go`)
- Socket event registry → Socket authentication: registers checks (evidence: `server/sockets/index.go`)
- Socket event registry → Presence events: registers listeners (evidence: `server/sockets/index.go`)
- Socket event registry → Project events: registers listeners (evidence: `server/sockets/index.go`)
- Socket event registry → Dataset events: registers listeners (evidence: `server/sockets/index.go`)
- Socket event registry → History events: registers listeners (evidence: `server/sockets/index.go`)
