# mynamegabe/sad architecture

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

- Interactive diagram: https://gitdiagram.com/mynamegabe/sad
- Repository: https://github.com/mynamegabe/sad

## Overview

##### Main Components
- Frontend Client: Located in the “frontend” directory, it is built using a modern JavaScript/TypeScript framework (likely React with Vite due to the presence of “vite.config.ts” and “App.tsx”). It handles the user interface and interacts with the backend through API calls.
- Backend API Service: Located in the “backend” directory, this Python-based service includes multiple components:
– The entry point (main.py) that initializes the API service.
– Routers (in “routers” folder for auth, users, and webhooks) that expose REST or webhook endpoints.
– Modules (e.g., gemini.py and github.py) that handle integration logic with external systems.
– Utility functions and database connectivity (in “utils” and “schemas.py”) that aid the overall application logic.
- Containerized Sandbox Environment: Under “backend/sandbox/benchmarker” and related subdirectories, there is a set of containerized tools (using Dockerfiles) for tasks like benchmarking, entropy scanning, and Yara scanning. These containers are likely responsible for scanning files or code for potential supply chain attacks.
- External Integrations and Services:
– GitHub Integration: Configured with a dedicated router (e.g., “webhooks/github”) and module (backend/modules/github.py), indicating that there is support for GitHub webhooks and possibly other GitHub API operations.
– Yara Scanner: A clearly segregated component that uses Yara rules (organized in “yara-rules-src” and “yara-rules”) to detect suspicious patterns, supplemented by additional components (like “yara_updater.py” and “yara_compiler.py”) for scanning and maintaining up-to-date rules.
- Database: Though not directly visible in the file tree, the README and the sample “config.py” inform us that the backend connects to a database (with details such as DB_HOST, DB_USERNAME, etc.). This is most likely a containerized database service set up via docker-compose.

##### Relationships and Data Flow
- The Frontend makes API calls to the Backend to display and update data related to supply chain security events.
- The Backend receives requests via various routers (authentication, user management, webhook processing). In particular, GitHub webhooks allow external notifications into the system.
- The Backend then interacts with the Database to store and retrieve information (using helper modules in “utils/db.py” and related files).
- For threat detection, the backend triggers scanning jobs in the sandbox environment (the containerized benchmarker and Yara scanner). Data flows from file uploads or code submissions into these scanning modules.
- Results from the sandbox scanners are processed and likely relayed back to the user via the Backend API and then the Frontend.
- External API keys and secrets (configured in “config.py”) manage integration with external services like MakerSuite or GitHub for extended functionalities.

##### Architectural Patterns and Technologies
- Separation of Concerns: Clear separation between frontend, backend API, scanning sandbox environment, and database.
- Containerization: The use of Docker for the sandbox scanning components (Dockerfiles in benchmarker/yara-scanner) and docker-compose for orchestrating the database (and possibly backend services).
- Modular Design: Backend modules and routers separate responsibilities (e.g., authentication, GitHub/webhook integrations).
- Integration with Third-Party Services: The design considers integration with external platforms (e.g., GitHub and possibly a MakerSuite API) with proper configurations.

##### Components
- Frontend Component:
- Backend API Service:
– Sub-components: “Routers (auth, users, webhooks)”, “Modules (gemini, GitHub)”, “Utilities (db, common)”.
- Containerized Sandbox:
– Label distinctly, e.g., “Sandbox Scanning Service” with a sub-section for “Yara Scanner” and “Entropy Scan”.
- Database:
- External Services:
– Include a representation for “GitHub Integration” and any additional API services shown in config.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (React/Vite)"
        FE1["App.tsx"]:::frontend
        FE2["vite.config.ts"]:::frontend
        FE3["GitHub Callback Route"]:::frontend
    end

    subgraph "Backend API"
        BE1["main.py"]:::backend
        BE2["Routers (auth,users,webhooks)"]:::backend
        BE3A["Gemini Module"]:::backend
        BE3B["GitHub Module"]:::backend
        BE4["Schemas (schemas.py)"]:::backend
        BE5A["Utility: db.py"]:::backend
        BE5B["Utility: common.py"]:::backend
    end

    subgraph "Sandbox Scanning Service"
        SS1["Benchmarker & Container Tools"]:::sandbox
        SS2["Yara Scanner"]:::sandbox
        SS3["Entropy Scan"]:::sandbox
    end

    DB["Database"]:::database
    EX["GitHub Integration"]:::external

    %% Connections
    FE1 -->|"RESTAPICall"| BE1
    EX -->|"Webhook"| BE2
    BE1 -->|"DBQuery"| DB
    BE1 -->|"TriggerScan"| SS1
    SS2 -->|"ScanResults"| BE1
    SS3 -->|"ScanResults"| BE1
    BE3B -->|"GitHubData"| EX

    %% Click Events
    click FE1 "https://github.com/mynamegabe/sad/blob/main/frontend/src/App.tsx"
    click FE2 "https://github.com/mynamegabe/sad/blob/main/frontend/vite.config.ts"
    click FE3 "https://github.com/mynamegabe/sad/tree/main/frontend/src/routes/github"
    click BE1 "https://github.com/mynamegabe/sad/blob/main/backend/main.py"
    click BE2 "https://github.com/mynamegabe/sad/tree/main/backend/routers/"
    click BE3A "https://github.com/mynamegabe/sad/blob/main/backend/modules/gemini.py"
    click BE3B "https://github.com/mynamegabe/sad/blob/main/backend/modules/github.py"
    click BE5A "https://github.com/mynamegabe/sad/blob/main/backend/utils/db.py"
    click BE5B "https://github.com/mynamegabe/sad/blob/main/backend/utils/common.py"
    click SS1 "https://github.com/mynamegabe/sad/tree/main/backend/sandbox/benchmarker/"
    click SS2 "https://github.com/mynamegabe/sad/tree/main/backend/sandbox/benchmarker/yara-scanner/"
    click EX "https://github.com/mynamegabe/sad/blob/main/backend/routers/webhooks.py"
    click DB "https://github.com/mynamegabe/sad/blob/main/backend/schemas.py"

    %% Styles
    classDef frontend fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef backend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef sandbox fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef database fill:#FAD7A0,stroke:#7D6608,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
