# mrfrazer25/2fa-app architecture

> Architecture diagram of the GitHub repository mrfrazer25/2fa-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrfrazer25/2fa-app
- Repository: https://github.com/mrfrazer25/2fa-app

## Overview

##### Project Type and Purpose
- This is a standalone Python desktop application for managing two-factor authentication (2FA) tokens.
- It provides a modern GUI (CustomTkinter), secure secret storage (OS keyring), PIN protection, encrypted backup/restore, and TOTP code generation.

##### File Structure
Top-level files & folders:
- main.py – application entrypoint and bootstrap
- core/ – business logic layer
– app_lock.py (PIN management, auto-lock)
– secure_storage.py (keyring wrapper, backup encryption)
- ui/ – presentation layer (CustomTkinter views & dialogs)
– add_token_dialog.py, pin_dialog.py, password_dialog.py, recovery_codes_dialog.py, settings_frame.py, sidebar.py, token_card.py
- requirements.txt – dependencies (CustomTkinter, keyring, cryptography, etc.)

##### Extract Architecture Insights from README
- Security through OS keyring + PBKDF2-SHA256 + AES-GCM
- UI theming (Light/Dark/System)
- Features tied to core services: token CRUD, clipboard auto-clear, auto-lock, encrypted JSON backup

##### Main Components & Their Relationships
A. UI Layer (CustomTkinter)
- Windows, dialogs, frames under ui/
- Presents token cards, forms, settings, PIN prompts
- Calls core services via well-defined method interfaces
B. Core Logic
1. AppLock (core/app_lock.py)
- Manages PIN hash & salt (PBKDF2)
- Tracks inactivity, triggers auto-lock events
2. SecureStorage (core/secure_storage.py)
- Reads/writes TOTP secrets & recovery codes to OS keyring
- Exports/imports encrypted JSON backups (AES-256-GCM)
C. System Services & External Dependencies
- OS Keyring backend (Windows Credential Manager, macOS Keychain, Linux Secret Service)
- File system for encrypted backup files (.json)
- Cryptography library (AES-GCM, PBKDF2)
- Clipboard service for copying codes

Interaction Flow Examples:
- Startup: main.py → AppLock.check_or_set_pin() → UI.pin_dialog → on success → UI.main_window
- Token: UI.add_token_dialog → SecureStorage.store_secret(keyring) → UI.token_card refresh
- Generate Code: UI.token_card → TOTP algorithm in core/secure_storage → UI display
- Backup: UI.settings_frame “Export” → SecureStorage.export_backup() (derive key via PBKDF2 → AES-GCM → write file)

##### Architectural Patterns & Design Principles
- Layered Separation: UI (View) ↔ Core (Model/Services) ↔ External (OS & FS)
- Single Responsibility: each module handles one concern (PIN logic, storage, presentation)
- Dependency Inversion: core code depends on keyring/cryptography abstracts, not UI
- Secure by Design: clear boundary between untrusted input (UI) and sensitive operations (core + OS services)

[ ] Separate UI, Core, External lanes
[ ] Label modules & show their file paths (e.g., ui/token_card.py)
[ ] Include all critical operations: PIN management, keyring storage, TOTP generation, backup encryption, clipboard clearing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        A["Add Token Dialog"]:::ui
        B["PIN Dialog"]:::ui
        C["Password/Backup Dialog"]:::ui
        D["Recovery Codes Dialog"]:::ui
        E["Settings Frame"]:::ui
        F["Sidebar"]:::ui
        G["Token Card"]:::ui
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        H(("AppLock")):::core
        I(("SecureStorage")):::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        J["OS Keyring"]:::external
        K["Filesystem (.json)"]:::external
        L["Clipboard"]:::external
        M[/"Cryptography Library"/]:::lib
    end

    %% UI → Core
    B -->|"verify_pin() / set_pin()"| H
    A -->|"store_secret()"| I
    G -->|"generate_totp()"| I
    G -->|"copy_code()"| L
    E -->|"export_backup() / import_backup()"| I

    %% Core → External
    H -->|"PBKDF2-SHA256"| M
    I -->|"keyring.set_password() / get_password()"| J
    I -->|"AESGCM.encrypt()/decrypt()"| M
    I -->|"write/read .json"| K

    %% Core → UI
    H -->|"unlock_event"| B
    I -->|"totp_code"| G

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
    classDef lib fill:#f8f9fa,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5;

    %% Click events
    click A "https://github.com/mrfrazer25/2fa-app/blob/main/ui/add_token_dialog.py"
    click B "https://github.com/mrfrazer25/2fa-app/blob/main/ui/pin_dialog.py"
    click C "https://github.com/mrfrazer25/2fa-app/blob/main/ui/password_dialog.py"
    click D "https://github.com/mrfrazer25/2fa-app/blob/main/ui/recovery_codes_dialog.py"
    click E "https://github.com/mrfrazer25/2fa-app/blob/main/ui/settings_frame.py"
    click F "https://github.com/mrfrazer25/2fa-app/blob/main/ui/sidebar.py"
    click G "https://github.com/mrfrazer25/2fa-app/blob/main/ui/token_card.py"
    click H "https://github.com/mrfrazer25/2fa-app/blob/main/core/app_lock.py"
    click I "https://github.com/mrfrazer25/2fa-app/blob/main/core/secure_storage.py"
    click J "https://github.com/mrfrazer25/2fa-app/tree/main/assets/"
    click K "https://github.com/mrfrazer25/2fa-app/blob/main/requirements.txt"
```
