# kodefluence/altair architecture

> Architecture diagram of the GitHub repository kodefluence/altair, 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/kodefluence/altair
- Repository: https://github.com/kodefluence/altair

## Overview

Altair is a Go API gateway whose principal runtime purpose is to accept API traffic and route it toward configured upstreams; its repository also includes a plugin system, OAuth management and authorization, and Prometheus metrics. The tree identifies configuration, routing, controller, plugin, and OAuth subsystems, while the sampled code confirms configuration compilation, controller interfaces, OAuth application-manager dependencies, and the metrics endpoint. Most runtime wiring and proxy request details were not sampled, so uncertain call relationships are omitted.

Main entry points: [`plugin/oauth/module/application/usecase/application_manager.go`](https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/application/usecase/application_manager.go) (Application manager), [`altair.go`](https://github.com/kodefluence/altair/blob/master/altair.go) (Altair gateway), [`core/controller.go`](https://github.com/kodefluence/altair/blob/master/core/controller.go) (Controller interfaces), [`core/routing.go`](https://github.com/kodefluence/altair/blob/master/core/routing.go) (Route contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway runtime"]
  node_gateway["Altair gateway<br/>[altair.go]"]
  node_controller_api["Controller interfaces<br/>[controller.go]"]
  node_controller_manager["Controller manager<br/>[controller.go]"]
end

subgraph group_config_routing["Configuration and routing"]
  node_app_config["App configuration<br/>[app.go]"]
  node_database_config["Database configuration<br/>[database.go]"]
  node_database_access["Database access<br/>[database_bearer.go]"]
  node_route_contracts["Route contracts<br/>[routing.go]"]
  node_route_compiler["Route compiler<br/>[compiler.go]"]
  node_route_generator["Route generator<br/>[generator.go]"]
end

subgraph group_plugins["Plugin runtime"]
  node_plugin_registry["Plugin registry<br/>[registry.go]"]
  node_plugin_runner["Plugin runner<br/>[runner.go]"]
  node_plugin_api["Plugin interface<br/>[plugin.go]"]
end

subgraph group_oauth["OAuth"]
  node_oauth_http["OAuth endpoints<br/>[http.go]"]
  node_oauth_authorization["Authorization logic<br/>[authorization.go]"]
  node_oauth_app_http["Application endpoints<br/>[http.go]"]
  node_oauth_app_manager["Application manager"]
  node_oauth_formatter["OAuth formatter<br/>[formatter.go]"]
end

subgraph group_state_metrics["State and metrics"]
  node_oauth_repositories[("OAuth repositories")]
  node_prometheus_endpoint["Prometheus endpoint"]
end

node_api_caller(("API caller"))
node_prometheus(("Prometheus"))

node_api_caller -->|"sends requests"| node_gateway
node_gateway -->|"handles routes"| node_controller_api
node_controller_manager -->|"manages controllers"| node_controller_api
node_route_compiler -->|"implements compile"| node_route_contracts
node_route_generator -->|"implements generate"| node_route_contracts
node_oauth_app_manager -->|"repository dependency"| node_oauth_repositories
node_oauth_app_manager -->|"formatter dependency"| node_oauth_formatter
node_prometheus -->|"scrapes metrics"| node_prometheus_endpoint

click node_gateway "https://github.com/kodefluence/altair/blob/master/altair.go"
click node_controller_api "https://github.com/kodefluence/altair/blob/master/core/controller.go"
click node_controller_manager "https://github.com/kodefluence/altair/blob/master/module/controller/usecase/controller.go"
click node_app_config "https://github.com/kodefluence/altair/blob/master/cfg/app.go"
click node_database_config "https://github.com/kodefluence/altair/blob/master/cfg/database.go"
click node_database_access "https://github.com/kodefluence/altair/blob/master/cfg/database_bearer.go"
click node_route_contracts "https://github.com/kodefluence/altair/blob/master/core/routing.go"
click node_route_compiler "https://github.com/kodefluence/altair/blob/master/module/router/usecase/compiler.go"
click node_route_generator "https://github.com/kodefluence/altair/blob/master/module/router/usecase/generator.go"
click node_plugin_registry "https://github.com/kodefluence/altair/blob/master/plugin/registry.go"
click node_plugin_runner "https://github.com/kodefluence/altair/blob/master/plugin/runner.go"
click node_plugin_api "https://github.com/kodefluence/altair/blob/master/module/plugin.go"
click node_oauth_http "https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/authorization/controller/http/http.go"
click node_oauth_authorization "https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/authorization/usecase/authorization.go"
click node_oauth_app_http "https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/application/controller/http/http.go"
click node_oauth_app_manager "https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/application/usecase/application_manager.go"
click node_oauth_repositories "https://github.com/kodefluence/altair/blob/master/plugin/oauth/repository/mysql/oauth_application.go"
click node_oauth_formatter "https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/formatter/usecase/formatter.go"
click node_prometheus_endpoint "https://github.com/kodefluence/altair/blob/master/plugin/metric/module/prometheus/controller/http/prometheus_controller.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_gateway,node_controller_api,node_controller_manager toneBlue
class node_app_config,node_database_config,node_database_access,node_route_contracts,node_route_compiler,node_route_generator toneAmber
class node_plugin_registry,node_plugin_runner,node_plugin_api,node_api_caller toneMint
class node_oauth_http,node_oauth_authorization,node_oauth_app_http,node_oauth_app_manager,node_oauth_formatter toneRose
class node_oauth_repositories,node_prometheus_endpoint,node_prometheus toneIndigo
```

## Components

### Gateway runtime

- [Altair gateway](https://github.com/kodefluence/altair/blob/master/altair.go): `altair.go`
- [Controller interfaces](https://github.com/kodefluence/altair/blob/master/core/controller.go): `core/controller.go`
- [Controller manager](https://github.com/kodefluence/altair/blob/master/module/controller/usecase/controller.go): `module/controller/usecase/controller.go`

### Configuration and routing

- [App configuration](https://github.com/kodefluence/altair/blob/master/cfg/app.go): `cfg/app.go`
- [Database configuration](https://github.com/kodefluence/altair/blob/master/cfg/database.go): `cfg/database.go`
- [Database access](https://github.com/kodefluence/altair/blob/master/cfg/database_bearer.go): `cfg/database_bearer.go`
- [Route contracts](https://github.com/kodefluence/altair/blob/master/core/routing.go): `core/routing.go`
- [Route compiler](https://github.com/kodefluence/altair/blob/master/module/router/usecase/compiler.go): `module/router/usecase/compiler.go`
- [Route generator](https://github.com/kodefluence/altair/blob/master/module/router/usecase/generator.go): `module/router/usecase/generator.go`

### Plugin runtime

- [Plugin registry](https://github.com/kodefluence/altair/blob/master/plugin/registry.go): `plugin/registry.go`
- [Plugin runner](https://github.com/kodefluence/altair/blob/master/plugin/runner.go): `plugin/runner.go`
- [Plugin interface](https://github.com/kodefluence/altair/blob/master/module/plugin.go): `module/plugin.go`

### OAuth

- [OAuth endpoints](https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/authorization/controller/http/http.go): `plugin/oauth/module/authorization/controller/http/http.go`
- [Authorization logic](https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/authorization/usecase/authorization.go): `plugin/oauth/module/authorization/usecase/authorization.go`
- [Application endpoints](https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/application/controller/http/http.go): `plugin/oauth/module/application/controller/http/http.go`
- [Application manager](https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/application/usecase/application_manager.go): `plugin/oauth/module/application/usecase/application_manager.go`
- [OAuth formatter](https://github.com/kodefluence/altair/blob/master/plugin/oauth/module/formatter/usecase/formatter.go): `plugin/oauth/module/formatter/usecase/formatter.go`

### State and metrics

- [OAuth repositories](https://github.com/kodefluence/altair/blob/master/plugin/oauth/repository/mysql/oauth_application.go): `plugin/oauth/repository/mysql/oauth_application.go`
- [Prometheus endpoint](https://github.com/kodefluence/altair/blob/master/plugin/metric/module/prometheus/controller/http/prometheus_controller.go): `plugin/metric/module/prometheus/controller/http/prometheus_controller.go`

### Other components

- **API caller**
- **Prometheus**

## Connections

- API caller → Altair gateway: sends requests
- Altair gateway → Controller interfaces: handles routes
- Controller manager → Controller interfaces: manages controllers
- Route compiler → Route contracts: implements compile
- Route generator → Route contracts: implements generate
- Application manager → OAuth repositories: repository dependency
- Application manager → OAuth formatter: formatter dependency
- Prometheus → Prometheus endpoint: scrapes metrics