# pwnxpl0it/spark architecture

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

- Interactive diagram: https://gitdiagram.com/pwnxpl0it/spark
- Repository: https://github.com/pwnxpl0it/spark

## Overview

##### Project Type and Purpose
- Spark is a command-line tool written in Rust that serves as a TOML-based project initializer. Its main purpose is to help users quickly generate project scaffolding using templates defined in TOML, with dynamic placeholder substitution, Git integration, JSON support, and Liquid templating.
- The tool is not a typical full-stack web application but a CLI utility with a clear separation between command-line parsing and core template processing and generation logic.

##### File Structure
- Top-Level Files/Directories:
- .github and its workflows: Contains CI configurations (e.g., rust.yml) to validate builds, ensuring the tool is tested and maintains quality.
- Cargo.toml, Cargo.lock, rustfmt.toml: These files indicate the Rust build system and code formatting rules.
- src directory:
▪ cli folder: Contains files like args.rs, config.rs, main.rs. This indicates the command-line interface layer where user input is parsed, and configuration is loaded.
▪ core folder: Contains the heart of the functionality (lib.rs, funcs.rs, keywords.rs, templates, and utils.rs). This layer handles template processing, dynamic placeholders, function calls, Git integration (seen via templates/options/git), and possibly environment variable and JSON integration.
- test.sh: Likely a helper script for testing or demonstrations.

##### README for Additional Insights
- The README explains the features and use cases of Spark in depth, highlighting:
- TOML-based templating, dynamic placeholders, CLI flag (--from) for overriding values, Liquid templating support.
- Examples of different template structures.
- Git integration and environment/JSON features.
- This confirms that the core is designed around flexible template processing and transformation using various templating techniques and configurations.

##### Mapping the Main Components and Their Relationships
a. Core Components:
- CLI Component:
- Located in src/cli (args.rs, config.rs, main.rs).
- Responsible for accepting user arguments, commands (like spark new, spark init), and loading configuration data.
- Core Processing/Template Engine:
- Located in src/core (lib.rs, funcs.rs, keywords.rs, utils.rs).
- Handles dynamic placeholders, custom functions for reading user inputs, and template customization.
- Manages file generation based on TOML templates.
- Template Management:
- Inside src/core/templates and its subdirectories (like options and specifically git under options).
- Contains logic and options specific to a template (e.g., Git initialization settings).
- External Integrations:
- Git integration: As seen in options/git templates, establishing steps to initialize or integrate with Git.
- JSON integration: Supports replacing placeholders using an external JSON file for non-interactive setups.
- Liquid Templating: Provides an additional layer of templating that works alongside the Spark’s custom syntax.
- Configuration and Environment Management:
- Uses configuration files (from CLI and potentially in user’s config directory like ~/.config/spark/config.toml) to load constants and keywords for replacement.

b. Relationships/Interactions:
- The CLI component takes user input (commands and flags such as --from) and passes control to the core engine.
- The core engine reads the TOML template definitions and parses placeholders that might trigger interaction with:
- Functions for reading user input or processing environment variables.
- JSON files if provided via command-line.
- Liquid templating for advanced customization loops or conditionals.
- Finally, the engine generates or writes the output files per the given template, with integrations (e.g., Git initialization) being invoked as needed.

##### Important Architectural Patterns and Design Principles
- Layered Architecture: There is a clear separation between the CLI (presentation layer) and the core business logic (application layer).
- Template/Plugin Architecture: The project is highly configurable, allowing plugins/extensions through the use of TOML templates, dynamic functions, and keyword substitutions.
- Configuration Driven: The behavior (like Git integration, JSON value substitution) is largely determined by user-defined configuration and the provided TOML templates.
- Use of External Tools/Standards: Integration with Git, JSON, and Liquid indicates a design that leverages standard technologies to enhance flexibility.

##### Specific Elements
- “Core Template Engine” (src/core) as the central processing unit:
- Sub-components: Dynamic Placeholder Processor (functions in funcs.rs), Template File Processor (modules under src/core/templates), and Utility functions.
- “Template Options & External Integration”:
- Separate out Git integration options (src/core/templates/options/git) and JSON/ Liquid templating components.
- “Configuration Management”:
- How the tool loads its runtime configuration (from config files like ~/.config/spark/config.toml or command-line overrides).
- “Output Generation”:
- Generation of files and directories as the final output of the system, with dependencies traced from the processed templates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    A["User Command/Input"]:::user

    %% CLI Interface
    subgraph "CLI Interface"
        B["CLI Parser (src/cli)"]:::cli
    end

    %% Core Processing
    subgraph "Core Processing"
        C["Core Template Engine (src/core)"]:::core
        D["Dynamic Placeholder Processor"]:::core
        E["Template File Processor"]:::core
        F["Utility Functions"]:::core
    end

    %% Template Management and External Integrations
    subgraph "Template Management"
        G["Templates & Options (src/core/templates)"]:::templ
        H["Git Integration (src/core/templates/options/git)"]:::templ
        I["JSON & Liquid Templating"]:::templ
    end

    %% Configuration and Build Settings
    subgraph "Configuration & Build"
        J["Runtime Configuration"]:::config
        K["Project Config & Build System"]:::config
        L["CI/Build Configuration"]:::config
    end

    %% Output Generation
    subgraph "Output Generation"
        M["Generated Files/Directories"]:::output
    end

    %% Relationships / Data Flow
    A -->|"invokes"| B
    B -->|"forwards_args"| C
    C -->|"processes"| D
    C -->|"handles_templates"| E
    C -->|"uses"| F
    D -->|"aids"| E
    C -->|"retrieves"| G
    G -->|"includes"| H
    G -->|"integrates"| I
    C -->|"outputs_to"| M
    J -->|"configures"| B
    J -->|"configures"| C
    K -->|"supports"| B
    K -->|"supports"| C
    L -->|"validates"| B

    %% Styles
    classDef user fill:#f9d5e5,stroke:#e48f9a,stroke-width:2px;
    classDef cli fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef core fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef templ fill:#ffebcc,stroke:#ff9933,stroke-width:2px;
    classDef config fill:#f7fe2e,stroke:#cccc00,stroke-width:2px;
    classDef output fill:#e8daef,stroke:#af7ac5,stroke-width:2px;

    %% Applying Classes
    class A user;
    class B cli;
    class C,D,E,F core;
    class G,H,I templ;
    class J,K,L config;
    class M output;

    %% Click Events
    click B "https://github.com/pwnxpl0it/spark/tree/main/src/cli"
    click C "https://github.com/pwnxpl0it/spark/tree/main/src/core"
    click G "https://github.com/pwnxpl0it/spark/tree/main/src/core/templates"
    click H "https://github.com/pwnxpl0it/spark/tree/main/src/core/templates/options/git"
    click L "https://github.com/pwnxpl0it/spark/blob/main/.github/workflows/rust.yml"
    click K "https://github.com/pwnxpl0it/spark/blob/main/Cargo.toml"
```
