# michniks2001/code-coffee-hack architecture

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

- Interactive diagram: https://gitdiagram.com/michniks2001/code-coffee-hack
- Repository: https://github.com/michniks2001/code-coffee-hack

## Overview

##### Project type and purpose
- APIPort is a standalone, Python-based command-line interface (CLI) tool for securely managing API secrets. It provides commands to add, list, update, delete, and import secrets, with optional AI-powered parsing.

##### File structure
- Top-level scripts and entry points:
- __main__.py, apiport.py and commands.py – CLI launchers
- setup.py / pyproject.toml – packaging & entry-point definitions
- Package directory `apiport/`:
- cli.py – argument parsing & dispatch
- commands.py – implementation of add, list, update, delete, import
- encryption.py – Fernet symmetric encryption key management
- storage.py – vault file I/O (read/write encrypted data)
- Support files:
- apis.txt – sample input format
- requirements.txt – dependencies
- CI/CD: .github/workflows/python-publish.yml

##### README for additional insights
- Core features: secure storage, file-based bulk import, AI parsing (optional), .env integration
- Security: uses Fernet, key stored at `~/.apiport_key`, vault at `~/.apiport/vault.port`
- External dependency (optional): Google Gemini API

##### Main components and their interactions
a. Components:
- User (CLI user)
- CLI Entry Point (`apiport` script → __main__.py)
- Argument Parser & Dispatcher (cli.py)
- Command Handlers (commands.py)
- Encryption Engine (encryption.py)
- Storage Engine (storage.py, local filesystem vault)
- .env Importer (commands.py + file I/O)
- AI Parser Module (optional, in commands.py)
- External AI Service (Google Gemini API)
b. Relationships & Data Flows:
1. User types `apiport <command> [options]`
2. Entry Point loads cli.py, which parses args and invokes the correct handler in commands.py
3. Command handler formats secret data, calls Encryption Engine to encrypt/decrypt
4. Encrypted blobs are passed to Storage Engine, which reads/writes `vault.port` on disk
5. For imports to `.env`, handler reads the vault, decrypts, and writes to the .env file
6. If AI parsing is enabled, handler sends raw text to the AI Parser Module, which calls Google Gemini API, receives parsed secrets, then continues the normal encryption/storage flow
c. Architectural Patterns:
- Modular layering: CLI → Command Handlers → Domain Services (Encryption, Storage)
- Separation of concerns: crypto isolated, I/O isolated, business logic in commands
- Optional extension point: AI parsing as a pluggable service
d. Key Technologies & Libraries:
- Python standard library: argparse, pathlib
- cryptography.Fernet
- Click or custom CLI (depending on cli.py implementation)
- Gemini API client (optional, requires external credentials)

##### Detail
- Config locations (e.g., `~/.apiport_key`, `~/.apiport/vault.port`)
- Packaging & entry points as a side note (setup.py → console_scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Packaging & Entry-Point Definitions
    subgraph "Packaging"
        SP["setup.py"]:::core
        PJ["pyproject.toml"]:::core
    end

    %% Entry Points
    subgraph "CLI Entry Points"
        ME["__main__.py"]:::frontend
        AP["apiport.py"]:::frontend
    end

    %% Core Layers
    User["User"]:::frontend
    User -->|"apiport <command> [options]"| ME
    User -->|"apiport <command> [options]"| AP

    ME -->|"loads cli.py"| CP["cli.py"]:::frontend
    AP -->|"loads cli.py"| CP

    CP -->|"dispatch command"| CH["commands.py"]:::frontend

    %% Services
    CH -->|"plaintext secret"| EN["encryption.py"]:::core
    CH -->|"invoke storage"| ST["storage.py"]:::core
    CH -->|"decrypt & write"| ENVIMPORT[".env Importer"]:::core
    CH -->|"optional parsing"| AIP["AI Parser Module"]:::optional

    EN -->|"manage key"| KEY["~/.apiport_key"]:::storage
    EN -->|"encrypted blob"| ST

    ST -->|"read/write vault"| VAULT["~/.apiport/vault.port"]:::storage
    ENVIMPORT -->|"writes"| DOTENV[".env file"]:::storage

    AIP -->|"API call"| EXT["Google Gemini API"]:::external
    EXT -->|"parsed secrets"| CH

    %% Support Files
    subgraph "Support Files"
        APITXT["apis.txt"]:::storage
        REQ["requirements.txt"]:::storage
        CI["python-publish.yml"]:::storage
    end

    %% Click Events
    click ME "https://github.com/michniks2001/code-coffee-hack/blob/main/__main__.py"
    click AP "https://github.com/michniks2001/code-coffee-hack/blob/main/apiport.py"
    click SP "https://github.com/michniks2001/code-coffee-hack/blob/main/setup.py"
    click PJ "https://github.com/michniks2001/code-coffee-hack/blob/main/pyproject.toml"
    click CP "https://github.com/michniks2001/code-coffee-hack/blob/main/apiport/cli.py"
    click CH "https://github.com/michniks2001/code-coffee-hack/blob/main/apiport/commands.py"
    click EN "https://github.com/michniks2001/code-coffee-hack/blob/main/apiport/encryption.py"
    click ST "https://github.com/michniks2001/code-coffee-hack/blob/main/apiport/storage.py"
    click APITXT "https://github.com/michniks2001/code-coffee-hack/blob/main/apis.txt"
    click REQ "https://github.com/michniks2001/code-coffee-hack/blob/main/requirements.txt"
    click CI "https://github.com/michniks2001/code-coffee-hack/blob/main/.github/workflows/python-publish.yml"

    %% Styles
    classDef frontend fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef optional fill:#FFD700,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFEB99,stroke:#333,stroke-width:1px
```
