# loumonthjack/limit-guardian architecture

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

- Interactive diagram: https://gitdiagram.com/loumonthjack/limit-guardian
- Repository: https://github.com/loumonthjack/limit-guardian

## Overview

##### Project Type and Purpose
- The README makes it clear that this is a specialized, open-source library meant for rate limit monitoring and management across APIs.
- It supports both real-time monitoring (via a GraphQL API) and direct command-line usage (CLI tools) while integrating background processing (via BullMQ and Bull Board) and email notifications for alerts.
- The project also uses Prisma as an ORM for its database layer (SQLite by default), indicating a data persistence component.

##### File Structure
- Top-Level Files: The presence of package.json, tsconfig.json, and various configuration files shows this is a TypeScript project with standard dependency management.
- Directories:
- /src: Contains the core application code. Within it:
▫ The “graphql” subdirectory holds resolvers, types, and the GraphQL schema – indicating a dedicated API module.
▫ The “interfaces” folder suggests a clear separation of concerns with defined contracts for CLI, server, and worker-related interactions.
▫ “services” contains helper functions such as the email service, marking specific business logic.
- /prisma: Holds the Prisma schema, migrations, and seed scripts, which define the data models and database initialization (using SQLite in development).
- Other Files: CLI commands are invoked via npm scripts (as described in the README) and a worker UI is available (leveraging Bull Board).

##### Main Components
a. Guardian Core Module:
- This is the central component instantiated and managed through Guardian.getInstance().
- Responsible for rate limit checking, usage tracking, and enforcing policies.
b. CLI Interface:
- Command-line commands for viewing and updating services, enabling/disabling limits, and updating usage.
- Interfaces with the Guardian core to provide administrative controls.
c. GraphQL API:
- Provides integration capabilities with external systems.
- Includes schema definitions (located in src/graphql/schema.graphql) and resolvers (src/graphql/resolvers.ts).
d. Database Layer:
- Managed by Prisma, with migrations and seed data (e.g., prisma/data/dev.db).
- Acts as persistent storage for API usage data and rate limit configurations.
e. Worker/Background Processing Service:
- Likely implemented using BullMQ for job queuing and managed via Bull Board for UI-based monitoring (accessible through npm run worker-ui).
- Processes background tasks such as sending email notifications when a rate limit is exceeded.
f. Email Notification Service:
- Located in src/services/email.ts, sends alerts as configured in the Guardian logic.
g. External Dependencies:
- Technologies such as Redis (for BullMQ), Bull Board (for UI monitoring), and potentially Express (for running the GraphQL server) should be represented.

##### Relationships and Data Flow
- The Guardian core communicates with the Database Layer (via Prisma) to record and query API usage data.
- When rate limits are violated, the Guardian core triggers the Email Notification Service.
- The Worker Service retrieves jobs from a Redis-backed BullMQ queue; indicate a data flow from the core to the queue and then to the Bull Board monitoring UI.
- External API calls might be “wrapped” by the Guardian’s protect function, forming a feedback loop back into the monitoring system.

##### Architectural Patterns and Key Technologies
- Modularity: The design is decoupled; distinct directories and interfaces ensure that each component (CLI, GraphQL, background workers) is loosely coupled with the Guardian core.
- Layered Architecture: The project separates presentation layers (CLI, GraphQL API) from business logic (Guardian core and services), with an underlying data access layer (Prisma with SQLite).
- Use of industry-standard libraries: BullMQ for job processing, Prisma for ORM, and GraphQL for API definitions are critical and should be clearly noted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Interfaces"
        CLI["CLI Interface"]:::interface
        subgraph "GraphQL API"
            GS["GraphQL Schema"]:::api
            GR["GraphQL Resolvers"]:::api
        end
    end

    GC["Guardian Core"]:::core

    subgraph "Database Layer"
        PS["Prisma Schema"]:::database
        DB["SQLite Database"]:::database
    end

    ES["Email Notification Service"]:::service

    WQ["BullMQ Queue (Redis)"]:::external

    subgraph "Worker Service"
        WP["Worker Processor"]:::worker
        WUI["Bull Board UI"]:::worker
    end

    %% Connections from Interfaces to Core
    CLI -->|"interacts"| GC
    GS -->|"calls"| GC
    GR -->|"calls"| GC

    %% Guardian Core interactions
    GC -->|"writes"| PS
    PS -->|"persists"| DB
    GC -->|"triggers"| ES
    GC -->|"queues"| WQ

    %% Worker Queue connections
    WQ -->|"processes"| WP
    WQ -->|"monitors"| WUI

    %% Click Events
    click GC "https://github.com/loumonthjack/limit-guardian/blob/main/src/model.ts"
    click CLI "https://github.com/loumonthjack/limit-guardian/blob/main/src/interfaces/cli.ts"
    click GS "https://github.com/loumonthjack/limit-guardian/blob/main/src/graphql/schema.graphql"
    click GR "https://github.com/loumonthjack/limit-guardian/blob/main/src/graphql/resolvers.ts"
    click PS "https://github.com/loumonthjack/limit-guardian/blob/main/prisma/schema.prisma"
    click DB "https://github.com/loumonthjack/limit-guardian/blob/main/prisma/data/dev.db"
    click WP "https://github.com/loumonthjack/limit-guardian/blob/main/src/interfaces/worker.ts"
    click WUI "https://github.com/loumonthjack/limit-guardian/blob/main/src/interfaces/worker-ui.ts"
    click ES "https://github.com/loumonthjack/limit-guardian/blob/main/src/services/email.ts"

    %% Styles
    classDef interface fill:#bbf,stroke:#333,stroke-width:2px;
    classDef api fill:#cfc,stroke:#333,stroke-width:2px;
    classDef core fill:#f96,stroke:#333,stroke-width:2px;
    classDef database fill:#fcc,stroke:#333,stroke-width:2px;
    classDef service fill:#cff,stroke:#333,stroke-width:2px;
    classDef worker fill:#fcf,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px;
```
