# rk936503/aegis-api architecture

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

- Interactive diagram: https://gitdiagram.com/rk936503/aegis-api
- Repository: https://github.com/rk936503/aegis-api

## Overview

Aegis API is a microservices backend whose main request path runs through a gateway for authentication, rate limiting, and downstream routing. Auth handles account and token lifecycle; user and order services handle their own domain operations and persistence. The README documents these capabilities, while the sampled source directly confirms gateway dispatch, token checks, and user/order persistence. Some unsampled wiring is therefore shown only where the README or tree supports it.

Main entry points: [`api-gateway/src/app.js`](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/app.js) (Gateway app), [`api-gateway/src/utils/circuitBreaker.js`](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/utils/circuitBreaker.js) (Circuit breakers), [`api-gateway/src/routes/authRoutes.js`](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/routes/authRoutes.js) (Auth proxy), [`auth-service/app.js`](https://github.com/rk936503/aegis-api/blob/main/auth-service/app.js) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API gateway"]
  node_gateway_app["Gateway app<br/>[app.js]"]
  node_gateway_auth["JWT validation<br/>[auth.js]"]
  node_rate_limit["Rate limiter<br/>[rateLimiter.js]"]
  node_auth_proxy["Auth proxy<br/>[authRoutes.js]"]
  node_proxy_routes["Service handlers<br/>[proxyRoutes.js]"]
  node_breaker["Circuit breakers<br/>[circuitBreaker.js]"]
  node_gateway_config["Service addresses<br/>[services.js]"]
end

subgraph group_identity["Identity"]
  node_auth_service["Auth service<br/>[app.js]"]
end

subgraph group_domains["Domain services"]
  node_user_app["User service<br/>[app.js]"]
  node_user_routes["Profile operations<br/>[userRoutes.js]"]
  node_order_app["Order service<br/>[app.js]"]
  node_order_routes["Order lifecycle<br/>[orderRoutes.js]"]
end

subgraph group_data["Persistence"]
  node_auth_db[("Auth database<br/>[schema.prisma]")]
  node_user_db[("User database<br/>[schema.prisma]")]
  node_order_db[("Order database<br/>[schema.prisma]")]
  node_redis[("Redis")]
end

subgraph group_observability["Observability"]
  node_metrics_middleware["Metrics middleware<br/>[metrics.js]"]
  node_metrics["Metrics registry<br/>[metrics.js]"]
  node_prometheus["Prometheus"]
  node_grafana["Grafana"]
end

node_caller(("API client"))

node_caller -->|"sends requests"| node_gateway_app
node_gateway_app -->|"records requests"| node_metrics_middleware
node_metrics_middleware -->|"updates metrics"| node_metrics
node_gateway_app -->|"limits requests"| node_rate_limit
node_gateway_app -->|"dispatches auth"| node_auth_proxy
node_auth_proxy -->|"reads address"| node_gateway_config
node_auth_proxy -->|"proxies requests"| node_auth_service
node_gateway_app -->|"checks protected routes"| node_gateway_auth
node_gateway_auth -->|"checks blacklist"| node_redis
node_gateway_app -->|"dispatches protected routes"| node_proxy_routes
node_proxy_routes -->|"creates handlers"| node_breaker
node_breaker -->|"reads addresses"| node_gateway_config
node_breaker -->|"forwards requests"| node_user_app
node_breaker -->|"forwards requests"| node_order_app
node_auth_service -->|"reads and writes users"| node_auth_db
node_auth_service -->|"blacklists tokens"| node_redis
node_user_app -->|"dispatches routes"| node_user_routes
node_user_routes -->|"reads and writes profiles"| node_user_db
node_order_app -->|"dispatches routes"| node_order_routes
node_order_routes -->|"reads and writes orders"| node_order_db
node_rate_limit -->|"stores windows"| node_redis
node_gateway_app -->|"serves metrics"| node_metrics
node_prometheus -.->|"scrapes metrics"| node_gateway_app
node_grafana -.->|"visualizes metrics"| node_prometheus

click node_gateway_app "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/app.js"
click node_gateway_auth "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/middleware/auth.js"
click node_rate_limit "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/middleware/rateLimiter.js"
click node_auth_proxy "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/routes/authRoutes.js"
click node_proxy_routes "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/routes/proxyRoutes.js"
click node_breaker "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/utils/circuitBreaker.js"
click node_gateway_config "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/config/services.js"
click node_auth_service "https://github.com/rk936503/aegis-api/blob/main/auth-service/app.js"
click node_user_app "https://github.com/rk936503/aegis-api/blob/main/user-service/app.js"
click node_user_routes "https://github.com/rk936503/aegis-api/blob/main/user-service/routes/userRoutes.js"
click node_order_app "https://github.com/rk936503/aegis-api/blob/main/order-service/app.js"
click node_order_routes "https://github.com/rk936503/aegis-api/blob/main/order-service/routes/orderRoutes.js"
click node_auth_db "https://github.com/rk936503/aegis-api/blob/main/auth-service/prisma/schema.prisma"
click node_user_db "https://github.com/rk936503/aegis-api/blob/main/user-service/prisma/schema.prisma"
click node_order_db "https://github.com/rk936503/aegis-api/blob/main/order-service/prisma/schema.prisma"
click node_metrics_middleware "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/middleware/metrics.js"
click node_metrics "https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/utils/metrics.js"

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_gateway_app,node_gateway_auth,node_rate_limit,node_auth_proxy,node_proxy_routes,node_breaker,node_gateway_config,node_caller toneBlue
class node_auth_service toneAmber
class node_user_app,node_user_routes,node_order_app,node_order_routes toneMint
class node_auth_db,node_user_db,node_order_db,node_redis toneRose
class node_metrics_middleware,node_metrics,node_prometheus,node_grafana toneIndigo
```

## Components

### API gateway

- [Gateway app](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/app.js): `api-gateway/src/app.js`
- [JWT validation](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/middleware/auth.js): `api-gateway/src/middleware/auth.js`
- [Rate limiter](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/middleware/rateLimiter.js): `api-gateway/src/middleware/rateLimiter.js`
- [Auth proxy](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/routes/authRoutes.js): `api-gateway/src/routes/authRoutes.js`
- [Service handlers](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/routes/proxyRoutes.js): `api-gateway/src/routes/proxyRoutes.js`
- [Circuit breakers](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/utils/circuitBreaker.js): `api-gateway/src/utils/circuitBreaker.js`
- [Service addresses](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/config/services.js): `api-gateway/src/config/services.js`

### Identity

- [Auth service](https://github.com/rk936503/aegis-api/blob/main/auth-service/app.js): `auth-service/app.js`

### Domain services

- [User service](https://github.com/rk936503/aegis-api/blob/main/user-service/app.js): `user-service/app.js`
- [Profile operations](https://github.com/rk936503/aegis-api/blob/main/user-service/routes/userRoutes.js): `user-service/routes/userRoutes.js`
- [Order service](https://github.com/rk936503/aegis-api/blob/main/order-service/app.js): `order-service/app.js`
- [Order lifecycle](https://github.com/rk936503/aegis-api/blob/main/order-service/routes/orderRoutes.js): `order-service/routes/orderRoutes.js`

### Persistence

- [Auth database](https://github.com/rk936503/aegis-api/blob/main/auth-service/prisma/schema.prisma): `auth-service/prisma/schema.prisma`
- [User database](https://github.com/rk936503/aegis-api/blob/main/user-service/prisma/schema.prisma): `user-service/prisma/schema.prisma`
- [Order database](https://github.com/rk936503/aegis-api/blob/main/order-service/prisma/schema.prisma): `order-service/prisma/schema.prisma`
- **Redis**

### Observability

- [Metrics middleware](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/middleware/metrics.js): `api-gateway/src/middleware/metrics.js`
- [Metrics registry](https://github.com/rk936503/aegis-api/blob/main/api-gateway/src/utils/metrics.js): `api-gateway/src/utils/metrics.js`
- **Prometheus**
- **Grafana**

### Other components

- **API client**

## Connections

- API client → Gateway app: sends requests
- Gateway app → Metrics middleware: records requests
- Metrics middleware → Metrics registry: updates metrics
- Gateway app → Rate limiter: limits requests
- Gateway app → Auth proxy: dispatches auth
- Auth proxy → Service addresses: reads address
- Auth proxy → Auth service: proxies requests
- Gateway app → JWT validation: checks protected routes
- JWT validation → Redis: checks blacklist
- Gateway app → Service handlers: dispatches protected routes
- Service handlers → Circuit breakers: creates handlers
- Circuit breakers → Service addresses: reads addresses
- Circuit breakers → User service: forwards requests
- Circuit breakers → Order service: forwards requests
- Auth service → Auth database: reads and writes users
- Auth service → Redis: blacklists tokens
- User service → Profile operations: dispatches routes
- Profile operations → User database: reads and writes profiles
- Order service → Order lifecycle: dispatches routes
- Order lifecycle → Order database: reads and writes orders
- Rate limiter → Redis: stores windows
- Gateway app → Metrics registry: serves metrics
- Prometheus → Gateway app: scrapes metrics
- Grafana → Prometheus: visualizes metrics