# satty-br/loki architecture

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

- Interactive diagram: https://gitdiagram.com/satty-br/loki
- Repository: https://github.com/satty-br/loki

## Overview

##### Project type and purpose
- LOKI is a **Python CLI tool** whose purpose is to automatically inject realistic security vulnerabilities into target repos and open a PR on GitHub.
- It leverages an LLM (OpenAI or local) plus GitHub APIs to analyze, plan, inject, and push changes.

##### File structure
- Only five top-level files: `.gitignore`, `LICENSE`, `README.md`, `main.py`, `requirements.txt`.
- All core logic lives in `main.py`.
- Dependencies listed in requirements include GitPython, PyYAML, GitHub API client, OpenAI SDK or another LLM client.

##### Key components
a. **CLI & Config Parser**
- Parses command-line args (`--llm-endpoint`, `--model-name`, `--github-token`, etc.).
b. **Repository Manager**
- Clones target repo into `clone_dir` using GitPython.
c. **Static & Dependency Analyzer**
- Scans files, languages, dependency manifests (`requirements.txt`, `package.json`, etc.).
d. **Vulnerability Planner (AI Module)**
- Sends repo context to LLM endpoint; receives a plan of what vulnerabilities to inject.
e. **Injection Engine**
- Applies code changes (e.g., hardcoded secrets, unsafe evals) and updates dependency versions.
f. **Git Commit & Brancher**
- Creates a new branch, stages and commits injected changes.
g. **Pull Request Creator**
- Uses GitHub API client to push branch and open a PR with descriptive details.
h. **Temporary Storage**
- Local filesystem path (`./temp_repo`) holds the cloned repo and modified files.
i. **External Services**
- **LLM Endpoint** (OpenAI or local)
- **GitHub API**

##### Architectural patterns & design principles
- **Modular monolith**: Single script logically separated into distinct components.
- **Command-Query Separation**: Analysis/planning is separate from injection/commit steps.
- **Externalization of AI**: LLM is a remote service, decoupled via endpoint interface.
- **Ephemeral state**: All repo changes occur in a transient `temp_repo`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Modules and Components
    A["CLI & Config Parser"]:::data
    B["Repository Manager"]:::data
    C["Static & Dependency Analyzer"]:::data
    D["Vulnerability Planner (AI Module)"]:::data
    E["Injection Engine"]:::data
    F["Git Commit & Brancher"]:::git
    G["Pull Request Creator"]:::git

    %% Storage
    H["Temp Storage<br/>(Filesystem)"]:::storage

    %% External Services
    I["LLM Endpoint"]:::external
    J["GitHub API"]:::external

    %% Documentation & Config
    K["Requirements Specification"]:::doc
    L["Project Documentation"]:::doc
    M["License Information"]:::doc
    N["Git Ignore Configuration"]:::doc

    %% Flow
    U["User/CI"]:::external -->|"runs python main.py"| A
    A -->|"parsed args: llm-endpoint, model, tokens"| B
    B -->|"clones repo"| H
    B -->|"repo metadata"| C
    C -->|"analysis results"| D
    D -->|"AI plan"| I
    I -->|"plan JSON"| D
    D -->|"plan details"| E
    E -->|"modified files"| H
    E -->|"changes"| F
    F -->|"git push"| J
    F -->|"branch created & committed"| G
    G -->|"open PR"| J
    G -->|"PR URL"| A

    %% Documentation/config links
    N --> A
    K --> C
    L --> A
    M --> A

    %% Click Events
    click A "https://github.com/satty-br/loki/blob/main/main.py"
    click B "https://github.com/satty-br/loki/blob/main/main.py"
    click C "https://github.com/satty-br/loki/blob/main/main.py"
    click D "https://github.com/satty-br/loki/blob/main/main.py"
    click E "https://github.com/satty-br/loki/blob/main/main.py"
    click F "https://github.com/satty-br/loki/blob/main/main.py"
    click G "https://github.com/satty-br/loki/blob/main/main.py"
    click K "https://github.com/satty-br/loki/blob/main/requirements.txt"
    click L "https://github.com/satty-br/loki/blob/main/README.md"
    click M "https://github.com/satty-br/loki/tree/main/LICENSE"
    click N "https://github.com/satty-br/loki/blob/main/.gitignore"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#E2FFD8,stroke:#28A745,color:#28A745,stroke-dasharray: 5 2;
    classDef storage fill:#F2F2F2,stroke:#888888,color:#555555,stroke-dasharray: 2 2;
    classDef git fill:#FFF5CC,stroke:#FFA500,color:#FFA500;
    classDef doc fill:#F9EFFF,stroke:#6F42C1,color:#6F42C1;
```
