# 404cisco/pain-x architecture

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

- Interactive diagram: https://gitdiagram.com/404cisco/pain-x
- Repository: https://github.com/404cisco/pain-x

## Overview

##### Project type and purpose
- PAIN-X is a Python-based, AI-powered command-line assistant.
- Purpose: receive natural-language commands on Linux/Windows, suggest safe shell commands via Google Gemini API, optionally execute them, and log history.

##### File structure
- Top‐level files:
- pain-x.py – the CLI entry‐point (handles user I/O, mode selection)
- suggester.py – core logic for building prompts, calling Gemini, risk assessment, formatting suggestions
- .env – configuration file for GEMINI_API_KEY (dotenv)
- history.log – persistent command history log
- README.md – documentation
- No separate frontend/backend dirs – it’s a single‐process CLI tool with distinct internal modules.

##### README for additional insights
- External dependency: Google Gemini API
- Features: quick vs interactive modes, risk checking, clipboard integration, logging
- Cross‐platform support implies abstraction over OS shell execution.

1. CLI Interface (pain-x.py)
2. Suggestion Engine (suggester.py)
3. Risk Assessment module (part of suggester.py)
4. Execution Module (shell runner / subprocess calls)
5. Logger (history.log writer)
6. Config Manager (.env reader via python-dotenv)
7. Clipboard Integrator (xclip on Linux / Windows clipboard API)
8. External AI Service (Google Gemini API)

- User → CLI Interface
- CLI Interface → Config Manager (load API key)
- CLI Interface → Suggestion Engine (pass user input + mode)
- Suggestion Engine ↔ Google Gemini API (send prompt, receive suggestions)
- Suggestion Engine → Risk Assessment module → annotate suggestions
- CLI Interface → Execution Module (if quick mode or user confirms interactive suggestion)
- Execution Module → OS Shell
- Execution Module → Logger (append to history.log)
- CLI Interface → Clipboard Integrator (on copy command)
- All modules → Log successes/errors to history.log

c. Architectural patterns & design principles:
- Modular single-process architecture
- Separation of concerns: I/O (CLI) vs AI logic vs execution vs logging
- Dependency injection for API key and OS calls
- Pluggable modes (quick vs interactive)

d. Key technologies/frameworks:
- Python 3
- python-dotenv (.env)
- Google Gemini API (1.5 Flash)
- subprocess (shell execution)
- xclip / OS clipboard APIs
- File I/O for history.log

## Diagram (Mermaid)

```mermaid
graph TB
    %% External User
    User("User"):::external

    %% Local Modules
    CLI["CLI Interface\n(pain-x.py)"]:::local
    EXE["Execution Module\n(pain-x.py)"]:::local

    subgraph "Suggestion Engine Module"
        SE["Suggestion Engine\n(suggester.py)"]:::local
        RA["Risk Assessment Module\n(suggester.py)"]:::local
    end

    %% Configuration & Storage
    CFG["Config Manager\n(.env)"]:::config
    LOG[(history.log)]:::config

    %% External Services
    AI["Google Gemini API"]:::external
    SHELL["OS Shell"]:::external
    CB["Clipboard Integrator"]:::external

    %% Flows
    User -->|"enter command"| CLI
    CLI -->|"load API key"| CFG
    CLI -->|"pass input & mode"| SE
    CFG -->|"provides API key"| SE

    SE -->|"send prompt"| AI
    AI -->|"return suggestions"| SE
    SE -->|"annotate suggestions"| RA
    RA -->|"return annotated suggestions"| SE
    SE -->|"return suggestions"| CLI
    SE -->|"log errors"| LOG

    CLI -->|"execute command"| EXE
    EXE -->|"run command"| SHELL
    EXE -->|"append log"| LOG

    CLI -->|"copy to clipboard"| CB
    CLI -->|"log success/error"| LOG

    %% Click Events
    click CLI "https://github.com/404cisco/pain-x/blob/main/pain-x.py"
    click SE "https://github.com/404cisco/pain-x/blob/main/suggester.py"
    click RA "https://github.com/404cisco/pain-x/blob/main/suggester.py"
    click EXE "https://github.com/404cisco/pain-x/blob/main/pain-x.py"
    click CFG "https://github.com/404cisco/pain-x/blob/main/.env"
    click LOG "https://github.com/404cisco/pain-x/blob/main/history.log"
    click SE "https://github.com/404cisco/pain-x/blob/main/suggester.py"

    %% Styles
    classDef local fill:#D0E8FF,stroke:#0366D6,color:#000;
    classDef external fill:#D0FFD0,stroke:#28A745,color:#000;
    classDef config fill:#FFF4C1,stroke:#DBAB09,color:#000;
```
