# motiv-labs/janus architecture

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

- Interactive diagram: https://gitdiagram.com/motiv-labs/janus
- Repository: https://github.com/motiv-labs/janus

## Overview

Janus is an API gateway and management platform. A client request is routed through the configured gateway, where authentication and policy plugins can control access before traffic reaches an upstream service; the gateway also exposes an API for managing definitions and credentials. The server loads and refreshes definitions, then registers API routes. The README documents additional capabilities such as rate limiting, retries, circuit breaking, CORS, and tracing. Some plugin wiring is not shown in the excerpts, so those relationships are left unverified.

Main entry points: [`pkg/server/server.go`](https://github.com/motiv-labs/janus/blob/master/pkg/server/server.go) (HTTP Server), [`pkg/proxy/reverse_proxy.go`](https://github.com/motiv-labs/janus/blob/master/pkg/proxy/reverse_proxy.go) (Reverse Proxy), [`pkg/loader/api_loader.go`](https://github.com/motiv-labs/janus/blob/master/pkg/loader/api_loader.go) (API Loader), [`pkg/router/router.go`](https://github.com/motiv-labs/janus/blob/master/pkg/router/router.go) (Request Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server Runtime"]
  node_main["Janus CLI<br/>[main.go]"]
  node_server["HTTP Server<br/>[server.go]"]
  node_api_loader["API Loader<br/>[api_loader.go]"]
end

subgraph group_routing["Gateway Routing"]
  node_gateway["Reverse Proxy<br/>[reverse_proxy.go]"]
  node_router["Request Router<br/>[router.go]"]
  node_balancer["Upstream Balancer<br/>[balancer.go]"]
end

subgraph group_management["Management API"]
  node_web_api["Definition API<br/>[api_handler.go]"]
  node_org_api["Organization API<br/>[handler.go]"]
end

subgraph group_security["Access and Plugins"]
  node_auth_plugins["Auth Plugins"]
  node_jwt["JWT Validation<br/>[handler.go]"]
  node_policy_plugins["Gateway Policies"]
end

subgraph group_state["State and Observability"]
  node_api_definitions[("API Definitions")]
  node_organization_store[("Organization Store")]
  node_observability["Metrics and Tracing<br/>[observability.go]"]
end

node_client(("API Client"))
node_upstream(("Backend Services"))
node_management_client(("Admin Client"))

node_main -->|"starts"| node_server
node_server -->|"registers APIs"| node_api_loader
node_api_loader -->|"configures proxies"| node_gateway
node_client -.->|"sends request"| node_server
node_server -.->|"creates router"| node_router
node_router -.->|"routes traffic"| node_gateway
node_gateway -.->|"selects backend"| node_balancer
node_gateway -.->|"forwards request"| node_upstream
node_management_client -.->|"manages definitions"| node_web_api
node_web_api -.->|"sends config changes"| node_server
node_server -.->|"loads definitions"| node_api_definitions
node_management_client -.->|"manages organizations"| node_org_api
node_org_api -->|"reads and writes"| node_organization_store
node_gateway -.->|"checks access"| node_auth_plugins
node_auth_plugins -->|"builds JWT manager"| node_jwt
node_gateway -.->|"applies policies"| node_policy_plugins
node_server -.->|"records telemetry"| node_observability

click node_main "https://github.com/motiv-labs/janus/blob/master/main.go"
click node_server "https://github.com/motiv-labs/janus/blob/master/pkg/server/server.go"
click node_api_loader "https://github.com/motiv-labs/janus/blob/master/pkg/loader/api_loader.go"
click node_gateway "https://github.com/motiv-labs/janus/blob/master/pkg/proxy/reverse_proxy.go"
click node_router "https://github.com/motiv-labs/janus/blob/master/pkg/router/router.go"
click node_balancer "https://github.com/motiv-labs/janus/blob/master/pkg/proxy/balancer/balancer.go"
click node_web_api "https://github.com/motiv-labs/janus/blob/master/pkg/web/api_handler.go"
click node_org_api "https://github.com/motiv-labs/janus/blob/master/pkg/plugin/organization/handler.go"
click node_auth_plugins "https://github.com/motiv-labs/janus/tree/master/pkg/plugin/oauth2"
click node_jwt "https://github.com/motiv-labs/janus/blob/master/pkg/jwt/handler.go"
click node_policy_plugins "https://github.com/motiv-labs/janus/tree/master/pkg/plugin"
click node_api_definitions "https://github.com/motiv-labs/janus/tree/master/pkg/api"
click node_organization_store "https://github.com/motiv-labs/janus/blob/master/pkg/plugin/organization/cassandra_repository.go"
click node_observability "https://github.com/motiv-labs/janus/blob/master/pkg/observability/observability.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_server,node_api_loader,node_client,node_management_client toneBlue
class node_gateway,node_router,node_balancer toneAmber
class node_web_api,node_org_api toneMint
class node_auth_plugins,node_jwt,node_policy_plugins toneRose
class node_api_definitions,node_organization_store,node_observability,node_upstream toneIndigo
```

## Components

### Server Runtime

- [Janus CLI](https://github.com/motiv-labs/janus/blob/master/main.go): `main.go`
- [HTTP Server](https://github.com/motiv-labs/janus/blob/master/pkg/server/server.go): `pkg/server/server.go`
- [API Loader](https://github.com/motiv-labs/janus/blob/master/pkg/loader/api_loader.go): `pkg/loader/api_loader.go`

### Gateway Routing

- [Reverse Proxy](https://github.com/motiv-labs/janus/blob/master/pkg/proxy/reverse_proxy.go): `pkg/proxy/reverse_proxy.go`
- [Request Router](https://github.com/motiv-labs/janus/blob/master/pkg/router/router.go): `pkg/router/router.go`
- [Upstream Balancer](https://github.com/motiv-labs/janus/blob/master/pkg/proxy/balancer/balancer.go): `pkg/proxy/balancer/balancer.go`

### Management API

- [Definition API](https://github.com/motiv-labs/janus/blob/master/pkg/web/api_handler.go): `pkg/web/api_handler.go`
- [Organization API](https://github.com/motiv-labs/janus/blob/master/pkg/plugin/organization/handler.go): `pkg/plugin/organization/handler.go`

### Access and Plugins

- [Auth Plugins](https://github.com/motiv-labs/janus/tree/master/pkg/plugin/oauth2): `pkg/plugin/oauth2`
- [JWT Validation](https://github.com/motiv-labs/janus/blob/master/pkg/jwt/handler.go): `pkg/jwt/handler.go`
- [Gateway Policies](https://github.com/motiv-labs/janus/tree/master/pkg/plugin): `pkg/plugin`

### State and Observability

- [API Definitions](https://github.com/motiv-labs/janus/tree/master/pkg/api): `pkg/api`
- [Organization Store](https://github.com/motiv-labs/janus/blob/master/pkg/plugin/organization/cassandra_repository.go): `pkg/plugin/organization/cassandra_repository.go`
- [Metrics and Tracing](https://github.com/motiv-labs/janus/blob/master/pkg/observability/observability.go): `pkg/observability/observability.go`

### Other components

- **API Client**
- **Backend Services**
- **Admin Client**

## Connections

- Janus CLI → HTTP Server: starts (evidence: `main.go`)
- HTTP Server → API Loader: registers APIs (evidence: `pkg/server/server.go`)
- API Loader → Reverse Proxy: configures proxies (evidence: `pkg/loader/api_loader.go`)
- API Client → HTTP Server: sends request
- HTTP Server → Request Router: creates router
- Request Router → Reverse Proxy: routes traffic
- Reverse Proxy → Upstream Balancer: selects backend
- Reverse Proxy → Backend Services: forwards request
- Admin Client → Definition API: manages definitions
- Definition API → HTTP Server: sends config changes (evidence: `pkg/web/api_handler.go`)
- HTTP Server → API Definitions: loads definitions (evidence: `pkg/server/server.go`)
- Admin Client → Organization API: manages organizations
- Organization API → Organization Store: reads and writes (evidence: `pkg/plugin/organization/handler.go`)
- Reverse Proxy → Auth Plugins: checks access
- Auth Plugins → JWT Validation: builds JWT manager (evidence: `pkg/plugin/oauth2/manager_factory.go`)
- Reverse Proxy → Gateway Policies: applies policies
- HTTP Server → Metrics and Tracing: records telemetry (evidence: `pkg/server/server.go`)
