# apoorvgarg-creator/dj-electric architecture

> Architecture diagram of the GitHub repository apoorvgarg-creator/dj-electric, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apoorvgarg-creator/dj-electric
- Repository: https://github.com/apoorvgarg-creator/dj-electric

## Overview

1. **What this repository is**
   - `django_electric` is a reusable Django app package, not a standalone service.
   - Its job is to connect Django ORM models to an external Electric SQL sync service over the network, so Django data can be pushed, pulled, and queried through “shapes.”

2. **Main runtime boundary**
   - The package sits between Django model code and the Electric SQL backend.
   - On one side it exposes Django-friendly APIs: model mixins, managers, admin actions, signals, and management commands.
   - On the other side it translates those operations into Electric-specific sync calls through `ElectricClient`.

3. **Core orchestration path**
   - The key flow is: Django model or command calls into `models.py` / `managers.py` / `sync.py` → `client.py` builds requests to Electric SQL → results come back and are turned into sync stats, shape IDs, or pulled rows.
   - `sync.py` appears to be the coordination layer that ties model metadata, HTTP client calls, and update/pull behavior together.

4. **Model integration layer**
   - `models.py` provides the model-facing sync mixin used by application models.
   - `managers.py` adds a custom manager for Electric-aware querying or sync access.
   - This is the main API boundary for app developers: they enable sync through model metadata and then call methods like `electric_sync`, `electric_pull`, and `electric_get_data`.

5. **Configuration and app bootstrapping**
   - `conf.py` centralizes reading Django settings such as service URL, auth token, timeouts, batch size, and auto-sync behavior.
   - `apps.py` registers the Django app so it can participate in Django’s startup lifecycle.
   - `__init__.py` makes the package importable as a Django app and likely exposes version/package metadata.

6. **Electric client boundary**
   - `client.py` is the direct integration point with Electric SQL.
   - It likely encapsulates request construction, connection/auth handling, shape creation, sync submission, and data retrieval.
   - This is the only part that should know Electric’s HTTP/API semantics; everything else should depend on it indirectly.

7. **Sync behavior and lifecycle events**
   - `signals.py` defines sync lifecycle signals such as started, completed, and failed.
   - This gives the package an event boundary so application code can react without coupling to the sync implementation.
   - `exceptions.py` provides a clean error boundary for configuration, transport, or sync failures.

8. **Developer-facing convenience layers**
   - `decorators.py` adds cross-cutting concerns like caching and retry around sync-related functions.
   - `middleware.py` is a Django integration hook for request/response-time behavior if the app needs per-request sync context or automatic handling.
   - These are support layers around the core sync path, not the primary data plane.

9. **Management and operational entry points**
   - `management/commands/electric_status.py` checks configuration/connectivity to the Electric service.
   - `management/commands/electric_sync.py` is the operational command for syncing or pulling specific models or all models.
   - These commands exercise the same core sync layer as the model API, but from the Django CLI boundary.

10. **Example application and validation**
   - `examples/demo_project` is a full Django project showing how the package is wired into a real app: settings, URLs, a sample blog app, admin, views, and model sync usage.
   - `tests/` covers the client, model behavior, and sync orchestration, which suggests the architecture is centered on keeping the model-to-client contract stable.

11. **Packaging and delivery**
   - The repository is packaged as a Python distribution via `setup.py`, `pyproject.toml`, and standard release workflows.
   - GitHub Actions run linting, tests, and publishing, so the package is intended to be consumed as a library rather than deployed as an application service.

12. **What an architecture diagram should emphasize**
   - Show Django models and management commands as the main entry points.
   - Show `sync.py` as the coordinator between Django-specific abstractions and `client.py`.
   - Show Electric SQL as the external system boundary.
   - Show signals, decorators, and exceptions as support mechanisms around the sync workflow, not as separate subsystems.

Main entry points: [`django_electric/sync.py`](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/sync.py) (Sync core), [`django_electric/client.py`](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/client.py) (Electric client), [`examples/demo_project/blog`](https://github.com/apoorvgarg-creator/dj-electric/tree/main/examples/demo_project/blog) (Blog app), [`django_electric/models.py`](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/models.py) (Model mixin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pkg["django_electric"]
  node_apps["App config<br/>[apps.py]"]
  node_conf["Settings<br/>config reader<br/>[conf.py]"]
  node_models["Model mixin<br/>django model api<br/>[models.py]"]
  node_managers["Custom manager<br/>query manager<br/>[managers.py]"]
  node_sync{{"Sync core<br/>orchestrator<br/>[sync.py]"}}
  node_client["Electric client<br/>http client<br/>[client.py]"]
  node_decorators["Decorators<br/>cross-cutting<br/>[decorators.py]"]
  node_signals(("Signals<br/>event hooks<br/>[signals.py]"))
  node_exceptions(("Errors<br/>exception boundary<br/>[exceptions.py]"))
  node_middleware["Middleware<br/>[middleware.py]"]
end

subgraph group_mgmt["Commands"]
  node_status_cmd["Status cmd<br/>management command<br/>[electric_status.py]"]
  node_sync_cmd["Sync cmd<br/>management command<br/>[electric_sync.py]"]
end

subgraph group_example["Example app"]
  node_demo_project["Demo project<br/>sample Django project"]
  node_blog_app["Blog app<br/>sample app"]
  node_demo_settings["Demo settings<br/>sample settings<br/>[settings.py]"]
end

subgraph group_tests["Tests"]
  node_tests_client["Client tests<br/>test suite<br/>[test_client.py]"]
  node_tests_models["Model tests<br/>test suite<br/>[test_models.py]"]
  node_tests_sync["Sync tests<br/>test suite<br/>[test_sync.py]"]
end

subgraph group_external["Electric SQL"]
  node_external_electric[("Electric SQL<br/>external service")]
end

node_conf -->|"settings"| node_sync
node_conf -->|"settings"| node_client
node_models -->|"calls"| node_sync
node_managers -->|"delegates"| node_sync
node_sync -->|"requests"| node_client
node_sync -->|"emits"| node_signals
node_sync -->|"raises"| node_exceptions
node_decorators -.->|"wraps"| node_sync
node_middleware -.->|"hooks"| node_sync
node_status_cmd -->|"checks"| node_client
node_sync_cmd -->|"invokes"| node_sync
node_demo_project -->|"contains"| node_blog_app
node_demo_project -->|"configures"| node_demo_settings
node_blog_app -->|"uses"| node_models
node_blog_app -->|"uses"| node_managers
node_tests_client -->|"verifies"| node_client
node_tests_models -->|"verifies"| node_models
node_tests_sync -->|"verifies"| node_sync
node_client -->|"talks to"| node_external_electric

click node_apps "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/apps.py"
click node_conf "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/conf.py"
click node_models "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/models.py"
click node_managers "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/managers.py"
click node_sync "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/sync.py"
click node_client "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/client.py"
click node_decorators "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/decorators.py"
click node_signals "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/signals.py"
click node_exceptions "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/exceptions.py"
click node_middleware "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/middleware.py"
click node_status_cmd "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/management/commands/electric_status.py"
click node_sync_cmd "https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/management/commands/electric_sync.py"
click node_demo_project "https://github.com/apoorvgarg-creator/dj-electric/tree/main/examples/demo_project"
click node_blog_app "https://github.com/apoorvgarg-creator/dj-electric/tree/main/examples/demo_project/blog"
click node_demo_settings "https://github.com/apoorvgarg-creator/dj-electric/blob/main/examples/demo_project/demo/settings.py"
click node_tests_client "https://github.com/apoorvgarg-creator/dj-electric/blob/main/tests/test_client.py"
click node_tests_models "https://github.com/apoorvgarg-creator/dj-electric/blob/main/tests/test_models.py"
click node_tests_sync "https://github.com/apoorvgarg-creator/dj-electric/blob/main/tests/test_sync.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_apps,node_conf,node_models,node_managers,node_sync,node_client,node_decorators,node_signals,node_exceptions,node_middleware toneBlue
class node_status_cmd,node_sync_cmd toneAmber
class node_demo_project,node_blog_app,node_demo_settings toneMint
class node_tests_client,node_tests_models,node_tests_sync toneRose
class node_external_electric toneIndigo
```

## Components

### django_electric

Reusable Django app package that bridges Django models to Electric SQL.

- [App config](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/apps.py): django app config · Registers the package with Django startup lifecycle. · `django_electric/apps.py`
- [Settings](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/conf.py): config reader · Centralizes Electric-related Django settings and defaults. · `django_electric/conf.py`
- [Model mixin](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/models.py): django model api · Model-facing sync API for application models. · `django_electric/models.py`
- [Custom manager](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/managers.py): query manager · Electric-aware manager for querying and sync access. · `django_electric/managers.py`
- [Sync core](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/sync.py): orchestrator · Coordinates metadata, client calls, pulls, updates, and sync lifecycle. · `django_electric/sync.py`
- [Electric client](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/client.py): http client · Builds and sends requests to Electric SQL and returns sync results. · `django_electric/client.py`
- [Decorators](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/decorators.py): cross-cutting · Retry and caching wrappers around sync-related functions. · `django_electric/decorators.py`
- [Signals](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/signals.py): event hooks · Lifecycle events for sync start, success, and failure. · `django_electric/signals.py`
- [Errors](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/exceptions.py): exception boundary · Package-specific failures for config, transport, and sync issues. · `django_electric/exceptions.py`
- [Middleware](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/middleware.py): django middleware · Request/response integration hook for per-request sync behavior. · `django_electric/middleware.py`

### Commands

Django management entry points for status and sync operations.

- [Status cmd](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/management/commands/electric_status.py): management command · Checks configuration and connectivity to Electric. · `django_electric/management/commands/electric_status.py`
- [Sync cmd](https://github.com/apoorvgarg-creator/dj-electric/blob/main/django_electric/management/commands/electric_sync.py): management command · Runs model sync or pull operations from the Django CLI. · `django_electric/management/commands/electric_sync.py`

### Example app

Demo Django project showing how the package is wired into Django.

- [Demo project](https://github.com/apoorvgarg-creator/dj-electric/tree/main/examples/demo_project): sample Django project · End-to-end example of wiring the package into Django. · `examples/demo_project`
- [Blog app](https://github.com/apoorvgarg-creator/dj-electric/tree/main/examples/demo_project/blog): sample app · Example application using Electric-enabled models, admin, views, and URLs. · `examples/demo_project/blog`
- [Demo settings](https://github.com/apoorvgarg-creator/dj-electric/blob/main/examples/demo_project/demo/settings.py): sample settings · Example project configuration for the package. · `examples/demo_project/demo/settings.py`

### Tests

Validation of the client, model API, and sync orchestration.

- [Client tests](https://github.com/apoorvgarg-creator/dj-electric/blob/main/tests/test_client.py): test suite · Validates Electric client request and response behavior. · `tests/test_client.py`
- [Model tests](https://github.com/apoorvgarg-creator/dj-electric/blob/main/tests/test_models.py): test suite · Covers model-facing sync integration and manager behavior. · `tests/test_models.py`
- [Sync tests](https://github.com/apoorvgarg-creator/dj-electric/blob/main/tests/test_sync.py): test suite · Exercises sync orchestration and lifecycle behavior. · `tests/test_sync.py`

### Electric SQL

External sync service boundary.

- **Electric SQL**: external service · Remote Electric SQL backend that receives sync requests and serves data.

## Connections

- Settings → Sync core: settings · Sync orchestration reads connection and batching configuration.
- Settings → Electric client: settings · Client uses configured URL, token, and timeout values.
- Model mixin → Sync core: calls · Model mixin delegates sync operations to the coordinator.
- Custom manager → Sync core: delegates · Manager participates in Electric-aware data access and syncing.
- Sync core → Electric client: requests · Coordinator converts Django sync actions into Electric API calls.
- Sync core → Signals: emits · Broadcasts lifecycle events around sync execution.
- Sync core → Errors: raises · Surfaces package-specific sync and transport failures.
- Decorators → Sync core: wraps · Provides retry and caching around sync-related functions.
- Middleware → Sync core: hooks · Can trigger or shape per-request sync behavior.
- Status cmd → Electric client: checks · Status command probes the Electric service through the client.
- Sync cmd → Sync core: invokes · CLI command runs the same sync coordinator used by models.
- Demo project → Blog app: contains · Demo project hosts the sample blog application.
- Demo project → Demo settings: configures · Project settings wire the package into Django.
- Blog app → Model mixin: uses · Sample app demonstrates the Electric model API.
- Blog app → Custom manager: uses · Sample app can use the custom manager in practice.
- Client tests → Electric client: verifies · Client tests validate request building and response handling.
- Model tests → Model mixin: verifies · Model tests cover the Django-facing sync API.
- Sync tests → Sync core: verifies · Sync tests exercise orchestration and lifecycle behavior.
- Electric client → Electric SQL: talks to · HTTP boundary to the Electric SQL service.