# domiz918/totp_decoder architecture

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

- Interactive diagram: https://gitdiagram.com/domiz918/totp_decoder
- Repository: https://github.com/domiz918/totp_decoder

## Overview

This is a browser-only TOTP QR decoder. Users drop or paste an image, OTP Auth link, migration export, or raw Base32 secret; decoding produces one or more accounts, live OTP codes, re-encodable URLs/QRs, and copyable values. The graph preserves the documented input, migration, code-generation, display, clipboard, localization, and visual-background capabilities. Sampled source supports the main call paths; optional browser/runtime integrations are shown only where documented.

Main entry points: [`web/src/App.tsx`](https://github.com/domiz918/totp_decoder/blob/main/web/src/App.tsx) (App orchestration), [`web/src/core/QRDecoder.ts`](https://github.com/domiz918/totp_decoder/blob/main/web/src/core/QRDecoder.ts) (QR decoder), [`web/src/parsers/MigrationParser.ts`](https://github.com/domiz918/totp_decoder/blob/main/web/src/parsers/MigrationParser.ts) (Migration parser), [`web/src/hooks/useClipboard.ts`](https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useClipboard.ts) (Clipboard hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input handling"]
  node_uploader["File uploader<br/>[FileUploader.tsx]"]
  node_clipboard_hook["Clipboard hook<br/>[useClipboard.ts]"]
end

subgraph group_decode["Decode and parse"]
  node_decoder_hook["Decode state<br/>[useQRDecoder.ts]"]
  node_decoder["QR decoder<br/>[QRDecoder.ts]"]
  node_image_service["Image loading<br/>[ImageService.ts]"]
  node_qr_service["QR recognition<br/>[QRService.ts]"]
  node_standard_parser["Standard parser<br/>[StandardParser.ts]"]
  node_migration_parser["Migration parser<br/>[MigrationParser.ts]"]
  node_migration_payload["Migration payload<br/>[otpMigration.ts]"]
end

subgraph group_codes["OTP generation"]
  node_totp_service["TOTP and URL service<br/>[TOTPService.ts]"]
  node_timer_hook["Live code timer<br/>[useTimer.ts]"]
end

subgraph group_interface["Results interface"]
  node_app["App orchestration<br/>[App.tsx]"]
  node_results["Results list<br/>[ResultsList.tsx]"]
  node_account_card["Account and QR card<br/>[AccountCard.tsx]"]
  node_status["Decode status<br/>[StatusMessage.tsx]"]
  node_dotwave["Animated background<br/>[DotWave.tsx]"]
end

subgraph group_shared["Browser utilities"]
  node_clipboard_service["Clipboard service"]
  node_base32["Base32 conversion<br/>[base32.ts]"]
  node_i18n_hook["Localization hook<br/>[useI18n.ts]"]
  node_i18n_setup["Localization setup<br/>[index.ts]"]
end

node_user(("User"))
node_analytics["Vercel Analytics"]
node_network["Network services"]

node_user -->|"drops files"| node_uploader
node_user -->|"pastes input"| node_clipboard_hook
node_uploader -->|"uploads file"| node_app
node_clipboard_hook -->|"uses"| node_clipboard_service
node_clipboard_hook -->|"submits text"| node_app
node_app -->|"requests decode"| node_decoder_hook
node_decoder_hook -->|"invokes"| node_decoder
node_decoder -->|"loads image"| node_image_service
node_decoder -->|"decodes QR"| node_qr_service
node_decoder -->|"parses standard"| node_standard_parser
node_decoder -->|"parses migration"| node_migration_parser
node_decoder -->|"creates raw-secret URL"| node_totp_service
node_migration_parser -->|"decodes payload"| node_migration_payload
node_migration_parser -->|"converts secret"| node_base32
node_standard_parser -->|"generates code"| node_totp_service
node_migration_parser -->|"generates code and URL"| node_totp_service
node_app -->|"starts timers"| node_timer_hook
node_timer_hook -->|"refreshes codes"| node_totp_service
node_app -->|"renders results"| node_results
node_app -->|"renders status"| node_status
node_results -->|"renders accounts"| node_account_card
node_account_card -.->|"copies values"| node_clipboard_hook
node_app -->|"mounts background"| node_dotwave
node_i18n_hook -.->|"uses translations"| node_i18n_setup
node_app -->|"renders analytics"| node_analytics
node_analytics -.->|"may send telemetry"| node_network

click node_app "https://github.com/domiz918/totp_decoder/blob/main/web/src/App.tsx"
click node_uploader "https://github.com/domiz918/totp_decoder/blob/main/web/src/components/FileUploader.tsx"
click node_clipboard_hook "https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useClipboard.ts"
click node_clipboard_service "https://github.com/domiz918/totp_decoder/blob/main/web/src/services/ClipboardService.ts"
click node_decoder_hook "https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useQRDecoder.ts"
click node_decoder "https://github.com/domiz918/totp_decoder/blob/main/web/src/core/QRDecoder.ts"
click node_image_service "https://github.com/domiz918/totp_decoder/blob/main/web/src/services/ImageService.ts"
click node_qr_service "https://github.com/domiz918/totp_decoder/blob/main/web/src/services/QRService.ts"
click node_standard_parser "https://github.com/domiz918/totp_decoder/blob/main/web/src/parsers/StandardParser.ts"
click node_migration_parser "https://github.com/domiz918/totp_decoder/blob/main/web/src/parsers/MigrationParser.ts"
click node_migration_payload "https://github.com/domiz918/totp_decoder/blob/main/web/src/otpMigration.ts"
click node_base32 "https://github.com/domiz918/totp_decoder/blob/main/web/src/utils/base32.ts"
click node_totp_service "https://github.com/domiz918/totp_decoder/blob/main/web/src/services/TOTPService.ts"
click node_timer_hook "https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useTimer.ts"
click node_results "https://github.com/domiz918/totp_decoder/blob/main/web/src/components/ResultsList.tsx"
click node_account_card "https://github.com/domiz918/totp_decoder/blob/main/web/src/components/AccountCard.tsx"
click node_status "https://github.com/domiz918/totp_decoder/blob/main/web/src/components/StatusMessage.tsx"
click node_dotwave "https://github.com/domiz918/totp_decoder/blob/main/web/src/components/DotWave.tsx"
click node_i18n_hook "https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useI18n.ts"
click node_i18n_setup "https://github.com/domiz918/totp_decoder/blob/main/web/src/i18n/index.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_uploader,node_clipboard_hook,node_user toneBlue
class node_decoder_hook,node_decoder,node_image_service,node_qr_service,node_standard_parser,node_migration_parser,node_migration_payload toneAmber
class node_totp_service,node_timer_hook toneMint
class node_app,node_results,node_account_card,node_status,node_dotwave toneRose
class node_clipboard_service,node_base32,node_i18n_hook,node_i18n_setup,node_analytics,node_network toneIndigo
```

## Components

### Input handling

- [File uploader](https://github.com/domiz918/totp_decoder/blob/main/web/src/components/FileUploader.tsx): `web/src/components/FileUploader.tsx`
- [Clipboard hook](https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useClipboard.ts): `web/src/hooks/useClipboard.ts`

### Decode and parse

- [Decode state](https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useQRDecoder.ts): `web/src/hooks/useQRDecoder.ts`
- [QR decoder](https://github.com/domiz918/totp_decoder/blob/main/web/src/core/QRDecoder.ts): `web/src/core/QRDecoder.ts`
- [Image loading](https://github.com/domiz918/totp_decoder/blob/main/web/src/services/ImageService.ts): `web/src/services/ImageService.ts`
- [QR recognition](https://github.com/domiz918/totp_decoder/blob/main/web/src/services/QRService.ts): `web/src/services/QRService.ts`
- [Standard parser](https://github.com/domiz918/totp_decoder/blob/main/web/src/parsers/StandardParser.ts): `web/src/parsers/StandardParser.ts`
- [Migration parser](https://github.com/domiz918/totp_decoder/blob/main/web/src/parsers/MigrationParser.ts): `web/src/parsers/MigrationParser.ts`
- [Migration payload](https://github.com/domiz918/totp_decoder/blob/main/web/src/otpMigration.ts): `web/src/otpMigration.ts`

### OTP generation

- [TOTP and URL service](https://github.com/domiz918/totp_decoder/blob/main/web/src/services/TOTPService.ts): `web/src/services/TOTPService.ts`
- [Live code timer](https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useTimer.ts): `web/src/hooks/useTimer.ts`

### Results interface

- [App orchestration](https://github.com/domiz918/totp_decoder/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Results list](https://github.com/domiz918/totp_decoder/blob/main/web/src/components/ResultsList.tsx): `web/src/components/ResultsList.tsx`
- [Account and QR card](https://github.com/domiz918/totp_decoder/blob/main/web/src/components/AccountCard.tsx): `web/src/components/AccountCard.tsx`
- [Decode status](https://github.com/domiz918/totp_decoder/blob/main/web/src/components/StatusMessage.tsx): `web/src/components/StatusMessage.tsx`
- [Animated background](https://github.com/domiz918/totp_decoder/blob/main/web/src/components/DotWave.tsx): `web/src/components/DotWave.tsx`

### Browser utilities

- [Clipboard service](https://github.com/domiz918/totp_decoder/blob/main/web/src/services/ClipboardService.ts): `web/src/services/ClipboardService.ts`
- [Base32 conversion](https://github.com/domiz918/totp_decoder/blob/main/web/src/utils/base32.ts): `web/src/utils/base32.ts`
- [Localization hook](https://github.com/domiz918/totp_decoder/blob/main/web/src/hooks/useI18n.ts): `web/src/hooks/useI18n.ts`
- [Localization setup](https://github.com/domiz918/totp_decoder/blob/main/web/src/i18n/index.ts): `web/src/i18n/index.ts`

### Other components

- **User**
- **Vercel Analytics**
- **Network services**

## Connections

- User → File uploader: drops files (evidence: `README.md`)
- User → Clipboard hook: pastes input (evidence: `README.md`)
- File uploader → App orchestration: uploads file (evidence: `web/src/App.tsx`)
- Clipboard hook → Clipboard service: uses (evidence: `web/src/hooks/useClipboard.ts`)
- Clipboard hook → App orchestration: submits text (evidence: `web/src/App.tsx`)
- App orchestration → Decode state: requests decode (evidence: `web/src/App.tsx`)
- Decode state → QR decoder: invokes (evidence: `web/src/hooks/useQRDecoder.ts`)
- QR decoder → Image loading: loads image (evidence: `web/src/core/QRDecoder.ts`)
- QR decoder → QR recognition: decodes QR (evidence: `web/src/core/QRDecoder.ts`)
- QR decoder → Standard parser: parses standard (evidence: `web/src/core/QRDecoder.ts`)
- QR decoder → Migration parser: parses migration (evidence: `web/src/core/QRDecoder.ts`)
- QR decoder → TOTP and URL service: creates raw-secret URL (evidence: `web/src/core/QRDecoder.ts`)
- Migration parser → Migration payload: decodes payload (evidence: `web/src/parsers/MigrationParser.ts`)
- Migration parser → Base32 conversion: converts secret (evidence: `web/src/parsers/MigrationParser.ts`)
- Standard parser → TOTP and URL service: generates code (evidence: `web/src/parsers/StandardParser.ts`)
- Migration parser → TOTP and URL service: generates code and URL (evidence: `web/src/parsers/MigrationParser.ts`)
- App orchestration → Live code timer: starts timers (evidence: `web/src/App.tsx`)
- Live code timer → TOTP and URL service: refreshes codes (evidence: `web/src/hooks/useTimer.ts`)
- App orchestration → Results list: renders results (evidence: `web/src/App.tsx`)
- App orchestration → Decode status: renders status (evidence: `web/src/App.tsx`)
- Results list → Account and QR card: renders accounts (evidence: `web/src/components/ResultsList.tsx`)
- Account and QR card → Clipboard hook: copies values
- App orchestration → Animated background: mounts background (evidence: `web/src/main.tsx`)
- Localization hook → Localization setup: uses translations
- App orchestration → Vercel Analytics: renders analytics (evidence: `web/src/App.tsx`)
- Vercel Analytics → Network services: may send telemetry
