# tscarterjr/unsecuredapikeys-opensource architecture

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

- Interactive diagram: https://gitdiagram.com/tscarterjr/unsecuredapikeys-opensource
- Repository: https://github.com/tscarterjr/unsecuredapikeys-opensource

## Overview

##### Project type and purpose
- This is a full-stack, modular security-awareness platform (“UnsecuredAPIKeys”) combining:
- A Next.js UI for educational content and live dashboards
- A .NET 9 WebAPI backend exposing REST endpoints and SignalR hubs
- An Entity Framework Core + PostgreSQL data layer
- An extensible “Providers” library for API-key discovery/validation
- Two bots (Scraper and Verifier) for automated discovery and validation

##### File structure
- Top-level folders correspond to major components:
- UnsecuredAPIKeys.UI – Next.js frontend
- UnsecuredAPIKeys.WebAPI – .NET backend (REST + SignalR)
- UnsecuredAPIKeys.Data – EF Core DbContext, migrations, models
- UnsecuredAPIKeys.Providers – API-key provider implementations & registry
- UnsecuredAPIKeys.Bots.Scraper – Automated discovery worker
- UnsecuredAPIKeys.Bots.Verifier – Automated validation worker
- Shared configuration files (appsettings.json, .env), Dockerfile, scripts
- CI/CD, Docker Compose implied by root Dockerfile and PowerShell deploy scripts

##### README for additional insights
- Architectural patterns called out:
- Repository Pattern for data access
- Provider Pattern for pluggable validation/search
- CQRS separation (read/write via different services)
- Event-Driven real-time updates via SignalR
- Modular design for independent testing and extension
- External integrations: Discord OAuth, PayPal IPN, GitHub/GitLab/SourceGraph APIs, AI providers

a. Main components
- Frontend (Next.js UI)
- Backend API (UnsecuredAPIKeys.WebAPI)
- Data Layer (PostgreSQL + EF Core)
- Providers Library (internal assembly used by API and Bots)
- Scraper Bot (discovers keys, writes to DB)
- Verifier Bot (reads from DB, validates via providers, updates DB)
- External services: GitHub/GitLab/SourceGraph APIs, AI-provider endpoints, Discord OAuth, PayPal IPN
b. Relationships & interactions
- UI ↔ WebAPI: HTTP requests for CRUD + SignalR for live stats
- WebAPI ↔ Data Layer: EF Core DbContext for reads/writes
- WebAPI & Bots ↔ Providers Library: pluggable providers invoked for search/validation
- Bots ↔ Data Layer: Scraper writes raw key discoveries; Verifier reads raw keys and writes validation results
- WebAPI ↔ External Services:
– Search Providers for manual ad-hoc search
– Discord for OAuth and role assignments
– PayPal IPN webhook for donation tracking
- Optional: RateLimitCleanupService runs in WebAPI to purge old rate-limit logs
c. Key architectural patterns
- Modular separation (UI, API, Data, Providers, Bots)
- Provider Pattern for easy extension of new search/validation engines
- Repository Pattern via EF Core for DB abstraction
- CQRS/Event-Driven: Bots perform writes; API serves read queries and real-time push via SignalR
d. Relevant technologies/frameworks
- Next.js, React, Tailwind CSS, HeroUI, Framer Motion (UI)
- .NET 9, ASP.NET Core, SignalR, Entity Framework Core, PostgreSQL (Backend/Data)
- Docker (containerization)
- PowerShell scripts, Docker Compose for deployment
- Sentry (error tracking), GitHub Actions (CI/CD)

##### Detail
- Break out sub-components where appropriate: e.g., WebAPI’s Controllers, SignalR Hub, Services
- Providers library as a shared module or micro-library node used by multiple services
- Rate-limiting, error tracking (Sentry), and real-time features explicitly

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Interface Layer
    subgraph "User Interface" 
        UI["Next.js Frontend"]:::frontend
    end

    %% Backend Services Layer
    subgraph "Backend Services"
        API["UnsecuredAPIKeys.WebAPI"]:::backend
        subgraph "WebAPI Components"
            C["Controllers"]:::backend
            H["SignalR Hub"]:::backend
            S["Services"]:::backend
            RC["RateLimitCleanupService"]:::backend
        end
        subgraph "Configuration"
            CONF["appsettings.json & launchSettings"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["PostgreSQL"]:::data
        subgraph "EF Core"
            DBCtx["DBContext.cs"]:::data
            Factory["DesignTimeDbContextFactory.cs"]:::data
            Migs["Migrations"]:::data
            Models["Models"]:::data
        end
    end

    %% Providers Library
    subgraph "Providers Library"
        Base["BaseApiKeyProvider.cs"]:::providers
        Interfaces["_Interfaces"]:::providers
        AI["AI Providers"]:::providers
        Search["Search Providers"]:::providers
        Registry["ApiProviderRegistry.cs"]:::providers
        PServices["Provider Services"]:::providers
    end

    %% Bots Layer
    subgraph "Bots"
        subgraph "Scraper Bot"
            Scraper["Scraper_Program.cs"]:::bots
        end
        subgraph "Verifier Bot"
            Verifier["Verifier_Program.cs"]:::bots
            VServices["Verifier Services"]:::bots
        end
    end

    %% External Services
    GitHub["GitHub/GitLab/SourceGraph APIs"]:::external
    AIEx["External AI Endpoints"]:::external
    Discord["Discord OAuth"]:::external
    PayPal["PayPal IPN"]:::external
    Sentry["Sentry"]:::external

    %% Interactions
    UI -->|"HTTP & SignalR"| C
    C -->|uses| DBCtx
    C -->|invokes| Registry
    H -->|"real-time"| UI
    S -->|cleanup| RC
    API -->|reads/writes| DB
    API -->|loads| CONF
    API -->|calls| GitHub
    API -->|calls| Discord
    API -->|receives| PayPal
    API -->|reports errors to| Sentry
    API -->|uses| PServices
    Scraper -->|writes discoveries| DB
    Scraper -->|uses| Search
    Verifier -->|reads raw keys| DB
    Verifier -->|uses| AI
    Verifier -->|writes results| DB
    Verifier -->|reports errors to| Sentry

    %% Click Events
    click UI "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.UI"
    click API "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.WebAPI"
    click C "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.WebAPI/Controllers"
    click H "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.WebAPI/Hubs/StatsHub.cs"
    click S "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.WebAPI/Services"
    click DBCtx "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.Data/DBContext.cs"
    click Factory "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.Data/DesignTimeDbContextFactory.cs"
    click Migs "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Data/Migrations"
    click Models "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Data/Models"
    click Base "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.Providers/_Base/BaseApiKeyProvider.cs"
    click Interfaces "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Providers/_Interfaces"
    click AI "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Providers/AI Providers"
    click Search "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Providers/Search Providers"
    click Registry "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.Providers/ApiProviderRegistry.cs"
    click PServices "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Providers/Services"
    click Scraper "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.Bots.Scraper/Scraper_Program.cs"
    click Verifier "https://github.com/tscarterjr/unsecuredapikeys-opensource/blob/main/UnsecuredAPIKeys.Bots.Verifier/Verifier_Program.cs"
    click VServices "https://github.com/tscarterjr/unsecuredapikeys-opensource/tree/main/UnsecuredAPIKeys.Bots.Verifier/Services"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:1px
    classDef backend fill:#bbf,stroke:#333,stroke-width:1px
    classDef data fill:#bfb,stroke:#333,stroke-width:1px
    classDef providers fill:#fbf,stroke:#333,stroke-width:1px
    classDef bots fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
