# ekiourk/django-tunables architecture

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

- Interactive diagram: https://gitdiagram.com/ekiourk/django-tunables
- Repository: https://github.com/ekiourk/django-tunables
- Video tour (about a minute): https://gitdiagram.com/ekiourk/django-tunables/video

## Overview

django-tunables lets a Django host declare a typed catalogue, then operators read or edit its effective values through admin, embedded panel, or REST API. Edits become atomic, versioned change sets and snapshots, with audit history and optional publishing. Management commands synchronize, import/export, inspect, and retain snapshots; schema and search support external clients and discovery. The graph emphasizes documented capabilities and relationships visible in excerpts or the README; unsampled command and API wiring is not asserted.

Main entry points: [`src/tunables/services.py`](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/services.py) (Change services), [`src/tunables/api/views.py`](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/api/views.py) (REST API), [`src/tunables/sync.py`](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/sync.py) (Catalogue sync), [`src/tunables/management/commands`](https://github.com/ekiourk/django-tunables/tree/master/src/tunables/management/commands) (Management commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_declaration["Catalogue and definitions"]
  node_catalogue["Typed catalogue<br/>[catalogue.py]"]
  node_registry["Catalogue registry<br/>[registry.py]"]
  node_types["Value types<br/>[types.py]"]
  node_schema["Client schemas<br/>[schema.py]"]
end

subgraph group_interfaces["Operator interfaces"]
  node_admin["Django admin<br/>[__init__.py]"]
  node_panel["Embedded panel<br/>[panel.py]"]
  node_forms["Edit forms<br/>[forms.py]"]
  node_api["REST API<br/>[views.py]"]
  node_api_writes["API write handling<br/>[writes.py]"]
  node_search["Definition search<br/>[search.py]"]
  node_access["Edit access<br/>[access.py]"]
end

subgraph group_history["Changes and persistence"]
  node_services["Change services<br/>[services.py]"]
  node_models[("History and values<br/>[models.py]")]
  node_reader["Snapshot reader<br/>[reader.py]"]
  node_document["Snapshot documents<br/>[document.py]"]
end

subgraph group_operations["Operations and integration"]
  node_sync["Catalogue sync<br/>[sync.py]"]
  node_tags["Tags<br/>[tags.py]"]
  node_publishers["Snapshot publishers<br/>[publishers.py]"]
  node_management["Management commands"]
end

node_host(("Django host"))
node_external(("External client"))

node_host -->|"declares"| node_catalogue
node_registry -->|"loads"| node_catalogue
node_catalogue -->|"validates defaults"| node_types
node_admin -->|"uses"| node_forms
node_panel -->|"builds"| node_forms
node_forms -->|"applies edits"| node_services
node_api -->|"dispatches writes"| node_api_writes
node_api_writes -->|"applies changes"| node_services
node_admin -->|"checks access"| node_access
node_panel -->|"checks access"| node_access
node_services -->|"records versions"| node_models
node_services -->|"writes snapshots"| node_document
node_reader -->|"reads snapshots"| node_models
node_reader -->|"gets values"| node_services
node_sync -->|"loads catalogue"| node_registry
node_sync -->|"mirrors definitions"| node_models
node_sync -->|"writes system changes"| node_services
node_management -->|"runs sync"| node_sync
node_management -->|"imports and prunes"| node_services
node_api -->|"serves schemas"| node_schema
node_external -->|"reads and edits"| node_api
node_external -->|"renders forms"| node_schema
node_api -->|"filters definitions"| node_search
node_management -.->|"publishes snapshots"| node_publishers
node_publishers -.->|"delivers snapshot"| node_external

click node_catalogue "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/catalogue.py"
click node_registry "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/registry.py"
click node_types "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/types.py"
click node_schema "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/schema.py"
click node_admin "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/admin/__init__.py"
click node_panel "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/panel.py"
click node_forms "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/forms.py"
click node_api "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/api/views.py"
click node_api_writes "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/api/writes.py"
click node_search "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/search.py"
click node_access "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/access.py"
click node_services "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/services.py"
click node_models "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/models.py"
click node_reader "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/reader.py"
click node_document "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/document.py"
click node_sync "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/sync.py"
click node_tags "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/tags.py"
click node_publishers "https://github.com/ekiourk/django-tunables/blob/master/src/tunables/publishers.py"
click node_management "https://github.com/ekiourk/django-tunables/tree/master/src/tunables/management/commands"

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_catalogue,node_registry,node_types,node_schema,node_external toneBlue
class node_admin,node_panel,node_forms,node_api,node_api_writes,node_search,node_access toneAmber
class node_services,node_models,node_reader,node_document toneMint
class node_sync,node_tags,node_publishers,node_management toneRose
class node_host toneIndigo
```

## Components

### Catalogue and definitions

- [Typed catalogue](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/catalogue.py): `src/tunables/catalogue.py`
- [Catalogue registry](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/registry.py): `src/tunables/registry.py`
- [Value types](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/types.py): `src/tunables/types.py`
- [Client schemas](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/schema.py): `src/tunables/schema.py`

### Operator interfaces

- [Django admin](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/admin/__init__.py): `src/tunables/admin/__init__.py`
- [Embedded panel](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/panel.py): `src/tunables/panel.py`
- [Edit forms](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/forms.py): `src/tunables/forms.py`
- [REST API](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/api/views.py): `src/tunables/api/views.py`
- [API write handling](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/api/writes.py): `src/tunables/api/writes.py`
- [Definition search](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/search.py): `src/tunables/search.py`
- [Edit access](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/access.py): `src/tunables/access.py`

### Changes and persistence

- [Change services](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/services.py): `src/tunables/services.py`
- [History and values](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/models.py): `src/tunables/models.py`
- [Snapshot reader](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/reader.py): `src/tunables/reader.py`
- [Snapshot documents](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/document.py): `src/tunables/document.py`

### Operations and integration

- [Catalogue sync](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/sync.py): `src/tunables/sync.py`
- [Tags](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/tags.py): `src/tunables/tags.py`
- [Snapshot publishers](https://github.com/ekiourk/django-tunables/blob/master/src/tunables/publishers.py): `src/tunables/publishers.py`
- [Management commands](https://github.com/ekiourk/django-tunables/tree/master/src/tunables/management/commands): `src/tunables/management/commands`

### Other components

- **Django host**
- **External client**

## Connections

- Django host → Typed catalogue: declares (evidence: `README.md`)
- Catalogue registry → Typed catalogue: loads (evidence: `src/tunables/registry.py`)
- Typed catalogue → Value types: validates defaults (evidence: `src/tunables/catalogue.py`)
- Django admin → Edit forms: uses (evidence: `src/tunables/admin/__init__.py`)
- Embedded panel → Edit forms: builds (evidence: `src/tunables/panel.py`)
- Edit forms → Change services: applies edits (evidence: `src/tunables/forms.py`)
- REST API → API write handling: dispatches writes (evidence: `src/tunables/api/views.py`)
- API write handling → Change services: applies changes (evidence: `src/tunables/api/writes.py`)
- Django admin → Edit access: checks access (evidence: `src/tunables/admin/__init__.py`)
- Embedded panel → Edit access: checks access (evidence: `src/tunables/panel.py`)
- Change services → History and values: records versions (evidence: `src/tunables/services.py`)
- Change services → Snapshot documents: writes snapshots (evidence: `src/tunables/services.py`)
- Snapshot reader → History and values: reads snapshots (evidence: `src/tunables/reader.py`)
- Snapshot reader → Change services: gets values (evidence: `src/tunables/reader.py`)
- Catalogue sync → Catalogue registry: loads catalogue (evidence: `src/tunables/sync.py`)
- Catalogue sync → History and values: mirrors definitions (evidence: `src/tunables/sync.py`)
- Catalogue sync → Change services: writes system changes (evidence: `src/tunables/sync.py`)
- Management commands → Catalogue sync: runs sync (evidence: `src/tunables/management/commands/tunables_sync.py`)
- Management commands → Change services: imports and prunes (evidence: `src/tunables/management/commands/tunables_import.py`)
- REST API → Client schemas: serves schemas (evidence: `src/tunables/api/views.py`)
- External client → REST API: reads and edits (evidence: `README.md`)
- External client → Client schemas: renders forms (evidence: `README.md`)
- REST API → Definition search: filters definitions (evidence: `src/tunables/api/views.py`)
- Management commands → Snapshot publishers: publishes snapshots
- Snapshot publishers → External client: delivers snapshot
