# badbadtrip/qrauth architecture

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

- Interactive diagram: https://gitdiagram.com/badbadtrip/qrauth
- Repository: https://github.com/badbadtrip/qrauth

## Overview

QRAuth is a Lampac plugin that provides a configurable deny/login page and Telegram-based account access and QR sign-in. A visitor requests a short-lived QR session; Telegram users with access can confirm it, while new users can request access for admin approval. Approval writes a token to the shared users file, and the browser uses that token to log in through Lampac. Admins also manage users through the bot. The graph follows README-described capabilities where source excerpts were unavailable; the Lampac core’s polling and login endpoints are external.

Main entry points: [`controllers/qrauthcontroller.cs`](https://github.com/badbadtrip/qrauth/blob/main/controllers/qrauthcontroller.cs) (QR HTTP endpoints), [`services/botsession.cs`](https://github.com/badbadtrip/qrauth/blob/main/services/botsession.cs) (Bot workflows), [`DenyPageGenerator.cs`](https://github.com/badbadtrip/qrauth/blob/main/DenyPageGenerator.cs) (Deny page generator), [`modInit.cs`](https://github.com/badbadtrip/qrauth/blob/main/modInit.cs) (Module lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["Login experience"]
  node_module["Module lifecycle<br/>[modInit.cs]"]
  node_denygen["Deny page generator"]
  node_pageconf["Page settings<br/>[denyPageConf.cs]"]
end

subgraph group_qr["QR authentication"]
  node_controller["QR HTTP endpoints"]
  node_sessions["Pairing sessions<br/>[qrauthsessions.cs]"]
end

subgraph group_bot["Telegram access"]
  node_hosted["Bot polling host"]
  node_botsession["Bot workflows<br/>[botsession.cs]"]
  node_botconf["Bot settings<br/>[telegramBotConf.cs]"]
end

subgraph group_state["Shared state"]
  node_repo["User repository<br/>[usersrepository.cs]"]
  node_users[("users.json")]
  node_user_model["Account record<br/>[lampacUser.cs]"]
  node_filelog[("Module file log<br/>[filelog.cs]")]
end

node_visitor(("Visitor"))
node_admin(("Access admin"))
node_telegram{{"Telegram"}}
node_lampac{{"Lampac core"}}

node_module -->|"generates page"| node_denygen
node_module -->|"starts service"| node_hosted
node_module -->|"loads settings"| node_pageconf
node_module -->|"loads settings"| node_botconf
node_visitor -->|"opens login page"| node_denygen
node_denygen -->|"requests session"| node_controller
node_controller -->|"creates session"| node_sessions
node_denygen -->|"polls status"| node_controller
node_controller -->|"consumes confirmation"| node_sessions
node_denygen -->|"logs in with token"| node_lampac
node_hosted -->|"dispatches updates"| node_botsession
node_hosted -->|"polls updates"| node_telegram
node_botsession -->|"sends bot messages"| node_telegram
node_visitor -->|"starts bot"| node_telegram
node_admin -->|"manages access"| node_telegram
node_botsession -->|"looks up and changes users"| node_repo
node_botsession -->|"confirms QR login"| node_sessions
node_controller -->|"looks up login token"| node_repo
node_controller -->|"notifies admins"| node_telegram
node_repo -->|"reads and writes"| node_users
node_repo -->|"serializes records"| node_user_model
node_lampac -.->|"polls user records"| node_users
node_controller -->|"logs failures"| node_filelog
node_hosted -->|"logs bot events"| node_filelog
node_botsession -->|"logs workflow"| node_filelog

click node_module "https://github.com/badbadtrip/qrauth/blob/main/modInit.cs"
click node_denygen "https://github.com/badbadtrip/qrauth/blob/main/DenyPageGenerator.cs"
click node_controller "https://github.com/badbadtrip/qrauth/blob/main/controllers/qrauthcontroller.cs"
click node_sessions "https://github.com/badbadtrip/qrauth/blob/main/services/qrauthsessions.cs"
click node_hosted "https://github.com/badbadtrip/qrauth/blob/main/services/telegrambothostedservice.cs"
click node_botsession "https://github.com/badbadtrip/qrauth/blob/main/services/botsession.cs"
click node_repo "https://github.com/badbadtrip/qrauth/blob/main/services/usersrepository.cs"
click node_user_model "https://github.com/badbadtrip/qrauth/blob/main/models/lampacUser.cs"
click node_botconf "https://github.com/badbadtrip/qrauth/blob/main/models/telegramBotConf.cs"
click node_pageconf "https://github.com/badbadtrip/qrauth/blob/main/models/denyPageConf.cs"
click node_filelog "https://github.com/badbadtrip/qrauth/blob/main/services/filelog.cs"

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_module,node_denygen,node_pageconf toneBlue
class node_controller,node_sessions toneAmber
class node_hosted,node_botsession,node_botconf toneMint
class node_repo,node_users,node_user_model,node_filelog toneRose
class node_visitor,node_admin,node_telegram,node_lampac toneIndigo
```

## Components

### Login experience

- [Module lifecycle](https://github.com/badbadtrip/qrauth/blob/main/modInit.cs): `modInit.cs`
- [Deny page generator](https://github.com/badbadtrip/qrauth/blob/main/DenyPageGenerator.cs): `DenyPageGenerator.cs`
- [Page settings](https://github.com/badbadtrip/qrauth/blob/main/models/denyPageConf.cs): `models/denyPageConf.cs`

### QR authentication

- [QR HTTP endpoints](https://github.com/badbadtrip/qrauth/blob/main/controllers/qrauthcontroller.cs): `controllers/qrauthcontroller.cs`
- [Pairing sessions](https://github.com/badbadtrip/qrauth/blob/main/services/qrauthsessions.cs): `services/qrauthsessions.cs`

### Telegram access

- [Bot polling host](https://github.com/badbadtrip/qrauth/blob/main/services/telegrambothostedservice.cs): `services/telegrambothostedservice.cs`
- [Bot workflows](https://github.com/badbadtrip/qrauth/blob/main/services/botsession.cs): `services/botsession.cs`
- [Bot settings](https://github.com/badbadtrip/qrauth/blob/main/models/telegramBotConf.cs): `models/telegramBotConf.cs`

### Shared state

- [User repository](https://github.com/badbadtrip/qrauth/blob/main/services/usersrepository.cs): `services/usersrepository.cs`
- **users.json**
- [Account record](https://github.com/badbadtrip/qrauth/blob/main/models/lampacUser.cs): `models/lampacUser.cs`
- [Module file log](https://github.com/badbadtrip/qrauth/blob/main/services/filelog.cs): `services/filelog.cs`

### Other components

- **Visitor**
- **Access admin**
- **Telegram**
- **Lampac core**

## Connections

- Module lifecycle → Deny page generator: generates page
- Module lifecycle → Bot polling host: starts service
- Module lifecycle → Page settings: loads settings
- Module lifecycle → Bot settings: loads settings
- Visitor → Deny page generator: opens login page
- Deny page generator → QR HTTP endpoints: requests session
- QR HTTP endpoints → Pairing sessions: creates session
- Deny page generator → QR HTTP endpoints: polls status
- QR HTTP endpoints → Pairing sessions: consumes confirmation
- Deny page generator → Lampac core: logs in with token
- Bot polling host → Bot workflows: dispatches updates
- Bot polling host → Telegram: polls updates
- Bot workflows → Telegram: sends bot messages
- Visitor → Telegram: starts bot
- Access admin → Telegram: manages access
- Bot workflows → User repository: looks up and changes users
- Bot workflows → Pairing sessions: confirms QR login
- QR HTTP endpoints → User repository: looks up login token
- QR HTTP endpoints → Telegram: notifies admins
- User repository → users.json: reads and writes
- User repository → Account record: serializes records
- Lampac core → users.json: polls user records
- QR HTTP endpoints → Module file log: logs failures
- Bot polling host → Module file log: logs bot events
- Bot workflows → Module file log: logs workflow