# zpleum/qrforge architecture

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

- Interactive diagram: https://gitdiagram.com/zpleum/qrforge
- Repository: https://github.com/zpleum/qrforge

## Overview

QRForge is a dynamic QR-code service: users create and style a QR code that encodes a stable short URL, then can change its destination without reprinting. The main flow runs from Google sign-in through dashboard management and QR rendering to public redirects and scan analytics. Separate branches handle abuse reports, admin moderation, data export, and scheduled retention/Web Risk checks. The graph uses documented capabilities for unsampled areas; some internal calls and storage details are omitted where excerpts do not establish them.

Main entry points: [`src/db/schema.ts`](https://github.com/zpleum/qrforge/blob/main/src/db/schema.ts) (QR and account data), [`src/lib/actions.ts`](https://github.com/zpleum/qrforge/blob/main/src/lib/actions.ts) (QR management actions), [`src/lib/queries.ts`](https://github.com/zpleum/qrforge/blob/main/src/lib/queries.ts) (Analytics queries), [`src/auth.ts`](https://github.com/zpleum/qrforge/blob/main/src/auth.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_account["Accounts and QR management"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_dashboard["QR dashboard<br/>[page.tsx]"]
  node_qr_actions["QR management actions<br/>[actions.ts]"]
  node_qr_store[("QR and account data<br/>[schema.ts]")]
end

subgraph group_qr["QR design and delivery"]
  node_qr_designer["QR designer<br/>[QrDesigner.tsx]"]
  node_design["Design options<br/>[design.ts]"]
  node_qr_renderer["QR renderer<br/>[useQrStyling.ts]"]
  node_qr_views["QR display and export<br/>[QrViews.tsx]"]
  node_redirect["Short-link redirect<br/>[route.ts]"]
end

subgraph group_analytics["Scan analytics"]
  node_scan_tracking["Scan tracking<br/>[track.ts]"]
  node_analytics_page["QR analytics<br/>[page.tsx]"]
  node_queries["Analytics queries<br/>[queries.ts]"]
  node_csv_export["Scan CSV export<br/>[route.ts]"]
end

subgraph group_safety["Safety and operations"]
  node_admin_actions["Admin actions<br/>[admin-actions.ts]"]
  node_reports["Abuse reports<br/>[page.tsx]"]
  node_report_actions["Report handling<br/>[report-actions.ts]"]
  node_admin["Admin console<br/>[page.tsx]"]
  node_maintenance["Scheduled maintenance<br/>[route.ts]"]
  node_web_risk["Web Risk checks<br/>[webrisk.ts]"]
end

node_visitor(("QR visitor"))
node_owner(("QR owner"))
node_staff(("Administrator"))
node_google{{"Google sign-in"}}

node_owner -->|"signs in"| node_auth
node_auth -->|"authenticates with"| node_google
node_auth -->|"reads and writes users"| node_qr_store
node_owner -->|"manages QR codes"| node_dashboard
node_dashboard -->|"lists QR codes"| node_queries
node_dashboard -->|"manages QR codes"| node_qr_actions
node_qr_actions -->|"reads and writes"| node_qr_store
node_qr_actions -->|"checks destinations"| node_web_risk
node_qr_designer -.->|"saves QR design"| node_qr_actions
node_qr_designer -.->|"uses design options"| node_design
node_qr_views -->|"builds QR options"| node_design
node_qr_renderer -->|"converts design"| node_design
node_visitor -->|"opens short link"| node_redirect
node_redirect -->|"records scan"| node_scan_tracking
node_redirect -->|"redirects to destination"| node_visitor
node_owner -->|"views scan analytics"| node_analytics_page
node_analytics_page -->|"requests statistics"| node_queries
node_queries -->|"queries scan data"| node_qr_store
node_owner -->|"exports scan data"| node_csv_export
node_csv_export -->|"checks QR ownership"| node_queries
node_csv_export -->|"reads scans"| node_qr_store
node_visitor -->|"reports a link"| node_reports
node_reports -.->|"submits report"| node_report_actions
node_staff -->|"reviews reports"| node_admin
node_admin -->|"moderates reports"| node_admin_actions
node_admin_actions -->|"updates QR and report status"| node_qr_store
node_maintenance -->|"cleans and checks records"| node_qr_store
node_maintenance -->|"checks active destinations"| node_web_risk

click node_auth "https://github.com/zpleum/qrforge/blob/main/src/auth.ts"
click node_dashboard "https://github.com/zpleum/qrforge/blob/main/src/app/dashboard/page.tsx"
click node_qr_actions "https://github.com/zpleum/qrforge/blob/main/src/lib/actions.ts"
click node_admin_actions "https://github.com/zpleum/qrforge/blob/main/src/lib/admin-actions.ts"
click node_qr_store "https://github.com/zpleum/qrforge/blob/main/src/db/schema.ts"
click node_qr_designer "https://github.com/zpleum/qrforge/blob/main/src/components/QrDesigner.tsx"
click node_design "https://github.com/zpleum/qrforge/blob/main/src/lib/design.ts"
click node_qr_renderer "https://github.com/zpleum/qrforge/blob/main/src/components/useQrStyling.ts"
click node_qr_views "https://github.com/zpleum/qrforge/blob/main/src/components/QrViews.tsx"
click node_redirect "https://github.com/zpleum/qrforge/blob/main/src/app/r/%5Bslug%5D/route.ts"
click node_scan_tracking "https://github.com/zpleum/qrforge/blob/main/src/lib/track.ts"
click node_analytics_page "https://github.com/zpleum/qrforge/blob/main/src/app/dashboard/%5Bid%5D/page.tsx"
click node_queries "https://github.com/zpleum/qrforge/blob/main/src/lib/queries.ts"
click node_csv_export "https://github.com/zpleum/qrforge/blob/main/src/app/dashboard/%5Bid%5D/export/route.ts"
click node_reports "https://github.com/zpleum/qrforge/blob/main/src/app/report/page.tsx"
click node_report_actions "https://github.com/zpleum/qrforge/blob/main/src/lib/report-actions.ts"
click node_admin "https://github.com/zpleum/qrforge/blob/main/src/app/admin/reports/page.tsx"
click node_maintenance "https://github.com/zpleum/qrforge/blob/main/src/app/api/cron/maintenance/route.ts"
click node_web_risk "https://github.com/zpleum/qrforge/blob/main/src/lib/webrisk.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_auth,node_dashboard,node_qr_actions,node_qr_store toneBlue
class node_qr_designer,node_design,node_qr_renderer,node_qr_views,node_redirect toneAmber
class node_scan_tracking,node_analytics_page,node_queries,node_csv_export toneMint
class node_admin_actions,node_reports,node_report_actions,node_admin,node_maintenance,node_web_risk toneRose
class node_visitor,node_owner,node_staff,node_google toneIndigo
```

## Components

### Accounts and QR management

- [Authentication](https://github.com/zpleum/qrforge/blob/main/src/auth.ts): `src/auth.ts`
- [QR dashboard](https://github.com/zpleum/qrforge/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [QR management actions](https://github.com/zpleum/qrforge/blob/main/src/lib/actions.ts): `src/lib/actions.ts`
- [QR and account data](https://github.com/zpleum/qrforge/blob/main/src/db/schema.ts): `src/db/schema.ts`

### QR design and delivery

- [QR designer](https://github.com/zpleum/qrforge/blob/main/src/components/QrDesigner.tsx): `src/components/QrDesigner.tsx`
- [Design options](https://github.com/zpleum/qrforge/blob/main/src/lib/design.ts): `src/lib/design.ts`
- [QR renderer](https://github.com/zpleum/qrforge/blob/main/src/components/useQrStyling.ts): `src/components/useQrStyling.ts`
- [QR display and export](https://github.com/zpleum/qrforge/blob/main/src/components/QrViews.tsx): `src/components/QrViews.tsx`
- [Short-link redirect](https://github.com/zpleum/qrforge/blob/main/src/app/r/%5Bslug%5D/route.ts): `src/app/r/[slug]/route.ts`

### Scan analytics

- [Scan tracking](https://github.com/zpleum/qrforge/blob/main/src/lib/track.ts): `src/lib/track.ts`
- [QR analytics](https://github.com/zpleum/qrforge/blob/main/src/app/dashboard/%5Bid%5D/page.tsx): `src/app/dashboard/[id]/page.tsx`
- [Analytics queries](https://github.com/zpleum/qrforge/blob/main/src/lib/queries.ts): `src/lib/queries.ts`
- [Scan CSV export](https://github.com/zpleum/qrforge/blob/main/src/app/dashboard/%5Bid%5D/export/route.ts): `src/app/dashboard/[id]/export/route.ts`

### Safety and operations

- [Admin actions](https://github.com/zpleum/qrforge/blob/main/src/lib/admin-actions.ts): `src/lib/admin-actions.ts`
- [Abuse reports](https://github.com/zpleum/qrforge/blob/main/src/app/report/page.tsx): `src/app/report/page.tsx`
- [Report handling](https://github.com/zpleum/qrforge/blob/main/src/lib/report-actions.ts): `src/lib/report-actions.ts`
- [Admin console](https://github.com/zpleum/qrforge/blob/main/src/app/admin/reports/page.tsx): `src/app/admin/reports/page.tsx`
- [Scheduled maintenance](https://github.com/zpleum/qrforge/blob/main/src/app/api/cron/maintenance/route.ts): `src/app/api/cron/maintenance/route.ts`
- [Web Risk checks](https://github.com/zpleum/qrforge/blob/main/src/lib/webrisk.ts): `src/lib/webrisk.ts`

### Other components

- **QR visitor**
- **QR owner**
- **Administrator**
- **Google sign-in**

## Connections

- QR owner → Authentication: signs in (evidence: `README.md`)
- Authentication → Google sign-in: authenticates with (evidence: `README.md`)
- Authentication → QR and account data: reads and writes users (evidence: `src/auth.ts`)
- QR owner → QR dashboard: manages QR codes (evidence: `README.md`)
- QR dashboard → Analytics queries: lists QR codes (evidence: `src/app/dashboard/page.tsx`)
- QR dashboard → QR management actions: manages QR codes (evidence: `README.md`)
- QR management actions → QR and account data: reads and writes (evidence: `src/lib/actions.ts`)
- QR management actions → Web Risk checks: checks destinations (evidence: `src/lib/actions.ts`)
- QR designer → QR management actions: saves QR design
- QR designer → Design options: uses design options
- QR display and export → Design options: builds QR options (evidence: `src/components/QrViews.tsx`)
- QR renderer → Design options: converts design (evidence: `src/components/useQrStyling.ts`)
- QR visitor → Short-link redirect: opens short link (evidence: `README.md`)
- Short-link redirect → Scan tracking: records scan (evidence: `src/app/r/[slug]/route.ts`)
- Short-link redirect → QR visitor: redirects to destination (evidence: `README.md`)
- QR owner → QR analytics: views scan analytics (evidence: `README.md`)
- QR analytics → Analytics queries: requests statistics (evidence: `src/app/dashboard/[id]/page.tsx`)
- Analytics queries → QR and account data: queries scan data (evidence: `src/lib/queries.ts`)
- QR owner → Scan CSV export: exports scan data (evidence: `src/app/dashboard/[id]/export/route.ts`)
- Scan CSV export → Analytics queries: checks QR ownership (evidence: `src/app/dashboard/[id]/export/route.ts`)
- Scan CSV export → QR and account data: reads scans (evidence: `src/app/dashboard/[id]/export/route.ts`)
- QR visitor → Abuse reports: reports a link (evidence: `README.md`)
- Abuse reports → Report handling: submits report
- Administrator → Admin console: reviews reports (evidence: `README.md`)
- Admin console → Admin actions: moderates reports (evidence: `src/app/admin/reports/page.tsx`)
- Admin actions → QR and account data: updates QR and report status (evidence: `src/lib/admin-actions.ts`)
- Scheduled maintenance → QR and account data: cleans and checks records (evidence: `src/app/api/cron/maintenance/route.ts`)
- Scheduled maintenance → Web Risk checks: checks active destinations (evidence: `src/app/api/cron/maintenance/route.ts`)
