# ansible/awx architecture

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

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

## Overview

1. **What this repo is**
   AWX is a Django-based automation controller. The core product is split into a web/API application, a background task/dispatch engine, a websocket/real-time channel, and a set of automation clients and deployment assets around it.

2. **Primary application boundary**
   The main runtime lives under `awx/`. `manage.py`, `awx/wsgi.py`, and `awx/asgi.py` are the entry points. Django settings are separated into `awx/settings/`, with environment-specific defaults for development, production, quiet, and Kubernetes-like deployments.

3. **HTTP/API layer**
   `awx/api/` is the REST surface. It contains authentication, permissions, serializers, pagination, schema generation, renderers/parsers, and a large set of view and URL modules grouped by resource domain: jobs, templates, inventories, projects, credentials, schedules, workflow jobs, instances, organizations, and notifications. This layer is the public contract consumed by the UI, `awxkit`, and the Ansible collection.

4. **Domain model layer**
   The business model is centered in `awx/main/models/` and `awx/conf/models.py`. `awx/main/models/` covers inventories, hosts, projects, jobs, workflows, credentials, labels, notifications, RBAC, execution environments, receptor addresses, and high-availability state. `awx/conf/` stores controller settings and licensing/subscription-related configuration. Django migrations are extensive, which signals that the database schema is a major architectural boundary.

5. **Job execution and dispatch pipeline**
   The asynchronous execution path is in `awx/main/dispatch/`, `awx/main/scheduler/`, `awx/main/tasks/`, `awx/main/queue.py`, and the management commands like `run_dispatcher`, `dispatcherd`, `run_callback_receiver`, and `run_wsrelay`. The scheduler chooses what should run, the dispatcher hands work to execution backends, and task modules handle job callbacks, fact collection, host metrics, policy checks, receptor interactions, and system maintenance. This is the core “control plane” versus “execution plane” split.

6. **Execution mesh / receptor integration**
   AWX integrates with a receptor-based execution mesh. The codebase has receptor-facing models, tasks, routing, and install-bundle templates under `awx/api/templates/instance_install_bundle/`. This is the path by which jobs are placed onto execution nodes rather than run only on the controller host.

7. **Real-time updates and analytics**
   Websocket and event streaming are first-class concerns. `awx/main/consumers.py`, `awx/main/routing.py`, and `awx/main/wsrelay.py` support live updates to clients. `awx/main/analytics/` and `awx/api/metrics.py` collect and expose subsystem metrics, job/job-event stats, and dispatch-related telemetry. These flows connect background activity to the UI and API consumers.

8. **UI boundary**
   The controller UI lives in `awx/ui/`. It is a separate Django app with its own URLs, context processors, and static/public assets. The repository also contains `awx/static/` and `awx/templates/` for server-rendered error and API pages, but the main user-facing frontend boundary is the `awx/ui` app.

9. **Notification and external integration subsystem**
   Notification delivery is isolated under `awx/main/notifications/`, with backends for email, webhook, Slack, PagerDuty, Mattermost, Rocket.Chat, Twilio, Grafana, IRC, and AWS SNS. This subsystem is fed by job and workflow events from the main domain model and is triggered by controller-side task logic.

10. **Automation client and content distribution**
   The repo includes two important external-facing packages: `awx_collection/` and `awxkit/`. `awx_collection` is the Ansible Collection that wraps controller resources as modules/lookup plugins/inventory plugins for automation-driven management. `awxkit` is the Python/CLI client built around the same REST API, using page objects and resource helpers. These are separate distribution artifacts, not part of the server runtime.

11. **Deployment and developer infrastructure**
   The `tools/` and `config/` directories encode how the system is assembled: Docker/compose, Ansible-based image generation, minikube bootstrap, Grafana/Loki/Prometheus/OTel configs, Redis and rsyslog configs, and release/debug scripts. This repo is designed to run as a multi-process service stack rather than a single process.

12. **Data stores and cross-cutting dependencies**
   PostgreSQL is the primary persistence layer for the Django models and migrations. Redis is used for caching/coordination and websocket-related plumbing. The application also relies on Ansible ecosystem components, receptor communication, and optional observability tooling. Those are important architecture boundaries because they separate controller state, async coordination, and execution telemetry.

13. **Quality and change management**
   Tests are broad and mirror the architecture: API, models, tasks, scheduler, notifications, live/functional, and collection/client tests. The heavy test surface reinforces that AWX is a platform with multiple integration boundaries, not just a single web service.

Main entry points: [`awx/api/__init__.py`](https://github.com/ansible/awx/blob/devel/awx/api/__init__.py) (REST API), [`awx/main/consumers.py`](https://github.com/ansible/awx/blob/devel/awx/main/consumers.py) (Realtime), [`docs/overview.md`](https://github.com/ansible/awx/blob/devel/docs/overview.md) (Docs), [`awx/main/models/__init__.py`](https://github.com/ansible/awx/blob/devel/awx/main/models/__init__.py) (Domain models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_manage_py["manage.py<br/>entrypoint<br/>[manage.py]"]
  node_asgi["ASGI<br/>entrypoint<br/>[asgi.py]"]
  node_wsgi["WSGI<br/>entrypoint<br/>[wsgi.py]"]
  node_settings["Settings<br/>config app<br/>[defaults.py]"]
  node_api["REST API<br/>django app<br/>[__init__.py]"]
  node_api_surface["API core<br/>api layer<br/>[authentication.py]"]
  node_api_routes["Resource routes<br/>api layer<br/>[urls.py]"]
  node_api_views["API views<br/>api layer<br/>[root.py]"]
  node_api_templates["API docs<br/>templates<br/>[api_root_view.md]"]
  node_conf["Controller config<br/>settings app<br/>[models.py]"]
  node_models[("Domain models<br/>django app<br/>[__init__.py]")]
  node_migrations["Migrations<br/>schema<br/>[0001_initial.py]"]
  node_scheduler["Scheduler<br/>control plane<br/>[task_manager.py]"]
  node_dispatch["Dispatcher<br/>control plane<br/>[dispatcherd.py]"]
  node_tasks["Tasks<br/>worker logic<br/>[jobs.py]"]
  node_realtime["Realtime<br/>websocket<br/>[consumers.py]"]
  node_analytics["Analytics<br/>telemetry<br/>[core.py]"]
  node_notifications["Notifications<br/>integration<br/>[base.py]"]
  node_ui["Web UI<br/>django app<br/>[urls.py]"]
end

subgraph group_clients["Clients"]
  node_collection["AWX Collection<br/>ansible collection<br/>[job_launch.py]"]
  node_awxkit["AWXKit<br/>python client<br/>[client.py]"]
end

subgraph group_deploy["Deployment"]
  node_tools["Tools<br/>deployment<br/>[launch_awx.sh]"]
end

subgraph group_docs["Docs & tests"]
  node_docs_root["Docs<br/>documentation<br/>[overview.md]"]
end

node_manage_py -->|"loads"| node_settings
node_manage_py -->|"starts"| node_api
node_manage_py -->|"uses"| node_models
node_asgi -->|"serves"| node_realtime
node_wsgi -->|"serves"| node_api
node_settings -->|"binds"| node_conf
node_api -->|"contains"| node_api_surface
node_api -->|"routes"| node_api_routes
node_api -->|"implements"| node_api_views
node_api -->|"documents"| node_api_templates
node_api -->|"reads/writes"| node_models
node_api -->|"exposes"| node_analytics
node_api -->|"configures"| node_notifications
node_models -->|"evolves"| node_migrations
node_scheduler -->|"plans"| node_models
node_scheduler -->|"hands off"| node_dispatch
node_dispatch -->|"runs"| node_tasks
node_tasks -->|"updates"| node_models
node_tasks -->|"triggers"| node_notifications
node_tasks -->|"publishes"| node_realtime
node_realtime -->|"feeds"| node_analytics
node_ui -->|"consumes"| node_api
node_ui -->|"subscribes"| node_realtime
node_collection -->|"wraps"| node_api
node_awxkit -->|"consumes"| node_api
node_tools -->|"orchestrates"| node_manage_py
node_tools -->|"deploys"| node_dispatch
node_tools -->|"deploys"| node_realtime
node_tools -->|"observes"| node_analytics
node_docs_root -->|"describes"| node_api
node_docs_root -->|"describes"| node_scheduler
node_docs_root -->|"describes"| node_realtime
node_docs_root -->|"describes"| node_collection
node_docs_root -->|"describes"| node_awxkit

click node_manage_py "https://github.com/ansible/awx/blob/devel/manage.py"
click node_asgi "https://github.com/ansible/awx/blob/devel/awx/asgi.py"
click node_wsgi "https://github.com/ansible/awx/blob/devel/awx/wsgi.py"
click node_settings "https://github.com/ansible/awx/blob/devel/awx/settings/defaults.py"
click node_api "https://github.com/ansible/awx/blob/devel/awx/api/__init__.py"
click node_api_surface "https://github.com/ansible/awx/blob/devel/awx/api/authentication.py"
click node_api_routes "https://github.com/ansible/awx/blob/devel/awx/api/urls/urls.py"
click node_api_views "https://github.com/ansible/awx/blob/devel/awx/api/views/root.py"
click node_api_templates "https://github.com/ansible/awx/blob/devel/awx/api/templates/api/api_root_view.md"
click node_conf "https://github.com/ansible/awx/blob/devel/awx/conf/models.py"
click node_models "https://github.com/ansible/awx/blob/devel/awx/main/models/__init__.py"
click node_migrations "https://github.com/ansible/awx/blob/devel/awx/main/migrations/0001_initial.py"
click node_scheduler "https://github.com/ansible/awx/blob/devel/awx/main/scheduler/task_manager.py"
click node_dispatch "https://github.com/ansible/awx/blob/devel/awx/main/dispatch/worker/dispatcherd.py"
click node_tasks "https://github.com/ansible/awx/blob/devel/awx/main/tasks/jobs.py"
click node_realtime "https://github.com/ansible/awx/blob/devel/awx/main/consumers.py"
click node_analytics "https://github.com/ansible/awx/blob/devel/awx/main/analytics/core.py"
click node_notifications "https://github.com/ansible/awx/blob/devel/awx/main/notifications/base.py"
click node_ui "https://github.com/ansible/awx/blob/devel/awx/ui/urls.py"
click node_collection "https://github.com/ansible/awx/blob/devel/awx_collection/plugins/modules/job_launch.py"
click node_awxkit "https://github.com/ansible/awx/blob/devel/awxkit/awxkit/api/client.py"
click node_tools "https://github.com/ansible/awx/blob/devel/tools/docker-compose/launch_awx.sh"
click node_docs_root "https://github.com/ansible/awx/blob/devel/docs/overview.md"

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_manage_py,node_asgi,node_wsgi,node_settings,node_api,node_api_surface,node_api_routes,node_api_views,node_api_templates,node_conf,node_models,node_migrations,node_scheduler,node_dispatch,node_tasks,node_realtime,node_analytics,node_notifications,node_ui toneBlue
class node_collection,node_awxkit toneAmber
class node_tools toneMint
class node_docs_root toneRose
```

## Components

### Server runtime

Django controller, API surface, async workers, and real-time channels.

- [manage.py](https://github.com/ansible/awx/blob/devel/manage.py): entrypoint · Django management entrypoint for the controller. · `manage.py`
- [ASGI](https://github.com/ansible/awx/blob/devel/awx/asgi.py): entrypoint · Async web/server entrypoint. · `awx/asgi.py`
- [WSGI](https://github.com/ansible/awx/blob/devel/awx/wsgi.py): entrypoint · Sync web/server entrypoint. · `awx/wsgi.py`
- [Settings](https://github.com/ansible/awx/blob/devel/awx/settings/defaults.py): config app · Environment-specific Django settings and defaults. · `awx/settings/defaults.py`
- [REST API](https://github.com/ansible/awx/blob/devel/awx/api/__init__.py): django app · Public REST surface for controller resources. · `awx/api/__init__.py`
- [API core](https://github.com/ansible/awx/blob/devel/awx/api/authentication.py): api layer · Authentication, permissions, pagination, schema, rendering, and validation. · `awx/api/authentication.py`
- [Resource routes](https://github.com/ansible/awx/blob/devel/awx/api/urls/urls.py): api layer · Resource-domain URL modules for jobs, inventories, projects, credentials, workflows, instances, and more. · `awx/api/urls/urls.py`
- [API views](https://github.com/ansible/awx/blob/devel/awx/api/views/root.py): api layer · View implementations for bulk actions, inventory, metrics, organization, webhooks, and install bundles. · `awx/api/views/root.py`
- [API docs](https://github.com/ansible/awx/blob/devel/awx/api/templates/api/api_root_view.md): templates · Browsable API and install-bundle templates. · `awx/api/templates/api/api_root_view.md`
- [Controller config](https://github.com/ansible/awx/blob/devel/awx/conf/models.py): settings app · Persistent settings, licensing, and subscription configuration. · `awx/conf/models.py`
- [Domain models](https://github.com/ansible/awx/blob/devel/awx/main/models/__init__.py): django app · Core controller entities for inventories, jobs, workflows, projects, credentials, RBAC, execution environments, and HA state. · `awx/main/models/__init__.py`
- [Migrations](https://github.com/ansible/awx/blob/devel/awx/main/migrations/0001_initial.py): schema · Large schema-evolution boundary for controller state. · `awx/main/migrations/0001_initial.py`
- [Scheduler](https://github.com/ansible/awx/blob/devel/awx/main/scheduler/task_manager.py): control plane · Decides what should run and builds dependency graphs. · `awx/main/scheduler/task_manager.py`
- [Dispatcher](https://github.com/ansible/awx/blob/devel/awx/main/dispatch/worker/dispatcherd.py): control plane · Hands scheduled work to execution backends and workers. · `awx/main/dispatch/worker/dispatcherd.py`
- [Tasks](https://github.com/ansible/awx/blob/devel/awx/main/tasks/jobs.py): worker logic · Job callbacks, facts, host metrics, policy, receptor, and system maintenance tasks. · `awx/main/tasks/jobs.py`
- [Realtime](https://github.com/ansible/awx/blob/devel/awx/main/consumers.py): websocket · Consumers, routing, relay, and websocket heartbeat for live updates. · `awx/main/consumers.py`
- [Analytics](https://github.com/ansible/awx/blob/devel/awx/main/analytics/core.py): telemetry · Subsystem metrics, dispatch telemetry, and websocket broadcast analytics. · `awx/main/analytics/core.py`
- [Notifications](https://github.com/ansible/awx/blob/devel/awx/main/notifications/base.py): integration · Outbound email, webhook, chat, pager, SMS, and SNS backends. · `awx/main/notifications/base.py`
- [Web UI](https://github.com/ansible/awx/blob/devel/awx/ui/urls.py): django app · Separate Django UI boundary with its own URLs, context processors, and public assets. · `awx/ui/urls.py`

### Clients

External-facing automation clients built from the controller API.

- [AWX Collection](https://github.com/ansible/awx/blob/devel/awx_collection/plugins/modules/job_launch.py): ansible collection · Ansible collection for managing controller resources as modules, lookup plugins, and inventory plugins. · `awx_collection/plugins/modules/job_launch.py`
- [AWXKit](https://github.com/ansible/awx/blob/devel/awxkit/awxkit/api/client.py): python client · Python/CLI client built on the REST API with page objects and resource helpers. · `awxkit/awxkit/api/client.py`

### Deployment

Build, runtime, and observability assembly for local, container, and cluster installs.

- [Tools](https://github.com/ansible/awx/blob/devel/tools/docker-compose/launch_awx.sh): deployment · Docker, compose, minikube, scripts, and observability assembly. · `tools/docker-compose/launch_awx.sh`

### Docs & tests

Validation surface and repository documentation.

- [Docs](https://github.com/ansible/awx/blob/devel/docs/overview.md): documentation · Repository documentation for architecture, APIs, workflows, and operations. · `docs/overview.md`

## Connections

- manage.py → Settings: loads · Django runtime bootstraps environment settings.
- manage.py → REST API: starts · Management commands exercise the Django API app.
- manage.py → Domain models: uses · Commands operate on controller domain state.
- ASGI → Realtime: serves · ASGI path supports websocket and async channels.
- WSGI → REST API: serves · WSGI path exposes the REST and browsable API.
- Settings → Controller config: binds · Settings incorporate controller configuration and licensing.
- REST API → API core: contains · Core API machinery for auth, permissions, serialization, and schema.
- REST API → Resource routes: routes · Resource-specific URL modules define the public contract.
- REST API → API views: implements · View modules handle resource behavior and actions.
- REST API → API docs: documents · Browsable API and install-bundle templates are generated here.
- REST API → Domain models: reads/writes · REST resources expose controller domain entities.
- REST API → Analytics: exposes · Metrics and analytics endpoints surface subsystem telemetry.
- REST API → Notifications: configures · Notification templates and delivery resources are managed via API.
- Domain models → Migrations: evolves · Schema changes track the domain model over time.
- Scheduler → Domain models: plans · Scheduling decisions are based on jobs, workflows, instances, and capacity state.
- Scheduler → Dispatcher: hands off · Scheduled work is passed to the dispatcher for execution.
- Dispatcher → Tasks: runs · Dispatcher and workers execute callback, policy, receptor, and maintenance tasks.
- Tasks → Domain models: updates · Background work mutates job, host, project, and HA state.
- Tasks → Notifications: triggers · Task outcomes drive outbound notifications.
- Tasks → Realtime: publishes · Background events are pushed into live channels.
- Realtime → Analytics: feeds · Realtime activity contributes to analytics and telemetry.
- Web UI → REST API: consumes · Frontend boundary uses the REST API.
- Web UI → Realtime: subscribes · UI receives live updates over websocket channels.
- AWX Collection → REST API: wraps · Collection modules call controller REST resources.
- AWXKit → REST API: consumes · Python/CLI client is built around the same API contract.
- Tools → manage.py: orchestrates · Container and bootstrap tooling launch Django processes and commands.
- Tools → Dispatcher: deploys · Service definitions include controller worker/dispatcher processes.
- Tools → Realtime: deploys · Deployment assets include websocket relay and heartbeat services.
- Tools → Analytics: observes · Observability stack captures controller metrics and logs.
- Docs → REST API: describes · Documentation covers REST conventions and API reference.
- Docs → Scheduler: describes · Docs explain task manager and scheduling behavior.
- Docs → Realtime: describes · Docs cover websocket architecture and live updates.
- Docs → AWX Collection: describes · Docs include collection usage and content distribution.
- Docs → AWXKit: describes · Docs cover client usage and command-line workflows.
