# rahul-02825/aegis architecture

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

- Interactive diagram: https://gitdiagram.com/rahul-02825/aegis
- Repository: https://github.com/rahul-02825/aegis

## Overview

Aegis (PrismX) is a Go reverse proxy/API gateway. At startup, its entry point connects to MongoDB, loads a configuration document into a concurrent in-memory runtime shape, initializes per-upstream consistent-hash balancers, and starts the management API and proxy. Proxy requests select an upstream by the first path segment, choose a backend using the client address, and are forwarded there. The separate management API handles config and user records; config updates reload runtime config. The README describes a standalone rate limiter, but it is not wired into the proxy. Relationships reflect shown source and README documentation; the limiter’s independence is documented.

Main entry points: [`main.go`](https://github.com/rahul-02825/aegis/blob/main/main.go) (Application startup), [`proxy/reverse_proxy.go`](https://github.com/rahul-02825/aegis/blob/main/proxy/reverse_proxy.go) (Reverse proxy), [`internal/controller/controller.go`](https://github.com/rahul-02825/aegis/blob/main/internal/controller/controller.go) (Config handlers), [`config/configHandler.go`](https://github.com/rahul-02825/aegis/blob/main/config/configHandler.go) (Runtime config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and runtime config"]
  node_main["Application startup<br/>[main.go]"]
  node_runtime_config["Runtime config<br/>[configHandler.go]"]
end

subgraph group_routing["Proxy and load balancing"]
  node_proxy["Reverse proxy<br/>[reverse_proxy.go]"]
  node_balancer_registry["Balancer registry<br/>[start.go]"]
  node_balancer_factory["Balancer factory<br/>[balancer.go]"]
  node_hash_ring["Consistent hash ring"]
end

subgraph group_management["Management API"]
  node_config_handlers["Config handlers<br/>[controller.go]"]
  node_user_handlers["User handlers<br/>[usercontroller.go]"]
  node_request_helpers["Controller helpers<br/>[helper.go]"]
end

subgraph group_storage["Persistence and support"]
  node_models["API and DB models<br/>[models.go]"]
  node_mongo_access[("Mongo collections<br/>[db.go]")]
  node_logger["Application logger<br/>[logger.go]"]
  node_rate_limiter["Standalone rate limiter<br/>[limiter.go]"]
end

node_operator(("API client"))
node_proxy_client(("Proxy client"))
node_upstreams(("Backend services"))
node_mongodb[("MongoDB")]

node_main -->|"initializes"| node_logger
node_main -->|"connects"| node_mongo_access
node_main -->|"loads config"| node_runtime_config
node_runtime_config -->|"reads config"| node_mongo_access
node_mongo_access -->|"connects collections"| node_mongodb
node_main -->|"initializes"| node_balancer_registry
node_balancer_registry -->|"reads upstreams"| node_runtime_config
node_balancer_registry -->|"creates balancer"| node_balancer_factory
node_balancer_factory -->|"builds"| node_hash_ring
node_main -->|"registers routes"| node_config_handlers
node_main -->|"registers routes"| node_user_handlers
node_operator -->|"manages configs"| node_config_handlers
node_operator -->|"manages users"| node_user_handlers
node_config_handlers -->|"updates configs"| node_mongo_access
node_config_handlers -->|"reloads config"| node_runtime_config
node_user_handlers -->|"reads and writes"| node_mongo_access
node_config_handlers -->|"decodes config"| node_models
node_user_handlers -->|"decodes user"| node_models
node_main -->|"starts proxy"| node_proxy
node_proxy_client -->|"sends requests"| node_proxy
node_proxy -->|"checks service"| node_runtime_config
node_proxy -->|"gets balancer"| node_balancer_registry
node_proxy -->|"selects backend"| node_hash_ring
node_proxy -->|"forwards request"| node_upstreams

click node_main "https://github.com/rahul-02825/aegis/blob/main/main.go"
click node_runtime_config "https://github.com/rahul-02825/aegis/blob/main/config/configHandler.go"
click node_proxy "https://github.com/rahul-02825/aegis/blob/main/proxy/reverse_proxy.go"
click node_balancer_registry "https://github.com/rahul-02825/aegis/blob/main/loadBalancer/start.go"
click node_balancer_factory "https://github.com/rahul-02825/aegis/blob/main/loadBalancer/balancer.go"
click node_hash_ring "https://github.com/rahul-02825/aegis/blob/main/loadBalancer/consistent_hasher.go"
click node_config_handlers "https://github.com/rahul-02825/aegis/blob/main/internal/controller/controller.go"
click node_user_handlers "https://github.com/rahul-02825/aegis/blob/main/internal/controller/usercontroller.go"
click node_request_helpers "https://github.com/rahul-02825/aegis/blob/main/internal/controller/helper.go"
click node_models "https://github.com/rahul-02825/aegis/blob/main/internal/models/models.go"
click node_mongo_access "https://github.com/rahul-02825/aegis/blob/main/internal/database/db.go"
click node_logger "https://github.com/rahul-02825/aegis/blob/main/logger/logger.go"
click node_rate_limiter "https://github.com/rahul-02825/aegis/blob/main/security/limiter.go"

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_main,node_runtime_config,node_operator,node_proxy_client toneBlue
class node_proxy,node_balancer_registry,node_balancer_factory,node_hash_ring,node_mongodb toneAmber
class node_config_handlers,node_user_handlers,node_request_helpers toneMint
class node_models,node_mongo_access,node_logger,node_rate_limiter toneRose
class node_upstreams toneIndigo
```

## Components

### Startup and runtime config

- [Application startup](https://github.com/rahul-02825/aegis/blob/main/main.go): `main.go`
- [Runtime config](https://github.com/rahul-02825/aegis/blob/main/config/configHandler.go): `config/configHandler.go`

### Proxy and load balancing

- [Reverse proxy](https://github.com/rahul-02825/aegis/blob/main/proxy/reverse_proxy.go): `proxy/reverse_proxy.go`
- [Balancer registry](https://github.com/rahul-02825/aegis/blob/main/loadBalancer/start.go): `loadBalancer/start.go`
- [Balancer factory](https://github.com/rahul-02825/aegis/blob/main/loadBalancer/balancer.go): `loadBalancer/balancer.go`
- [Consistent hash ring](https://github.com/rahul-02825/aegis/blob/main/loadBalancer/consistent_hasher.go): `loadBalancer/consistent_hasher.go`

### Management API

- [Config handlers](https://github.com/rahul-02825/aegis/blob/main/internal/controller/controller.go): `internal/controller/controller.go`
- [User handlers](https://github.com/rahul-02825/aegis/blob/main/internal/controller/usercontroller.go): `internal/controller/usercontroller.go`
- [Controller helpers](https://github.com/rahul-02825/aegis/blob/main/internal/controller/helper.go): `internal/controller/helper.go`

### Persistence and support

- [API and DB models](https://github.com/rahul-02825/aegis/blob/main/internal/models/models.go): `internal/models/models.go`
- [Mongo collections](https://github.com/rahul-02825/aegis/blob/main/internal/database/db.go): `internal/database/db.go`
- [Application logger](https://github.com/rahul-02825/aegis/blob/main/logger/logger.go): `logger/logger.go`
- [Standalone rate limiter](https://github.com/rahul-02825/aegis/blob/main/security/limiter.go): `security/limiter.go`

### Other components

- **API client**
- **Proxy client**
- **Backend services**
- **MongoDB**

## Connections

- Application startup → Application logger: initializes (evidence: `main.go`)
- Application startup → Mongo collections: connects (evidence: `main.go`)
- Application startup → Runtime config: loads config (evidence: `main.go`)
- Runtime config → Mongo collections: reads config (evidence: `config/configHandler.go`)
- Mongo collections → MongoDB: connects collections (evidence: `internal/database/db.go`)
- Application startup → Balancer registry: initializes (evidence: `main.go`)
- Balancer registry → Runtime config: reads upstreams (evidence: `loadBalancer/start.go`)
- Balancer registry → Balancer factory: creates balancer (evidence: `loadBalancer/start.go`)
- Balancer factory → Consistent hash ring: builds (evidence: `loadBalancer/balancer.go`)
- Application startup → Config handlers: registers routes (evidence: `main.go`)
- Application startup → User handlers: registers routes (evidence: `main.go`)
- API client → Config handlers: manages configs (evidence: `README.md`)
- API client → User handlers: manages users (evidence: `README.md`)
- Config handlers → Mongo collections: updates configs (evidence: `internal/controller/controller.go`)
- Config handlers → Runtime config: reloads config (evidence: `internal/controller/controller.go`)
- User handlers → Mongo collections: reads and writes (evidence: `internal/controller/usercontroller.go`)
- Config handlers → API and DB models: decodes config (evidence: `internal/controller/controller.go`)
- User handlers → API and DB models: decodes user (evidence: `internal/controller/usercontroller.go`)
- Application startup → Reverse proxy: starts proxy (evidence: `main.go`)
- Proxy client → Reverse proxy: sends requests (evidence: `README.md`)
- Reverse proxy → Runtime config: checks service (evidence: `proxy/reverse_proxy.go`)
- Reverse proxy → Balancer registry: gets balancer (evidence: `proxy/reverse_proxy.go`)
- Reverse proxy → Consistent hash ring: selects backend (evidence: `README.md`)
- Reverse proxy → Backend services: forwards request (evidence: `proxy/reverse_proxy.go`)
