How rogerluan/arkana works
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.