# pesoen/4th-semester-project architecture

> Architecture diagram of the GitHub repository pesoen/4th-semester-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pesoen/4th-semester-project
- Repository: https://github.com/pesoen/4th-semester-project

## Overview

1. **Overall shape**
   - This is a Django-based IoT monitoring system split into two main Django apps: `backend` for device/data logic and `frontend` for user-facing pages.
   - Outside Django, it also includes an MQTT listener and a device simulator, so the system behaves like a small event-driven pipeline rather than a pure request/response web app.

2. **Data ingestion pipeline**
   - Smart devices publish JSON payloads to the MQTT topic `home/power`.
   - The payload includes a device identifier, power reading, and an `api_key`.
   - A separate MQTT listener process receives the message, validates the API key against Django settings, removes the secret, and forwards the data into the Django side for persistence.

3. **External runtime dependency**
   - The architecture depends on a local Mosquitto broker running on port `1883`.
   - This broker is the transport layer between devices/simulator and the server-side processing pipeline.

4. **Backend domain layer**
   - The `backend` app owns the core IoT domain: devices, measurements, states, notifications, and consumption sessions.
   - The migration history shows the data model evolved to support energy usage, pricing, manufacturing year, expected lifespan, and session tracking.
   - This is the persistence boundary for operational data.

5. **Business logic and calculations**
   - Files like `backend/measurement.py`, `backend/FetchPrice.py`, `backend/signals.py`, and `utils/rul_calculator.py` suggest the backend computes more than raw storage.
   - Likely responsibilities include converting power readings into energy/cost metrics, reacting to model events, and estimating remaining useful life or similar device-health information.

6. **Backend interfaces**
   - `backend/views.py`, `backend/urls.py`, and `backend/urls2.py` expose server-side endpoints for the application.
   - `backend/management/commands/add_measurement.py` indicates there is also a command-line path for inserting measurement data, useful for testing or maintenance.
   - `backend/admin.py` exposes the domain models in Django admin.

7. **Frontend web UI**
   - The `frontend` app contains the browser-facing interface: templates, CSS, and view logic.
   - Templates cover CRUD screens for devices, measurements, states, and notifications, plus authentication pages for login, signup, and logout.
   - This app is the presentation layer over the backend data model.

8. **User and device workflows**
   - The presence of CRUD templates and tests for “claim device” indicates users can associate devices with their account and manage device-related settings.
   - State and notification pages imply users can configure when they want to be alerted and inspect device status history.

9. **System orchestration**
   - `run_full_program.py` is the top-level launcher that starts three cooperating processes: Django, the MQTT listener, and the simulator.
   - This makes local development a coordinated multi-process setup rather than a single-server run.

10. **Device simulation**
   - `device_simulator/improved_simulator.py` acts as a synthetic IoT source that publishes fake power readings.
   - It exists to exercise the ingestion pipeline without physical hardware.

11. **Shared utilities**
   - `utils/` holds cross-cutting helpers such as the RUL calculator and general utility functions.
   - These are not tied to one app’s presentation or transport layer, which helps keep business logic reusable.

12. **Testing structure**
   - Tests are organized by feature area: claim-device flows, data models, graphing, session behavior, and URL/view coverage.
   - That structure reflects the key architectural seams: domain persistence, web endpoints, and analytics/visualization.

13. **Clear boundaries for a diagram**
   - One boundary is the **device/MQTT side**: simulator or real hardware → MQTT broker → listener.
   - The second boundary is the **Django backend**: ingest, validate, store, calculate, and expose data.
   - The third boundary is the **web frontend**: render pages and CRUD forms for users.

Main entry points: [`backend/models.py`](https://github.com/pesoen/4th-semester-project/blob/main/backend/models.py) (Domain models), [`backend/views.py`](https://github.com/pesoen/4th-semester-project/blob/main/backend/views.py) (Backend views), [`backend/measurement.py`](https://github.com/pesoen/4th-semester-project/blob/main/backend/measurement.py) (Measurement logic), [`frontend/views.py`](https://github.com/pesoen/4th-semester-project/blob/main/frontend/views.py) (Frontend views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_launcher["Program launcher<br/>orchestrator"]
  node_django["Django app<br/>web runtime<br/>[settings.py]"]
end

subgraph group_ingest["Device ingest"]
  node_mqtt_listener["MQTT listener<br/>ingest worker<br/>[mqtt_listener.py]"]
  node_broker[("Mosquitto broker<br/>mqtt broker")]
  node_simulator["Device simulator<br/>mqtt producer"]
end

subgraph group_backend["Django backend"]
  node_backend_models[("Domain models<br/>django models<br/>[models.py]")]
  node_backend_views["Backend views<br/>api/views<br/>[views.py]"]
  node_backend_urls["Backend routes<br/>urlconf<br/>[urls.py]"]
  node_backend_urls2["Extra routes<br/>urlconf<br/>[urls2.py]"]
  node_backend_signals{{"Model signals<br/>event hooks<br/>[signals.py]"}}
  node_measurement_logic["Measurement logic<br/>calc/service<br/>[measurement.py]"]
  node_price_service["Price fetcher<br/>pricing service<br/>[FetchPrice.py]"]
  node_backend_admin["Admin<br/>[admin.py]"]
  node_command_add_measurement["Add measurement<br/>management command<br/>[add_measurement.py]"]
end

subgraph group_frontend["Web frontend"]
  node_frontend_views["Frontend views<br/>page views<br/>[views.py]"]
  node_frontend_templates["Templates<br/>presentation<br/>[master.html]"]
  node_frontend_static["Static styles<br/>presentation assets<br/>[style.css]"]
end

subgraph group_shared["Shared utilities"]
  node_shared_utils["Utility helpers<br/>[utils.py]"]
  node_rul_calculator{{"RUL calculator<br/>health metric<br/>[rul_calculator.py]"}}
end

node_launcher -->|"starts"| node_django
node_launcher -->|"starts"| node_mqtt_listener
node_launcher -->|"starts"| node_simulator
node_simulator -->|"publishes"| node_broker
node_broker -->|"delivers"| node_mqtt_listener
node_mqtt_listener -->|"forwards"| node_backend_views
node_backend_views -->|"stores"| node_backend_models
node_backend_signals -->|"reacts to"| node_backend_models
node_measurement_logic -->|"writes"| node_backend_models
node_measurement_logic -->|"uses"| node_price_service
node_measurement_logic -->|"uses"| node_shared_utils
node_measurement_logic -->|"uses"| node_rul_calculator
node_backend_views -->|"exposed by"| node_backend_urls
node_backend_views -->|"exposed by"| node_backend_urls2
node_backend_admin -->|"registers"| node_backend_models
node_command_add_measurement -->|"inserts"| node_backend_models
node_frontend_views -->|"renders"| node_frontend_templates
node_frontend_views -->|"reads"| node_backend_models
node_frontend_views -->|"uses"| node_backend_views
node_frontend_templates -->|"styles with"| node_frontend_static
node_django -->|"includes"| node_backend_urls
node_django -->|"includes"| node_frontend_views

click node_launcher "https://github.com/pesoen/4th-semester-project/blob/main/run_full_program.py"
click node_django "https://github.com/pesoen/4th-semester-project/blob/main/IoT_washing_machine/settings.py"
click node_mqtt_listener "https://github.com/pesoen/4th-semester-project/blob/main/backend/mqtt_listener.py"
click node_simulator "https://github.com/pesoen/4th-semester-project/blob/main/device_simulator/improved_simulator.py"
click node_backend_models "https://github.com/pesoen/4th-semester-project/blob/main/backend/models.py"
click node_backend_views "https://github.com/pesoen/4th-semester-project/blob/main/backend/views.py"
click node_backend_urls "https://github.com/pesoen/4th-semester-project/blob/main/backend/urls.py"
click node_backend_urls2 "https://github.com/pesoen/4th-semester-project/blob/main/backend/urls2.py"
click node_backend_signals "https://github.com/pesoen/4th-semester-project/blob/main/backend/signals.py"
click node_measurement_logic "https://github.com/pesoen/4th-semester-project/blob/main/backend/measurement.py"
click node_price_service "https://github.com/pesoen/4th-semester-project/blob/main/backend/FetchPrice.py"
click node_backend_admin "https://github.com/pesoen/4th-semester-project/blob/main/backend/admin.py"
click node_command_add_measurement "https://github.com/pesoen/4th-semester-project/blob/main/backend/management/commands/add_measurement.py"
click node_frontend_views "https://github.com/pesoen/4th-semester-project/blob/main/frontend/views.py"
click node_frontend_templates "https://github.com/pesoen/4th-semester-project/blob/main/frontend/templates/master.html"
click node_frontend_static "https://github.com/pesoen/4th-semester-project/blob/main/frontend/static/style.css"
click node_shared_utils "https://github.com/pesoen/4th-semester-project/blob/main/utils/utils.py"
click node_rul_calculator "https://github.com/pesoen/4th-semester-project/blob/main/utils/rul_calculator.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_launcher,node_django toneBlue
class node_mqtt_listener,node_broker,node_simulator toneAmber
class node_backend_models,node_backend_views,node_backend_urls,node_backend_urls2,node_backend_signals,node_measurement_logic,node_price_service,node_backend_admin,node_command_add_measurement toneMint
class node_frontend_views,node_frontend_templates,node_frontend_static toneRose
class node_shared_utils,node_rul_calculator toneIndigo
```

## Components

### Runtime orchestration

Processes started together for local development and end-to-end device simulation.

- [Program launcher](https://github.com/pesoen/4th-semester-project/blob/main/run_full_program.py): orchestrator · Starts Django, MQTT listener, and simulator together. · `run_full_program.py`
- [Django app](https://github.com/pesoen/4th-semester-project/blob/main/IoT_washing_machine/settings.py): web runtime · Main Django project configuration and request routing. · `IoT_washing_machine/settings.py`

### Device ingest

MQTT transport and device-side message production.

- [MQTT listener](https://github.com/pesoen/4th-semester-project/blob/main/backend/mqtt_listener.py): ingest worker · Receives MQTT payloads, validates them, and forwards measurements into Django. · `backend/mqtt_listener.py`
- **Mosquitto broker**: mqtt broker · Local message transport on port 1883 between devices and listener.
- [Device simulator](https://github.com/pesoen/4th-semester-project/blob/main/device_simulator/improved_simulator.py): mqtt producer · Publishes synthetic power readings to the MQTT topic. · `device_simulator/improved_simulator.py`

### Django backend

Core domain, persistence, calculations, and server-side endpoints.

- [Domain models](https://github.com/pesoen/4th-semester-project/blob/main/backend/models.py): django models · Devices, measurements, states, notifications, and sessions. · `backend/models.py`
- [Backend views](https://github.com/pesoen/4th-semester-project/blob/main/backend/views.py): api/views · Server-side endpoints for backend-facing application flows. · `backend/views.py`
- [Backend routes](https://github.com/pesoen/4th-semester-project/blob/main/backend/urls.py): urlconf · Primary backend URL mappings. · `backend/urls.py`
- [Extra routes](https://github.com/pesoen/4th-semester-project/blob/main/backend/urls2.py): urlconf · Secondary backend URL mappings. · `backend/urls2.py`
- [Model signals](https://github.com/pesoen/4th-semester-project/blob/main/backend/signals.py): event hooks · React to model changes and trigger derived behavior. · `backend/signals.py`
- [Measurement logic](https://github.com/pesoen/4th-semester-project/blob/main/backend/measurement.py): calc/service · Turns raw power readings into domain measurements and derived values. · `backend/measurement.py`
- [Price fetcher](https://github.com/pesoen/4th-semester-project/blob/main/backend/FetchPrice.py): pricing service · Obtains electricity price data for cost calculations. · `backend/FetchPrice.py`
- [Admin](https://github.com/pesoen/4th-semester-project/blob/main/backend/admin.py): django admin · Registers core domain models for Django admin use. · `backend/admin.py`
- [Add measurement](https://github.com/pesoen/4th-semester-project/blob/main/backend/management/commands/add_measurement.py): management command · CLI entry point for inserting measurement data. · `backend/management/commands/add_measurement.py`

### Web frontend

Browser-facing CRUD and auth pages.

- [Frontend views](https://github.com/pesoen/4th-semester-project/blob/main/frontend/views.py): page views · Renders the user-facing pages and CRUD workflows. · `frontend/views.py`
- [Templates](https://github.com/pesoen/4th-semester-project/blob/main/frontend/templates/master.html): presentation · HTML screens for devices, measurements, states, notifications, and auth. · `frontend/templates/master.html`
- [Static styles](https://github.com/pesoen/4th-semester-project/blob/main/frontend/static/style.css): presentation assets · Shared CSS for the browser UI. · `frontend/static/style.css`

### Shared utilities

Cross-cutting helpers used by backend logic and calculations.

- [Utility helpers](https://github.com/pesoen/4th-semester-project/blob/main/utils/utils.py): helpers · Reusable helper functions and RUL calculations. · `utils/utils.py`
- [RUL calculator](https://github.com/pesoen/4th-semester-project/blob/main/utils/rul_calculator.py): health metric · Estimates remaining useful life or similar device-health metrics. · `utils/rul_calculator.py`

## Connections

- Program launcher → Django app: starts · Launches the Django application runtime.
- Program launcher → MQTT listener: starts · Launches the MQTT ingestion worker.
- Program launcher → Device simulator: starts · Launches the synthetic device source.
- Device simulator → Mosquitto broker: publishes · Sends power payloads to the MQTT topic.
- Mosquitto broker → MQTT listener: delivers · Transports device messages to the listener.
- MQTT listener → Backend views: forwards · Hands validated payloads into the Django side for persistence.
- Backend views → Domain models: stores · Creates and updates operational records.
- Model signals → Domain models: reacts to · Triggers logic when domain records change.
- Measurement logic → Domain models: writes · Persists measurements and derived values.
- Measurement logic → Price fetcher: uses · Combines readings with electricity pricing.
- Measurement logic → Utility helpers: uses · Shares calculation helpers.
- Measurement logic → RUL calculator: uses · Feeds device history into health estimation.
- Backend views → Backend routes: exposed by · Primary request routing for backend endpoints.
- Backend views → Extra routes: exposed by · Secondary backend routes.
- Admin → Domain models: registers · Makes domain models available in admin.
- Add measurement → Domain models: inserts · CLI path for adding measurement records.
- Frontend views → Templates: renders · Serves HTML pages and forms.
- Frontend views → Domain models: reads · Loads domain data for the UI.
- Frontend views → Backend views: uses · Relies on backend-side application flows.
- Templates → Static styles: styles with · Uses shared CSS for presentation.
- Django app → Backend routes: includes · Project routing includes backend URLs.
- Django app → Frontend views: includes · Project routing includes frontend app pages.
