# rogerluan/arkana architecture

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

- Interactive diagram: https://gitdiagram.com/rogerluan/arkana
- Repository: https://github.com/rogerluan/arkana

## Overview

##### Project Overview – Identify the Project Type and Purpose
- Arkana is a Ruby gem designed to securely manage and generate code (for iOS and Android) that encapsulates secrets and keys. It works by parsing YAML config files and dotenv files, enciphering data with salt, and then generating source code for the appropriate language (Swift or Kotlin).
- Its main purpose is to abstract secret management, ensuring keys are not hardcoded but generated at build-time using a code-generation technique.

##### Primary Components of the System – What
A. Command-Line Interface (CLI):
- Represented by the executables in the “bin” directory (e.g., bin/arkana, bin/console, bin/setup).
- This layer is responsible for parsing command-line arguments and triggering the rest of the process.

B. Configuration & Input Layer:
- Config Parser (lib/arkana/config_parser.rb): Loads the YAML configuration file (.arkana.yml) and maps settings (environments, environment secrets, global secrets).
- Dotenv Loader (lib/arkana/helpers/dotenv_helper.rb): Loads data from a .env file or environment variables.

C. Models & Domain Logic:
- Models (found in lib/arkana/models): Represent the parsed configuration (Arguments, Config, Salt, Secret, TemplateArguments, Type, etc.).
- The model layer holds the business rules for secret declarations and how environment-specific keys should be interpreted.

D. Secret Generation & Encoding Modules:
- Salt Generator (lib/arkana/salt_generator.rb): Responsible for creating a salt that changes on each run.
- Encoder (lib/arkana/encoder.rb): Takes the plaintext from the dotenv file and encodes it using the salt.

E. Code Generation & Template Rendering:
- Code Generators:
- Kotlin Code Generator (lib/arkana/kotlin_code_generator.rb)
- Swift Code Generator (lib/arkana/swift_code_generator.rb)
- Templates Directory (lib/arkana/templates): Contains ERB templates for Swift and Kotlin code. These define how the generated accessor structures (classes/protocols, e.g., Global, Debug, Release) appear.
- Template Helpers (lib/arkana/helpers/kotlin_template_helper.rb and swift_template_helper.rb): Assist in rendering and formatting templates with the correct naming conventions.

F. Testing & CI Integration:
- Test suite (spec/): Contains RSpec tests for the above modules.
- CI Workflows (in the .github/workflows directory): Automates tests and code quality checks for Ruby, Kotlin, and Swift integrations.

G. Documentation & Developer Tools:
- Documentation folder (docs): Contains demo images and code previews that help illustrate the generated code’s appearance.

##### Relationships and Data Flow
- The CLI acts as the entry point – it takes in command-line options, then calls the Configuration Parser.
- The Config Parser reads the YAML config and uses the Dotenv Helper to fetch environment variables.
- Parsed configuration data is encapsulated into Model objects.
- The Code Generation module then uses these models along with the Salt Generator and Encoder to produce properly encoded secrets.
- The Code Generator uses the Template Engine with ERB templates (with the help of platform-specific template helpers) to generate Swift or Kotlin files.
- Finally, the generated files are written to disk and later integrated into iOS/Android projects, as indicated by the README (via SPM, CocoaPods, or Gradle module integration).
- RSpec tests ensure that each component behaves as expected. Additionally, GitHub Actions workflows run tests and linters, indicating continuous integration of the code quality checks.

##### Architectural Patterns or Design Principles
- Modular Design: Show that the generators for Swift and Kotlin are encapsulated and interchangeable based on the ‘--lang’ option.
- Template/Code Generation Pattern: Emphasize how ERB templates are used with corresponding helpers for output file generation.

##### Elements
- Each component should be clearly labeled. For example, "CLI (bin/arkana)", "Configuration Parser", "Dotenv Loader", "Salt Generator", "Encoder", "Swift/Kotlin Code Generator", and "Template Engine".
- Data flow from CLI → Config Parser → Models → Salt/Encoder → Code Generator → File Output.

##### Final Assembly
- Under it, branch out into “Configuration & Input” (YAML & dotenv file readers) feeding into “Domain Models.”
- Have a parallel flow where “Salt Generator” and “Encoder” work together to secure the secrets.
- Optionally, include a side block titled “CI / Testing” that interacts with the CLI and passes on feedback/status.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Block
    subgraph "Arkana CLI"
        CLI1["CLI (bin/arkana)"]:::cli
        CLI2["CLI (bin/console)"]:::cli
        CLI3["CLI (bin/setup)"]:::cli
    end

    %% Configuration & Input Block
    subgraph "Configuration & Input"
        CP["Configuration Parser"]:::input
        DL["Dotenv Loader"]:::input
    end

    %% Domain Models Block
    subgraph "Models & Domain Logic"
        MODELS["Models"]:::processing
    end

    %% Secret Generation Block
    subgraph "Secret Generation"
        SG["Salt Generator"]:::processing
        ENC["Encoder"]:::processing
    end

    %% Code Generation Block
    subgraph "Code Generation"
        subgraph "Swift Code Generation"
            SCG["Swift Code Generator"]:::output
            STTH["Swift Template Helper"]:::output
        end
        subgraph "Kotlin Code Generation"
            KCG["Kotlin Code Generator"]:::output
            KTTH["Kotlin Template Helper"]:::output
        end
        TEMPL["Templates"]:::output
    end

    %% Output Files Block
    OFILE["Output Files (iOS/Android Projects)"]:::output

    %% CI / Testing Block
    subgraph "CI / Testing"
        TEST["RSpec Tests"]:::testing
        CIW["CI Workflows"]:::testing
    end

    %% Documentation & Developer Tools Block
    subgraph "Documentation & Developer Tools"
        DOC["Documentation"]:::documentation
        CHANGELOG["CHANGELOG"]:::documentation
        CODE_OF_CONDUCT["CODE_OF_CONDUCT"]:::documentation
        LICENSE_NODE["LICENSE"]:::documentation
    end

    %% Connections - Vertical Flow
    CLI1 -->|"triggers"| CP
    CLI2 -->|"triggers"| CP
    CLI3 -->|"triggers"| CP

    CP -->|"loads"| DL
    CP -->|"populates"| MODELS
    DL -->|"populates"| MODELS

    MODELS -->|"supplies data"| SG
    MODELS -->|"supplies data"| ENC
    SG -->|"generates salt for"| ENC

    ENC -->|"feeds into"| SCG
    ENC -->|"feeds into"| KCG

    SCG -->|"uses"| STTH
    KCG -->|"uses"| KTTH

    STTH -->|"renders with"| TEMPL
    KTTH -->|"renders with"| TEMPL

    TEMPL -->|"creates"| OFILE

    %% CI / Testing interactions
    CLI1 ---|"verified by"| TEST
    CLI1 ---|"verified by"| CIW

    %% Documentation interactions (peripheral)
    CLI1 -.-> DOC
    CLI1 -.-> CHANGELOG
    CLI1 -.-> CODE_OF_CONDUCT
    CLI1 -.-> LICENSE_NODE

    %% Class Definitions for styling
    classDef cli fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef input fill:#a7d8ff,stroke:#333,stroke-width:2px;
    classDef processing fill:#d8f7be,stroke:#333,stroke-width:2px;
    classDef output fill:#ffe599,stroke:#333,stroke-width:2px;
    classDef testing fill:#f9cb9c,stroke:#333,stroke-width:2px;
    classDef documentation fill:#ead1dc,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI1 "https://github.com/rogerluan/arkana/tree/main/bin/arkana"
    click CLI2 "https://github.com/rogerluan/arkana/tree/main/bin/console"
    click CLI3 "https://github.com/rogerluan/arkana/tree/main/bin/setup"
    click CP "https://github.com/rogerluan/arkana/blob/main/lib/arkana/config_parser.rb"
    click DL "https://github.com/rogerluan/arkana/blob/main/lib/arkana/helpers/dotenv_helper.rb"
    click MODELS "https://github.com/rogerluan/arkana/tree/main/lib/arkana/models"
    click SG "https://github.com/rogerluan/arkana/blob/main/lib/arkana/salt_generator.rb"
    click ENC "https://github.com/rogerluan/arkana/blob/main/lib/arkana/encoder.rb"
    click SCG "https://github.com/rogerluan/arkana/blob/main/lib/arkana/swift_code_generator.rb"
    click KCG "https://github.com/rogerluan/arkana/blob/main/lib/arkana/kotlin_code_generator.rb"
    click STTH "https://github.com/rogerluan/arkana/blob/main/lib/arkana/helpers/swift_template_helper.rb"
    click KTTH "https://github.com/rogerluan/arkana/blob/main/lib/arkana/helpers/kotlin_template_helper.rb"
    click TEMPL "https://github.com/rogerluan/arkana/tree/main/lib/arkana/templates"
    click TEST "https://github.com/rogerluan/arkana/tree/main/spec/"
    click CIW "https://github.com/rogerluan/arkana/tree/main/.github/workflows"
    click DOC "https://github.com/rogerluan/arkana/tree/main/docs"
    click CHANGELOG "https://github.com/rogerluan/arkana/blob/main/CHANGELOG.md"
    click CODE_OF_CONDUCT "https://github.com/rogerluan/arkana/blob/main/CODE_OF_CONDUCT.md"
    click LICENSE_NODE "https://github.com/rogerluan/arkana/tree/main/LICENSE"
```
