# ansible/jewel architecture

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

- Interactive diagram: https://gitdiagram.com/ansible/jewel
- Repository: https://github.com/ansible/jewel

## Overview

Jewel is a Django-based gateway connecting Ansible services and exposing shared resources. The principal workflow is an API client request entering the gateway, passing authentication and API routing, then interacting with gateway state or upstream services through the resource client. Separate branches cover service registration/routing, Envoy control-plane support, preferences, and legacy service-data migration. Edges are limited to relationships shown in the README or SOURCE INDEX; unsampled runtime wiring is not inferred.

Main entry points: [`aap_gateway_api/models`](https://github.com/ansible/jewel/tree/devel/aap_gateway_api/models) (Gateway State), [`aap_gateway_api/utils/resources_client.py`](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/resources_client.py) (Upstream Resource Client), [`aap_gateway_api/views`](https://github.com/ansible/jewel/tree/devel/aap_gateway_api/views) (API Views), [`aap_gateway_api/authentication/service_token_auth.py`](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/authentication/service_token_auth.py) (Service Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Gateway API"]
  node_api_entry["API Routing<br/>[router.py]"]
  node_api_views["API Views"]
  node_service_views["Service Endpoints<br/>[service.py]"]
  node_user_views["User Endpoints<br/>[user.py]"]
end

subgraph group_identity["Identity And Resources"]
  node_auth["Service Authentication"]
  node_common_auth["Shared Auth<br/>[authentication.py]"]
  node_models[("Gateway State")]
  node_resource_api["Resource API<br/>[resource_api.py]"]
  node_resource_client["Upstream Resource Client"]
end

subgraph group_routing["Service Routing"]
  node_service_sync["Service ID Sync<br/>[service_id_sync.py]"]
  node_service_config["Service Configuration<br/>[service_cluster.py]"]
  node_envoy["Envoy Control Plane<br/>[control_plane.py]"]
  node_envoy_api["Envoy API"]
end

subgraph group_operations["Gateway Operations"]
  node_preferences[("Preferences<br/>[preferences.py]")]
  node_migration["Migration Command"]
  node_migration_steps["Migration Stages"]
  node_startup["Startup Signals<br/>[apps.py]"]
end

node_client(("API Client"))
node_upstream{{"Ansible Services"}}

node_client -->|"sends requests"| node_api_entry
node_api_entry -->|"routes to"| node_api_views
node_api_views -->|"uses state"| node_models
node_api_views -->|"reads preferences"| node_preferences
node_service_views -->|"uses state"| node_models
node_service_views -->|"uses shared views"| node_api_views
node_user_views -.->|"uses state"| node_models
node_auth -->|"uses auth helpers"| node_common_auth
node_auth -.->|"authorizes access"| node_resource_api
node_auth -->|"checks migration state"| node_models
node_resource_api -.->|"contacts services"| node_resource_client
node_resource_client -.->|"sends HTTP requests"| node_upstream
node_resource_client -->|"reads configuration"| node_preferences
node_service_sync -->|"fetches metadata"| node_resource_client
node_service_sync -->|"queries routes"| node_models
node_service_config -.->|"stores service settings"| node_models
node_envoy_api -.->|"serves control plane"| node_envoy
node_envoy -->|"uses auth helpers"| node_common_auth
node_migration -->|"orchestrates stages"| node_migration_steps
node_migration -->|"reads migration state"| node_models
node_migration_steps -->|"calls upstream services"| node_resource_client
node_migration_steps -->|"loads service types"| node_models
node_startup -->|"initializes preferences"| node_preferences
node_startup -->|"clears control cache"| node_envoy_api

click node_api_entry "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/router.py"
click node_api_views "https://github.com/ansible/jewel/tree/devel/aap_gateway_api/views"
click node_service_views "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/views/api/v1/service.py"
click node_user_views "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/views/api/v1/user.py"
click node_auth "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/authentication/service_token_auth.py"
click node_common_auth "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/common/authentication.py"
click node_models "https://github.com/ansible/jewel/tree/devel/aap_gateway_api/models"
click node_resource_api "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/resource_api.py"
click node_resource_client "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/resources_client.py"
click node_preferences "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/preferences.py"
click node_service_sync "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/service_id_sync.py"
click node_service_config "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/models/service_cluster.py"
click node_envoy "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/proxy/control_plane.py"
click node_envoy_api "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/views/api/envoy/rest_control_plane.py"
click node_migration "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/management/commands/migrate_service_data.py"
click node_migration_steps "https://github.com/ansible/jewel/tree/devel/aap_gateway_api/management/commands/_migrate_service_data"
click node_startup "https://github.com/ansible/jewel/blob/devel/aap_gateway_api/apps.py"

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_api_entry,node_api_views,node_service_views,node_user_views,node_client toneBlue
class node_auth,node_common_auth,node_models,node_resource_api,node_resource_client toneAmber
class node_service_sync,node_service_config,node_envoy,node_envoy_api toneMint
class node_preferences,node_migration,node_migration_steps,node_startup toneRose
class node_upstream toneIndigo
```

## Components

### Gateway API

- [API Routing](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/router.py): `aap_gateway_api/router.py`
- [API Views](https://github.com/ansible/jewel/tree/devel/aap_gateway_api/views): `aap_gateway_api/views`
- [Service Endpoints](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/views/api/v1/service.py): `aap_gateway_api/views/api/v1/service.py`
- [User Endpoints](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/views/api/v1/user.py): `aap_gateway_api/views/api/v1/user.py`

### Identity And Resources

- [Service Authentication](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/authentication/service_token_auth.py): `aap_gateway_api/authentication/service_token_auth.py`
- [Shared Auth](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/common/authentication.py): `aap_gateway_api/common/authentication.py`
- [Gateway State](https://github.com/ansible/jewel/tree/devel/aap_gateway_api/models): `aap_gateway_api/models`
- [Resource API](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/resource_api.py): `aap_gateway_api/resource_api.py`
- [Upstream Resource Client](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/resources_client.py): `aap_gateway_api/utils/resources_client.py`

### Service Routing

- [Service ID Sync](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/service_id_sync.py): `aap_gateway_api/utils/service_id_sync.py`
- [Service Configuration](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/models/service_cluster.py): `aap_gateway_api/models/service_cluster.py`
- [Envoy Control Plane](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/proxy/control_plane.py): `aap_gateway_api/proxy/control_plane.py`
- [Envoy API](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/views/api/envoy/rest_control_plane.py): `aap_gateway_api/views/api/envoy/rest_control_plane.py`

### Gateway Operations

- [Preferences](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/utils/preferences.py): `aap_gateway_api/utils/preferences.py`
- [Migration Command](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/management/commands/migrate_service_data.py): `aap_gateway_api/management/commands/migrate_service_data.py`
- [Migration Stages](https://github.com/ansible/jewel/tree/devel/aap_gateway_api/management/commands/_migrate_service_data): `aap_gateway_api/management/commands/_migrate_service_data`
- [Startup Signals](https://github.com/ansible/jewel/blob/devel/aap_gateway_api/apps.py): `aap_gateway_api/apps.py`

### Other components

- **API Client**
- **Ansible Services**

## Connections

- API Client → API Routing: sends requests (evidence: `aap_gateway_api/router.py`)
- API Routing → API Views: routes to (evidence: `aap_gateway_api/router.py`)
- API Views → Gateway State: uses state (evidence: `aap_gateway_api/views/__init__.py`)
- API Views → Preferences: reads preferences (evidence: `aap_gateway_api/views/__init__.py`)
- Service Endpoints → Gateway State: uses state (evidence: `aap_gateway_api/views/api/v1/service.py`)
- Service Endpoints → API Views: uses shared views (evidence: `aap_gateway_api/views/api/v1/service.py`)
- User Endpoints → Gateway State: uses state
- Service Authentication → Shared Auth: uses auth helpers (evidence: `aap_gateway_api/authentication/service_token_auth.py`)
- Service Authentication → Resource API: authorizes access
- Service Authentication → Gateway State: checks migration state (evidence: `aap_gateway_api/authentication/service_token_auth.py`)
- Resource API → Upstream Resource Client: contacts services
- Upstream Resource Client → Ansible Services: sends HTTP requests
- Upstream Resource Client → Preferences: reads configuration (evidence: `aap_gateway_api/utils/resources_client.py`)
- Service ID Sync → Upstream Resource Client: fetches metadata (evidence: `aap_gateway_api/utils/service_id_sync.py`)
- Service ID Sync → Gateway State: queries routes (evidence: `aap_gateway_api/utils/service_id_sync.py`)
- Service Configuration → Gateway State: stores service settings (evidence: `aap_gateway_api/models/service_cluster.py`)
- Envoy API → Envoy Control Plane: serves control plane
- Envoy Control Plane → Shared Auth: uses auth helpers (evidence: `aap_gateway_api/proxy/control_plane.py`)
- Migration Command → Migration Stages: orchestrates stages (evidence: `aap_gateway_api/management/commands/migrate_service_data.py`)
- Migration Command → Gateway State: reads migration state (evidence: `aap_gateway_api/management/commands/migrate_service_data.py`)
- Migration Stages → Upstream Resource Client: calls upstream services (evidence: `aap_gateway_api/management/commands/_migrate_service_data/service_orchestration.py`)
- Migration Stages → Gateway State: loads service types (evidence: `aap_gateway_api/management/commands/_migrate_service_data/service_orchestration.py`)
- Startup Signals → Preferences: initializes preferences (evidence: `aap_gateway_api/apps.py`)
- Startup Signals → Envoy API: clears control cache (evidence: `aap_gateway_api/apps.py`)