# niranjan123-k/rateguard architecture

> Architecture diagram of the GitHub repository niranjan123-k/rateguard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niranjan123-k/rateguard
- Repository: https://github.com/niranjan123-k/rateguard

## Overview

RateGuard is a Spring Boot rate-limiting API with a React monitoring dashboard. A client calls an annotated endpoint; the AOP aspect applies a per-IP fixed-window limit, records allowed or blocked events, and lets allowed calls proceed. Events are published for live monitoring and logs support history analytics. The README documents the MySQL and WebSocket capabilities; some frontend network wiring and configuration details were not excerpted, so those links rely on documented architecture rather than inspected implementation.

Main entry points: [`rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java) (Limit enforcement), [`rateguard/src/main/java/com/guard/api/controller/DemoController.java`](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/controller/DemoController.java) (Demo endpoints), [`rateguard/src/main/java/com/guard/api/repository/RequestLogRepository.java`](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/repository/RequestLogRepository.java) (Request log repository), [`frontend/src/App.jsx`](https://github.com/niranjan123-k/rateguard/blob/main/frontend/src/App.jsx) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and enforcement"]
  node_demo["Demo endpoints"]
  node_limit_annotation["Rate limit policy<br/>[RateLimit.java]"]
  node_aspect["Limit enforcement"]
  node_exception["Limit exception"]
  node_exception_handler["HTTP error mapping"]
end

subgraph group_monitoring["Monitoring and analytics"]
  node_analytics["History API"]
  node_repository["Request log repository"]
  node_request_log["Request log record<br/>[RequestLog.java]"]
  node_event["Live request event<br/>[RequestEvent.java]"]
  node_websocket["WebSocket delivery"]
  node_mysql[("MySQL")]
end

subgraph group_frontend["Dashboard"]
  node_dashboard["Dashboard UI<br/>[App.jsx]"]
  node_react_entry["React entry point<br/>[main.jsx]"]
end

node_client(("API client"))
node_user(("Dashboard user"))

node_client -->|"calls API"| node_demo
node_demo -->|"intercepted by"| node_aspect
node_demo -->|"configures"| node_limit_annotation
node_aspect -->|"reads policy"| node_limit_annotation
node_aspect -->|"proceeds to"| node_demo
node_aspect -->|"throws when blocked"| node_exception
node_exception_handler -->|"handles"| node_exception
node_aspect -->|"saves logs"| node_repository
node_repository -->|"persists entity"| node_request_log
node_repository -->|"stores logs"| node_mysql
node_analytics -->|"reads history"| node_repository
node_aspect -->|"creates event"| node_event
node_aspect -->|"publishes event"| node_websocket
node_websocket -.->|"streams updates"| node_dashboard
node_dashboard -.->|"requests history"| node_analytics
node_user -->|"opens dashboard"| node_react_entry
node_react_entry -->|"renders"| node_dashboard

click node_demo "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/controller/DemoController.java"
click node_limit_annotation "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/annotation/RateLimit.java"
click node_aspect "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java"
click node_exception "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/exception/RateLimitExceededException.java"
click node_exception_handler "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/exception/GlobalExceptionHandler.java"
click node_analytics "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/controller/AnalyticsController.java"
click node_repository "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/repository/RequestLogRepository.java"
click node_request_log "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/entity/RequestLog.java"
click node_event "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/dto/RequestEvent.java"
click node_websocket "https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/config/WebSocketConfig.java"
click node_dashboard "https://github.com/niranjan123-k/rateguard/blob/main/frontend/src/App.jsx"
click node_react_entry "https://github.com/niranjan123-k/rateguard/blob/main/frontend/src/main.jsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_demo,node_limit_annotation,node_aspect,node_exception,node_exception_handler,node_client,node_user toneBlue
class node_analytics,node_repository,node_request_log,node_event,node_websocket,node_mysql toneAmber
class node_dashboard,node_react_entry toneMint
```

## Components

### API and enforcement

- [Demo endpoints](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/controller/DemoController.java): `rateguard/src/main/java/com/guard/api/controller/DemoController.java`
- [Rate limit policy](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/annotation/RateLimit.java): `rateguard/src/main/java/com/guard/api/annotation/RateLimit.java`
- [Limit enforcement](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java): `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`
- [Limit exception](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/exception/RateLimitExceededException.java): `rateguard/src/main/java/com/guard/api/exception/RateLimitExceededException.java`
- [HTTP error mapping](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/exception/GlobalExceptionHandler.java): `rateguard/src/main/java/com/guard/api/exception/GlobalExceptionHandler.java`

### Monitoring and analytics

- [History API](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/controller/AnalyticsController.java): `rateguard/src/main/java/com/guard/api/controller/AnalyticsController.java`
- [Request log repository](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/repository/RequestLogRepository.java): `rateguard/src/main/java/com/guard/api/repository/RequestLogRepository.java`
- [Request log record](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/entity/RequestLog.java): `rateguard/src/main/java/com/guard/api/entity/RequestLog.java`
- [Live request event](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/dto/RequestEvent.java): `rateguard/src/main/java/com/guard/api/dto/RequestEvent.java`
- [WebSocket delivery](https://github.com/niranjan123-k/rateguard/blob/main/rateguard/src/main/java/com/guard/api/config/WebSocketConfig.java): `rateguard/src/main/java/com/guard/api/config/WebSocketConfig.java`
- **MySQL**

### Dashboard

- [Dashboard UI](https://github.com/niranjan123-k/rateguard/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [React entry point](https://github.com/niranjan123-k/rateguard/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`

### Other components

- **API client**
- **Dashboard user**

## Connections

- API client → Demo endpoints: calls API (evidence: `README.md`)
- Demo endpoints → Limit enforcement: intercepted by (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- Demo endpoints → Rate limit policy: configures (evidence: `rateguard/src/main/java/com/guard/api/controller/DemoController.java`)
- Limit enforcement → Rate limit policy: reads policy (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- Limit enforcement → Demo endpoints: proceeds to (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- Limit enforcement → Limit exception: throws when blocked (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- HTTP error mapping → Limit exception: handles (evidence: `rateguard/src/main/java/com/guard/api/exception/GlobalExceptionHandler.java`)
- Limit enforcement → Request log repository: saves logs (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- Request log repository → Request log record: persists entity (evidence: `rateguard/src/main/java/com/guard/api/repository/RequestLogRepository.java`)
- Request log repository → MySQL: stores logs (evidence: `README.md`)
- History API → Request log repository: reads history (evidence: `rateguard/src/main/java/com/guard/api/controller/AnalyticsController.java`)
- Limit enforcement → Live request event: creates event (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- Limit enforcement → WebSocket delivery: publishes event (evidence: `rateguard/src/main/java/com/guard/api/aspect/RateLimitAspect.java`)
- WebSocket delivery → Dashboard UI: streams updates (evidence: `README.md`)
- Dashboard UI → History API: requests history (evidence: `README.md`)
- Dashboard user → React entry point: opens dashboard (evidence: `frontend/src/main.jsx`)
- React entry point → Dashboard UI: renders (evidence: `frontend/src/main.jsx`)
