# hcd233/aris-proxy-api architecture

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

- Interactive diagram: https://gitdiagram.com/hcd233/aris-proxy-api
- Repository: https://github.com/hcd233/aris-proxy-api

## Overview

Aris is a model-aggregation gateway with a web console for managing upstreams and curating usage data, plus a CLI and server workflows for Agent Harness traces. The main call path is client → API routing and proxy use cases → configured upstream; sessions, messages, tools, and call audits preserve interaction data for review, sharing, export, and monitoring. The README documents these capabilities and several cross-service flows; unsampled implementation details are represented only where the tree supports a subsystem path.

Main entry points: [`internal/application/llmproxy/usecase`](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/llmproxy/usecase) (Protocol proxy), [`internal/handler`](https://github.com/hcd233/aris-proxy-api/tree/master/internal/handler) (API handlers), [`internal/router`](https://github.com/hcd233/aris-proxy-api/tree/master/internal/router) (API routes), [`internal/infrastructure/repository/session_repository.go`](https://github.com/hcd233/aris-proxy-api/blob/master/internal/infrastructure/repository/session_repository.go) (Session storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Model gateway"]
  node_router["API routes"]
  node_handlers["API handlers"]
  node_middleware["Auth and limits"]
  node_proxy["Protocol proxy"]
  node_converters["Protocol converters"]
end

subgraph group_data["Usage data"]
  node_sessions["Session records"]
  node_datarepo["Session storage"]
  node_database[("Relational database")]
  node_dataset["Dataset export"]
  node_audit["Usage audit and stats"]
end

subgraph group_trace["Trace analysis"]
  node_cli["Aris CLI"]
  node_tracecollect["Trace collection"]
  node_traceapi["Trace ingestion and queries"]
  node_traceviews["Trace console"]
end

subgraph group_admin["Management and operations"]
  node_resolver["Endpoint and model config<br/>[resolver.go]"]
  node_adminusecases["Admin use cases"]
  node_cron["Scheduled governance"]
  node_metrics["Runtime monitoring"]
  node_redis[("Redis cache")]
end

node_client(("Agent clients"))
node_web(("Admin console"))
node_upstream{{"MaaS providers"}}

node_client -->|"sends requests"| node_router
node_web -->|"uses API"| node_router
node_cli -->|"uploads batches"| node_traceapi
node_router -->|"applies guards"| node_middleware
node_router -->|"dispatches routes"| node_handlers
node_handlers -->|"invokes proxy"| node_proxy
node_handlers -->|"invokes operations"| node_adminusecases
node_handlers -->|"invokes trace"| node_traceapi
node_proxy -->|"resolves model"| node_resolver
node_proxy -->|"translates protocol"| node_converters
node_proxy -->|"forwards requests"| node_upstream
node_proxy -->|"records interactions"| node_sessions
node_proxy -->|"records calls"| node_audit
node_sessions -->|"persists data"| node_datarepo
node_datarepo -->|"reads and writes"| node_database
node_dataset -->|"queries sessions"| node_datarepo
node_dataset -->|"streams export"| node_web
node_audit -->|"reads usage data"| node_datarepo
node_tracecollect -->|"feeds events"| node_cli
node_traceapi -->|"rebuilds conversations"| node_sessions
node_traceviews -->|"presents traces"| node_web
node_adminusecases -.->|"uses cache and pubsub"| node_redis
node_cron -->|"coordinates reloads"| node_redis
node_metrics -->|"stores snapshots"| node_redis

click node_cli "https://github.com/hcd233/aris-proxy-api/tree/master/cmd/client"
click node_router "https://github.com/hcd233/aris-proxy-api/tree/master/internal/router"
click node_handlers "https://github.com/hcd233/aris-proxy-api/tree/master/internal/handler"
click node_middleware "https://github.com/hcd233/aris-proxy-api/tree/master/internal/middleware"
click node_proxy "https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/llmproxy/usecase"
click node_converters "https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/llmproxy/converter"
click node_resolver "https://github.com/hcd233/aris-proxy-api/blob/master/internal/domain/llmproxy/service/resolver.go"
click node_sessions "https://github.com/hcd233/aris-proxy-api/tree/master/internal/domain/session"
click node_datarepo "https://github.com/hcd233/aris-proxy-api/blob/master/internal/infrastructure/repository/session_repository.go"
click node_dataset "https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/dataset"
click node_audit "https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/audit"
click node_tracecollect "https://github.com/hcd233/aris-proxy-api/tree/master/internal/client/trace"
click node_traceapi "https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/trace"
click node_traceviews "https://github.com/hcd233/aris-proxy-api/tree/master/web/src/app/(dashboard)/trace"
click node_adminusecases "https://github.com/hcd233/aris-proxy-api/tree/master/internal/application"
click node_cron "https://github.com/hcd233/aris-proxy-api/tree/master/internal/cron"
click node_metrics "https://github.com/hcd233/aris-proxy-api/tree/master/internal/infrastructure/metrics"

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_router,node_handlers,node_middleware,node_proxy,node_converters,node_client toneBlue
class node_sessions,node_datarepo,node_database,node_dataset,node_audit toneAmber
class node_cli,node_tracecollect,node_traceapi,node_traceviews toneMint
class node_resolver,node_adminusecases,node_cron,node_metrics,node_redis toneRose
class node_web,node_upstream toneIndigo
```

## Components

### Model gateway

- [API routes](https://github.com/hcd233/aris-proxy-api/tree/master/internal/router): `internal/router`
- [API handlers](https://github.com/hcd233/aris-proxy-api/tree/master/internal/handler): `internal/handler`
- [Auth and limits](https://github.com/hcd233/aris-proxy-api/tree/master/internal/middleware): `internal/middleware`
- [Protocol proxy](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/llmproxy/usecase): `internal/application/llmproxy/usecase`
- [Protocol converters](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/llmproxy/converter): `internal/application/llmproxy/converter`

### Usage data

- [Session records](https://github.com/hcd233/aris-proxy-api/tree/master/internal/domain/session): `internal/domain/session`
- [Session storage](https://github.com/hcd233/aris-proxy-api/blob/master/internal/infrastructure/repository/session_repository.go): `internal/infrastructure/repository/session_repository.go`
- **Relational database**
- [Dataset export](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/dataset): `internal/application/dataset`
- [Usage audit and stats](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/audit): `internal/application/audit`

### Trace analysis

- [Aris CLI](https://github.com/hcd233/aris-proxy-api/tree/master/cmd/client): `cmd/client`
- [Trace collection](https://github.com/hcd233/aris-proxy-api/tree/master/internal/client/trace): `internal/client/trace`
- [Trace ingestion and queries](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application/trace): `internal/application/trace`
- [Trace console](https://github.com/hcd233/aris-proxy-api/tree/master/web/src/app/(dashboard)/trace): `web/src/app/(dashboard)/trace`

### Management and operations

- [Endpoint and model config](https://github.com/hcd233/aris-proxy-api/blob/master/internal/domain/llmproxy/service/resolver.go): `internal/domain/llmproxy/service/resolver.go`
- [Admin use cases](https://github.com/hcd233/aris-proxy-api/tree/master/internal/application): `internal/application`
- [Scheduled governance](https://github.com/hcd233/aris-proxy-api/tree/master/internal/cron): `internal/cron`
- [Runtime monitoring](https://github.com/hcd233/aris-proxy-api/tree/master/internal/infrastructure/metrics): `internal/infrastructure/metrics`
- **Redis cache**

### Other components

- **Agent clients**
- **Admin console**
- **MaaS providers**

## Connections

- Agent clients → API routes: sends requests
- Admin console → API routes: uses API
- Aris CLI → Trace ingestion and queries: uploads batches
- API routes → Auth and limits: applies guards
- API routes → API handlers: dispatches routes
- API handlers → Protocol proxy: invokes proxy
- API handlers → Admin use cases: invokes operations
- API handlers → Trace ingestion and queries: invokes trace
- Protocol proxy → Endpoint and model config: resolves model
- Protocol proxy → Protocol converters: translates protocol
- Protocol proxy → MaaS providers: forwards requests
- Protocol proxy → Session records: records interactions
- Protocol proxy → Usage audit and stats: records calls
- Session records → Session storage: persists data
- Session storage → Relational database: reads and writes
- Dataset export → Session storage: queries sessions
- Dataset export → Admin console: streams export
- Usage audit and stats → Session storage: reads usage data
- Trace collection → Aris CLI: feeds events
- Trace ingestion and queries → Session records: rebuilds conversations
- Trace console → Admin console: presents traces
- Admin use cases → Redis cache: uses cache and pubsub
- Scheduled governance → Redis cache: coordinates reloads
- Runtime monitoring → Redis cache: stores snapshots