# cado-security/masked-ai architecture

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

- Interactive diagram: https://gitdiagram.com/cado-security/masked-ai
- Repository: https://github.com/cado-security/masked-ai

## Overview

##### Project type and purpose
- From the README and file tree, we see that Masked-AI is a Python SDK plus a CLI wrapper. Its job is to “mask” sensitive data in user inputs, forward the redacted request to an LLM API (e.g., OpenAI), then “unmask” the API’s response so the user sees their original data. It’s not a microservice or web app; it’s a standalone CLI tool backed by a Python library.

##### File structure
- Top-level directories:
- masked_ai/        ← core library code
– core/masks.py   ← mask definitions (IP, email, credit-card, etc.)
– masker.py       ← orchestrates masking, API execution, unmasking
- tests/            ← unit tests for masks and CLI functionality
- ci/, .github/     ← CI linting, type checks, GitHub Actions (app-ci.yml, publish.yml)
- release/          ← scripts to build binaries and upload to PyPI
- setup.py, requirements.txt, setup.cfg ← packaging & dependencies
- No webserver, no database directories: this is a library + CLI that invokes an external API.

##### README for additional insights
- It calls out core classes (“MaskBase”, IPMask, EmailMask, etc.) and shows example usage of the Masker class.

a. Components:
1) CLI Frontend (“masker” executable)
2) Masker Library
– Mask Engine (core/masks.py)
– Masker Orchestrator (masked_ai/masker.py)
3) External LLM API (OpenAI/GPT-4/etc.)
4) Packaging & Distribution (PyPI, release scripts)
5) CI/CD Pipeline (GitHub Actions, flake8, mypy)
6) Tests (pytest)
b. Relationships / Data Flow:
- User types a command or invokes Python SDK →
- CLI Frontend calls Masker Orchestrator →
- Orchestrator runs each Mask class to transform raw input →
- Sends masked payload to External LLM API over HTTPS →
- Receives API JSON response →
- Orchestrator calls unmask routines to re-insert sensitive data →
- Returns final output to user
c. Architectural patterns / design principles:
- Strategy pattern for masks (MaskBase subclasses)
- Single responsibility: each mask handles only one data type
- Plug-in architecture: new masks auto-discovered by inheritance
- Thin orchestration layer – no persistent storage
- CLI + library co-exist in same package
d. Key technologies / libraries:
- Python 3.x
- re (regex) for mask detection
- Click or argparse (implicitly used in masker.py for CLI)
- HTTP client (curl or requests in examples)
- pytest for tests
- GitHub Actions for CI/CD
- PyPI packaging via setup.py / setup.cfg

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external
    User -->|"invokes CLI"| CLI

    %% Core Library Cluster
    subgraph "Core Library" 
        direction TB
        CoreLib["Core Library\n(masked_ai/)"]:::library
        CLI["CLI Frontend\n(masker executable)"]:::library
        Orchestrator["Masker Orchestrator"]:::library
        MaskEngine["Mask Engine\n(IPMask, EmailMask, etc.)"]:::library
    end

    %% External API
    API["External LLM API\n(OpenAI/GPT)"]:::external

    %% Processes Flow
    CLI -->|"calls"| Orchestrator
    Orchestrator -->|"uses"| MaskEngine
    Orchestrator -->|"sends masked payload\n(HTTPS/JSON)"| API
    API -->|"returns response\n(HTTPS/JSON)"| Orchestrator
    Orchestrator -->|"outputs unmasked result"| CLI
    CLI -->|"displays output"| User

    %% Tests
    subgraph "Tests" 
        direction TB
        TestsMasks["Masks Tests"]:::tests
        TestsMasker["Masker Tests"]:::tests
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        Workflow1["GitHub Actions CI"]:::ci
        Workflow2["GitHub Actions Publish"]:::ci
        Flake["Flake8 Config"]:::ci
        Mypy["Mypy Config"]:::ci
    end

    %% Packaging & Distribution
    subgraph "Packaging & Distribution"
        direction TB
        SetupPy["setup.py"]:::pack
        SetupCfg["setup.cfg"]:::pack
        Req["requirements.txt"]:::pack
        Lin["generate_linux_binary.sh"]:::pack
        OSX["generate_osx_binary.sh"]:::pack
        Win["generate_windows_binary.bat"]:::pack
        Upload["upload_pip.sh"]:::pack
        Docs["Flow Diagram"]:::pack
    end

    %% CI/CD to Packaging Relationship
    Workflow2 -->|"publishes package"| SetupPy

    %% Click Events
    click CoreLib "https://github.com/cado-security/masked-ai/tree/main/masked_ai/"
    click CLI "https://github.com/cado-security/masked-ai/blob/main/masked_ai/masker.py"
    click Orchestrator "https://github.com/cado-security/masked-ai/blob/main/masked_ai/masker.py"
    click MaskEngine "https://github.com/cado-security/masked-ai/blob/main/masked_ai/core/masks.py"
    click TestsMasks "https://github.com/cado-security/masked-ai/blob/main/tests/test_core/test_masks.py"
    click TestsMasker "https://github.com/cado-security/masked-ai/blob/main/tests/test_masker.py"
    click Workflow1 "https://github.com/cado-security/masked-ai/blob/main/.github/workflows/app-ci.yml"
    click Workflow2 "https://github.com/cado-security/masked-ai/blob/main/.github/workflows/publish.yml"
    click Flake "https://github.com/cado-security/masked-ai/blob/main/ci/flake8.cfg"
    click Mypy "https://github.com/cado-security/masked-ai/blob/main/ci/mypy.cfg"
    click SetupPy "https://github.com/cado-security/masked-ai/blob/main/setup.py"
    click SetupCfg "https://github.com/cado-security/masked-ai/blob/main/setup.cfg"
    click Req "https://github.com/cado-security/masked-ai/blob/main/requirements.txt"
    click Lin "https://github.com/cado-security/masked-ai/blob/main/release/generate_linux_binary.sh"
    click OSX "https://github.com/cado-security/masked-ai/blob/main/release/generate_osx_binary.sh"
    click Win "https://github.com/cado-security/masked-ai/blob/main/release/generate_windows_binary.bat"
    click Upload "https://github.com/cado-security/masked-ai/blob/main/release/upload_pip.sh"
    click Docs "https://github.com/cado-security/masked-ai/blob/main/docs/flow2.png"

    %% Styles
    classDef library fill:#D0E8FF,stroke:#0366d6;
    classDef external fill:#b3ffb3,stroke:#228B22;
    classDef ci fill:#FFE5B4,stroke:#FF8C00;
    classDef tests fill:#E0E0E0,stroke:#666666;
    classDef pack fill:#E8E0FF,stroke:#800080;
    classDef user fill:#ffffff,stroke:#000000;
```
