# dag0310/otp-crypto architecture

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

- Interactive diagram: https://gitdiagram.com/dag0310/otp-crypto
- Repository: https://github.com/dag0310/otp-crypto

## Overview

##### Project type and purpose
- This is an open-source JavaScript/TypeScript library for pseudo one-time-pad encryption of plaintext (otp-crypto).
- It’s packaged as an npm module, tested with Karma/Mocha, and demoed via a static HTML page.

##### File structure
- Root files: configuration and metadata (.eslintrc.json, package.json, karma.conf.cjs, README.md, LICENSE).
- src/: the library source (otp-crypto.d.ts + otp-crypto.js).
- spec/: unit tests (otp-crypto.spec.js).
- demo/: browser demo (index.html pulls in otp-crypto).
- package.json: declares entry point, dependencies, scripts (lint, test).

##### Key insights from the README
- API surface: generateRandomBytes(), encrypt(plaintext, key), decrypt(base64, key).
- Data flow: key generation → encryption → Base64 encoding → decryption → remaining-key tracking.
- Demo and tests exercise the same core functions in browser and Node.

a. Core Library Module
- Key Generation Service
- Encryption Engine (XOR logic)
- Base64 Encoder/Decoder
- Decryption Engine
- Key Management (remainingKey flow)
b. Consumer Layers
- Demo Web App (demo/index.html + script tag)
- External Node.js App (npm install + import)
c. Development Tooling
- Test Runner (Karma + Mocha)
- Linter (ESLint)
- TypeScript typings (otp-crypto.d.ts)
d. Packaging & Deployment
- npm registry (package.json publish)
- GitHub Pages for demo

##### Relationships & interactions
- User calls generateRandomBytes() → Core Key Generation → returns Uint8Array key.
- User calls encrypt(plaintext, key) → Encryption Engine → Base64 Encoder → returns { base64Encrypted, remainingKey }.
- User calls decrypt(base64Encrypted, key) → Base64 Decoder → Decryption Engine → returns { plaintextDecrypted, remainingKey }.
- Demo Web App imports library via <script> or ES module → invokes API.
- Test Runner imports library → exercises API in headless browser/Node environment.
- Linter runs on src/ and spec/ prior to tests.
- package.json scripts wire up lint/test and define entry point for consumers.

##### Architectural patterns & design principles
- Modular single-responsibility: each sub-module (key gen, encrypt, base64, decrypt) encapsulated within one file.
- Functional API: pure functions that return new state (remainingKey) without side-effects.
- Separation of concerns: core logic decoupled from consumers (demo & tests).

##### Detailed capture of essential elements
- Data flow of the key and message.
- “remainingKey” feedback loop after encrypt/decrypt.
- Npm registry & GitHub Pages as external endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Core Library"
        direction TB
        KeyGen["KeyGen Service\ngenerateRandomBytes()"]:::core
        Encrypt["Encryption Engine\nencrypt()"]:::core
        Base64["Base64 Encoder/Decoder"]:::core
        Decrypt["Decryption Engine\ndecrypt()"]:::core
        KeyMgmt["Key Management\nremainingKey"]:::core
        Typings["TypeScript Typings\notp-crypto.d.ts"]:::core
    end

    KeyGen -->|"generates key"| Encrypt
    Encrypt -->|"outputs encrypted bytes"| Base64
    Base64 -->|"returns Base64 string"| Encrypted("Encrypted(Base64)"):::data
    Encrypted -->|"input for decrypt"| Decrypt
    Decrypt -->|"returns plaintext"| Decrypted("Decrypted(Text)"):::data
    Encrypt -->|"updates"| KeyMgmt
    Decrypt -->|"updates"| KeyMgmt
    KeyMgmt -->|"provides remainingKey"| Encrypt
    KeyMgmt -->|"provides remainingKey"| Decrypt

    subgraph "Consumers"
        direction TB
        Demo["Demo Web App"]:::consumer
        NodeApp["Node.js App"]:::consumer
        TestRunner["Test Runner"]:::consumer
    end

    Demo -->|"calls encrypt/decrypt"| Encrypt
    NodeApp -->|"calls encrypt/decrypt"| Encrypt
    TestRunner -->|"tests API"| Encrypt
    TestRunner -->|"tests API"| Decrypt

    subgraph "Dev Tools"
        direction TB
        ESLint["ESLint"]:::dev
        KarmaMocha["Karma + Mocha"]:::dev
    end

    ESLint -->|"lints"| KeyGen
    ESLint -->|"lints"| TestRunner
    KarmaMocha -->|"runs tests on"| TestRunner
    KarmaMocha -->|"runs tests on"| KeyGen

    subgraph "Packaging/Deployment"
        direction TB
        npmReg["npm Registry"]:::deploy
        GHPages["GitHub Pages"]:::deploy
        PackageJSON["package.json"]:::deploy
        README["README.md"]:::deploy
        License["LICENSE"]:::deploy
    end

    PackageJSON -->|"publish"| npmReg
    Demo -->|"host demo"| GHPages

    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef consumer fill:#D6F5D6,stroke:#333,stroke-width:1px
    classDef dev fill:#FFE7C5,stroke:#333,stroke-width:1px
    classDef deploy fill:#E5D1FF,stroke:#333,stroke-width:1px
    classDef data fill:#FFF2CC,stroke:#666,stroke-width:1px

    click KeyGen "https://github.com/dag0310/otp-crypto/blob/master/src/otp-crypto.js"
    click Encrypt "https://github.com/dag0310/otp-crypto/blob/master/src/otp-crypto.js"
    click Base64 "https://github.com/dag0310/otp-crypto/blob/master/src/otp-crypto.js"
    click Decrypt "https://github.com/dag0310/otp-crypto/blob/master/src/otp-crypto.js"
    click KeyMgmt "https://github.com/dag0310/otp-crypto/blob/master/src/otp-crypto.js"
    click Typings "https://github.com/dag0310/otp-crypto/blob/master/src/otp-crypto.d.ts"
    click Demo "https://github.com/dag0310/otp-crypto/blob/master/demo/index.html"
    click NodeApp "https://github.com/dag0310/otp-crypto/blob/master/package.json"
    click TestRunner "https://github.com/dag0310/otp-crypto/blob/master/spec/otp-crypto.spec.js"
    click ESLint "https://github.com/dag0310/otp-crypto/blob/master/.eslintrc.json"
    click KarmaMocha "https://github.com/dag0310/otp-crypto/blob/master/karma.conf.cjs"
    click PackageJSON "https://github.com/dag0310/otp-crypto/blob/master/package.json"
    click README "https://github.com/dag0310/otp-crypto/blob/master/README.md"
    click License "https://github.com/dag0310/otp-crypto/tree/master/LICENSE"
```
