# dim13/otpauth architecture

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

- Interactive diagram: https://gitdiagram.com/dim13/otpauth
- Repository: https://github.com/dim13/otpauth

## Overview

##### Identify the Project Type and Purpose
- **Project Type:**
This is a **CLI and Web Application** built in Go, designed to decode Google Authenticator migration links and convert them into standard `otpauth` links. It also provides functionalities such as QR code generation, HTTP serving for a web interface, and Docker support for containerization.

- **Purpose:**
The tool facilitates the migration of 2FA accounts from Google Authenticator by decoding migration URLs and providing both command-line and web-based interfaces for managing and visualizing the converted `otpauth` links.

##### Analyze the File Structure
- **Top-Level Directories and Files:**
- `.github/`: Contains GitHub workflows for CI/CD (e.g., `go.yml`) and release scripts.
- `migration/`: Core logic for processing migration links, including Go source files and Protocol Buffer definitions.
- `static/`: Web assets such as `index.html`, `style.css`, and `events.js`.
- `images/`: Contains image assets like logos and examples.
- `main.go` & `http.go`: Entry points for the CLI and HTTP server respectively.
- `Dockerfile`: Defines the containerization process.
- Configuration and dependency files (`go.mod`, `go.sum`, `.gitignore`).

- **Architectural Patterns:**
- **Modular Structure:** Separation between migration logic (`migration/`), web server (`http.go` and `static/`), and main application entry points.
- **MVC Pattern (Implicit):** Web server serving static frontend assets and handling HTTP requests, potentially following Model-View-Controller principles.
- **Microservices Elements:** While not fully microservices, the clear separation of concerns suggests a service-oriented approach within the application.

##### Examine the README for Additional Insights
- **Functionalities Highlighted:**
- Conversion of migration links to `otpauth` links.
- Command-line flags for various operations (e.g., `-qr`, `-http`).
- HTTP server setup for a web interface.
- Docker integration for easy deployment.

- **Technological Stack:**
- **Programming Language:** Go
- **Containerization:** Docker
- **Version Control & CI/CD:** GitHub Actions workflows

- **Usage Scenarios:**
- CLI-based conversion and evaluation of OTPs.
- Web-based interaction via an HTTP server.
- Deployment using Docker for consistent environments.

**a. Identify the Main Components:**
- **Command-Line Interface (CLI):**
- Handles user input via terminal.
- Executes conversion, evaluation, QR code generation based on flags.

- **HTTP Server:**
- Serves the web interface (`index.html`, `style.css`, `events.js`).
- Provides API endpoints for conversion and other functionalities.

- **Migration Module (`migration/`):**
- Core logic for decoding and converting migration links.
- Handles QR code generation and evaluation of OTPs.
- Utilizes Protocol Buffers (`migration.proto`) for data serialization.

- **Static Assets:**
- Frontend resources served by the HTTP server.

- **Docker Container:**
- Encapsulates the application, ensuring consistent runtime environments.
- Manages port mapping and volume mounting for the working directory.

- **GitHub Workflows:**
- Automates CI/CD processes such as testing and building Docker images.

**b. Determine Relationships and Interactions:**
- **CLI and HTTP Server** both interact with the **Migration Module** to perform their respective functions.
- **HTTP Server** serves **Static Assets** to clients and communicates with the **Migration Module** for backend processing.
- **Docker Container** encapsulates the **CLI**, **HTTP Server**, and **Migration Module**, handling dependencies and environment setup.
- **GitHub Workflows** automate testing and deployment processes, ensuring code quality and facilitating releases.

**c. Highlight Architectural Patterns and Design Principles:**
- **Separation of Concerns:** Clear division between CLI, HTTP server, migration logic, and frontend assets.
- **Modularity:** Each component is modular, promoting maintainability and scalability.
- **Containerization:** Use of Docker enhances deployment flexibility and environment consistency.
- **Automation:** GitHub Actions workflows ensure streamlined CI/CD pipelines.

**d. Include Relevant Technologies, Frameworks, or Libraries:**
- **Go:** Primary programming language for both backend and CLI.
- **Docker:** For containerization.
- **Protocol Buffers:** For data serialization (`migration.proto`).
- **GitHub Actions:** For CI/CD workflows.
- **Frontend Technologies:** HTML, CSS, JavaScript for the web interface.

##### Elements

- **Clear Labels for Each Component:**
- CLI
- HTTP Server
- Migration Module
- Static Assets
- Docker Container
- GitHub Workflows

- From CLI/Web Interface to Migration Module.
- From Migration Module to Output (e.g., `otpauth` links, QR codes).
- From Docker to all runtime components.
- From GitHub Workflows to Docker and Repository.

##### User Interface Layer
- **CLI:** Direct interaction via terminal.
- **Web Interface:** Accessed through the HTTP server.

##### Application Layer
- **HTTP Server:** Handles web requests and serves static files.
- **Migration Module:** Core processing logic for decoding and converting links.

##### Infrastructure Layer
- **Docker Container:** Encapsulates the application environment.
- **GitHub Actions:** Manages CI/CD pipelines.

##### Data Flow
- Users interact with the CLI or Web Interface.
- Inputs are processed by the Migration Module.
- Outputs are generated as `otpauth` links or QR codes.
- Docker manages the deployment and runtime consistency.
- GitHub Actions ensures automated testing and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Styles
    classDef frontend fill:#1f78b4,stroke:#333,stroke-width:2px;
    classDef backend fill:#33a02c,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#ff7f00,stroke:#333,stroke-width:2px;

    %% Components
    CLI["Command-Line Interface (CLI)"]:::backend
    HTTP["HTTP Server"]:::backend
    Migration["Migration Module"]:::backend
    Static["Static Assets"]:::frontend
    Docker["Docker Container"]:::infrastructure
    GitHub["GitHub Workflows"]:::infrastructure

    %% Subgraphs
    subgraph "User Interface Layer"
        CLI
        Web["Web Interface"]
    end

    subgraph "Application Layer"
        HTTP
        Migration
    end

    subgraph "Infrastructure Layer"
        Docker
        GitHub
    end

    %% Connections
    CLI --> Migration
    HTTP --> Migration
    HTTP --> Static
    Web --> HTTP
    Migration --> Output["Outputs: otpauth links, QR codes"]
    Docker --> CLI
    Docker --> HTTP
    Docker --> Migration
    GitHub --> Docker
    GitHub --> Repository["Repository"]

    %% Click Events
    click CLI "https://github.com/dim13/otpauth/blob/master/main.go"
    click HTTP "https://github.com/dim13/otpauth/blob/master/http.go"
    click Migration "https://github.com/dim13/otpauth/tree/master/migration/"
    click Static "https://github.com/dim13/otpauth/tree/master/static/"
    click Docker "https://github.com/dim13/otpauth/tree/master/Dockerfile"
    click GitHub "https://github.com/dim13/otpauth/blob/master/.github/workflows/go.yml"
    
    %% Additional Nodes
    Output["Outputs: otpauth links, QR codes"]:::backend
    Repository["Repository"]:::infrastructure

    %% Styles Override (if needed)
    class Output backend
    class Repository infrastructure
```
