How apoorvgarg-creator/dj-electric works
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: sync.py Sync core · client.py Electric client · blog Blog app · models.py Model mixin
Components 19
django_electric
Reusable Django app package that bridges Django models to Electric SQL.
- App config · Registers the package with Django startup lifecycle.
django_electric/apps.py - Settings · Centralizes Electric-related Django settings and defaults.
django_electric/conf.py - Model mixin · Model-facing sync API for application models.
django_electric/models.py - Custom manager · Electric-aware manager for querying and sync access.
django_electric/managers.py - Sync core · Coordinates metadata, client calls, pulls, updates, and sync lifecycle.
django_electric/sync.py - Electric client · Builds and sends requests to Electric SQL and returns sync results.
django_electric/client.py - Decorators · Retry and caching wrappers around sync-related functions.
django_electric/decorators.py - Signals · Lifecycle events for sync start, success, and failure.
django_electric/signals.py - Errors · Package-specific failures for config, transport, and sync issues.
django_electric/exceptions.py - 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 · Checks configuration and connectivity to Electric.
django_electric/management/commands/electric_status.py - Sync cmd · 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 · End-to-end example of wiring the package into Django.
examples/demo_project - Blog app · Example application using Electric-enabled models, admin, views, and URLs.
examples/demo_project/blog - Demo 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 · Validates Electric client request and response behavior.
tests/test_client.py - Model tests · Covers model-facing sync integration and manager behavior.
tests/test_models.py - Sync tests · Exercises sync orchestration and lifecycle behavior.
tests/test_sync.py
Electric SQL
External sync service boundary.
- Electric SQL · Remote Electric SQL backend that receives sync requests and serves data.
Connections 19
- 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.