# doorlockd/doorlockd-backend architecture

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

- Interactive diagram: https://gitdiagram.com/doorlockd/doorlockd-backend
- Repository: https://github.com/doorlockd/doorlockd-backend

## Overview

Doorlockd Backend manages people, keys, locks, and access policy, then exposes the resulting lock access lists and synchronization status to lock clients. Administrators manage records and inspect access and synchronization through Django admin and detail views; lock clients use the API to synchronize keys and report unknown-key and last-seen telemetry. The model layer implements access-list generation, synchronization state, and telemetry persistence. The excerpts show the main routes and API/model interactions; other model behavior is not inferred beyond the sampled code.

Main entry points: [`apps/doorlockdb/models.py`](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py) (People and Access Models), [`apps/doorlockdb/admin.py`](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/admin.py) (Django Admin), [`apps/doorlockdb/api.py`](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/api.py) (Lock API), [`apps/doorlockdb/views.py`](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/views.py) (Access Detail Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_management["Administration"]
  node_root_router["Project Router<br/>[urls.py]"]
  node_admin_ui["Django Admin<br/>[admin.py]"]
  node_group_bulk["Group Bulk Action<br/>[adminviews.py]"]
  node_forms["Model Forms<br/>[model_forms.py]"]
end

subgraph group_domain["Access Domain"]
  node_access_data["People and Access Models<br/>[models.py]"]
  node_lock_sync["Lock Sync Logic<br/>[models.py]"]
  node_key_telemetry["Key Telemetry<br/>[models.py]"]
end

subgraph group_client["Lock Client API"]
  node_api["Lock API<br/>[api.py]"]
  node_long_poll["Event Long Poll<br/>[views.py]"]
end

subgraph group_web["Web Views"]
  node_app_router["App Router<br/>[urls.py]"]
  node_detail_views["Access Detail Views<br/>[views.py]"]
  node_detail_templates["Detail Templates"]
end

node_admin_user(("Administrator"))
node_lock_client(("Lock Client"))
node_sqlite[("SQLite Database")]

node_root_router -->|"routes requests"| node_app_router
node_root_router -->|"mounts API"| node_api
node_root_router -->|"routes home"| node_detail_views
node_admin_user -->|"manages records"| node_admin_ui
node_admin_ui -->|"queries models"| node_access_data
node_admin_ui -->|"dispatches action"| node_group_bulk
node_admin_ui -.->|"uses forms"| node_forms
node_admin_ui -->|"edits records"| node_access_data
node_forms -->|"defines fields"| node_access_data
node_app_router -->|"routes polling"| node_long_poll
node_app_router -->|"routes details"| node_detail_views
node_detail_views -->|"queries access"| node_access_data
node_detail_views -->|"renders pages"| node_detail_templates
node_long_poll -->|"reads sync state"| node_lock_sync
node_api -->|"compares key state"| node_lock_sync
node_api -->|"records reports"| node_key_telemetry
node_api -->|"merges key metadata"| node_access_data
node_lock_client -->|"calls endpoints"| node_api
node_lock_client -->|"requests events"| node_long_poll
node_access_data -->|"persists records"| node_sqlite
node_lock_sync -->|"persists sync state"| node_sqlite
node_key_telemetry -->|"persists telemetry"| node_sqlite

click node_root_router "https://github.com/doorlockd/doorlockd-backend/blob/main/doorlockd_backend/urls.py"
click node_admin_ui "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/admin.py"
click node_group_bulk "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/adminviews.py"
click node_forms "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/model_forms.py"
click node_access_data "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py"
click node_lock_sync "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py"
click node_key_telemetry "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py"
click node_api "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/api.py"
click node_long_poll "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/views.py"
click node_app_router "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/urls.py"
click node_detail_views "https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/views.py"
click node_detail_templates "https://github.com/doorlockd/doorlockd-backend/tree/main/apps/doorlockdb/templates"

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_root_router,node_admin_ui,node_group_bulk,node_forms,node_lock_client toneBlue
class node_access_data,node_lock_sync,node_key_telemetry,node_sqlite toneAmber
class node_api,node_long_poll toneMint
class node_app_router,node_detail_views,node_detail_templates toneRose
class node_admin_user toneIndigo
```

## Components

### Administration

- [Project Router](https://github.com/doorlockd/doorlockd-backend/blob/main/doorlockd_backend/urls.py): `doorlockd_backend/urls.py`
- [Django Admin](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/admin.py): `apps/doorlockdb/admin.py`
- [Group Bulk Action](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/adminviews.py): `apps/doorlockdb/adminviews.py`
- [Model Forms](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/model_forms.py): `apps/doorlockdb/model_forms.py`

### Access Domain

- [People and Access Models](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py): `apps/doorlockdb/models.py`
- [Lock Sync Logic](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py): `apps/doorlockdb/models.py`
- [Key Telemetry](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/models.py): `apps/doorlockdb/models.py`

### Lock Client API

- [Lock API](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/api.py): `apps/doorlockdb/api.py`
- [Event Long Poll](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/views.py): `apps/doorlockdb/views.py`

### Web Views

- [App Router](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/urls.py): `apps/doorlockdb/urls.py`
- [Access Detail Views](https://github.com/doorlockd/doorlockd-backend/blob/main/apps/doorlockdb/views.py): `apps/doorlockdb/views.py`
- [Detail Templates](https://github.com/doorlockd/doorlockd-backend/tree/main/apps/doorlockdb/templates): `apps/doorlockdb/templates`

### Other components

- **Administrator**
- **Lock Client**
- **SQLite Database**

## Connections

- Project Router → App Router: routes requests (evidence: `doorlockd_backend/urls.py`)
- Project Router → Lock API: mounts API (evidence: `doorlockd_backend/urls.py`)
- Project Router → Access Detail Views: routes home (evidence: `doorlockd_backend/urls.py`)
- Administrator → Django Admin: manages records (evidence: `apps/doorlockdb/admin.py`)
- Django Admin → People and Access Models: queries models (evidence: `apps/doorlockdb/admin.py`)
- Django Admin → Group Bulk Action: dispatches action (evidence: `apps/doorlockdb/admin.py`)
- Django Admin → Model Forms: uses forms
- Django Admin → People and Access Models: edits records (evidence: `apps/doorlockdb/admin.py`)
- Model Forms → People and Access Models: defines fields (evidence: `apps/doorlockdb/model_forms.py`)
- App Router → Event Long Poll: routes polling (evidence: `apps/doorlockdb/urls.py`)
- App Router → Access Detail Views: routes details (evidence: `apps/doorlockdb/urls.py`)
- Access Detail Views → People and Access Models: queries access (evidence: `apps/doorlockdb/views.py`)
- Access Detail Views → Detail Templates: renders pages (evidence: `apps/doorlockdb/views.py`)
- Event Long Poll → Lock Sync Logic: reads sync state (evidence: `apps/doorlockdb/views.py`)
- Lock API → Lock Sync Logic: compares key state (evidence: `apps/doorlockdb/api.py`)
- Lock API → Key Telemetry: records reports (evidence: `apps/doorlockdb/api.py`)
- Lock API → People and Access Models: merges key metadata (evidence: `apps/doorlockdb/api.py`)
- Lock Client → Lock API: calls endpoints (evidence: `apps/doorlockdb/api.py`)
- Lock Client → Event Long Poll: requests events
- People and Access Models → SQLite Database: persists records
- Lock Sync Logic → SQLite Database: persists sync state
- Key Telemetry → SQLite Database: persists telemetry