# mushfiq/rssi-system architecture

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

- Interactive diagram: https://gitdiagram.com/mushfiq/rssi-system
- Repository: https://github.com/mushfiq/rssi-system

## Overview

This repository is a three-tier RSSI indoor-localization system with a clear split between acquisition/processing, server-side persistence/API, and mobile visualization.

1. **End-to-end data flow**
   Physical receivers capture RSSI from a watch/transmitter, the Java application ingests those readings, runs localization algorithms to compute position, then posts results and metadata to the REST API. The Python/Django API stores records in MongoDB and exposes them to clients, including the Android app, which fetches and renders the latest watch position.

2. **`comReader`: the Java localization hub**
   This is the central processing application. It combines device I/O, algorithm execution, data persistence, and a Swing desktop UI for monitoring/configuration. It is the main boundary where raw RSSI data becomes localization output.

3. **Data acquisition layer in `comReader`**
   The `data` package contains readers for serial/COM input and file-based input, plus runnable wrappers and writer abstractions. This suggests the system can operate live from hardware or replay from files for testing. `Reading`, `WatchPositionData`, and `Controller` are the main in-memory data carriers/control points.

4. **Localization algorithm layer in `comReader`**
   The `algorithm` package holds multiple strategies: proximity-based, probability-based, and random, with a shared `PositionLocalizationAlgorithm` abstraction. Supporting components include Kalman filtering, convex hull math, probability maps, and weight functions. This layer is where RSSI readings are transformed into x/y estimates.

5. **Map and receiver model layer in `comReader`**
   `components` and `dao` represent the map/receiver domain and data access. There are hardcoded DAO implementations as well as Mongo-backed DAOs, indicating the application can load map/receiver definitions from either static config or the database. This is the boundary between localization logic and environment configuration.

6. **Desktop UI in `comReader`**
   The `gui` package is a full Swing client for operators: map panels, receiver panels, parameter controls, status, dialogs, and custom views. It likely visualizes live receivers, selected maps, and algorithm state while allowing map/receiver setup and parameter tuning.

7. **Outbound integration from `comReader` to the API**
   The `rest` package and REST-related tests indicate that `comReader` also acts as a client to the server. It uploads maps, receivers, and computed watch positions to the Django API, making the Java app the producer of canonical localization data.

8. **`RESTApi`: Django/Python backend**
   The `RESTApi/restApp` project is the persistence and service layer. It uses Django/WSGI, REST-style resources/views, serializers, and middleware/auth code. This is the system’s backend boundary for storage and retrieval rather than computation.

9. **MongoDB as the persistence store**
   The API’s models/resources and the Mongo-specific scripts/tests indicate MongoDB is the primary database. The server persists maps, receiver records, and watch positions there, and the Java app has Mongo-aware DAO/wrapper code for some shared entities.

10. **Server-side test and support tooling**
    The API includes dummy data, setup scripts, and tests for map, receiver, image retrieval, and watch records. This suggests the backend is exercised as a data service with predefined fixtures rather than complex business logic.

11. **`AndroidApp`: mobile visualization client**
    The Android app is a lightweight consumer of the API. Its code centers on `WatchUserActivity`, a custom `MapImageView`, and simple data objects/parsers for map/receiver/position records. It is primarily a read/display client for the latest localization state.

12. **Android app data flow**
    `RestMapService` appears to fetch remote JSON from the REST API, `ResponseParser` converts responses into local records, and the UI renders the position on top of a map image. The app depends on the backend for map geometry and live position updates rather than computing localization itself.

13. **Cross-cutting technologies and boundaries**
    The project spans Java desktop/Swing, Android, and Python/Django REST services, with MongoDB underneath and hardware/serial input at the edge. Third-party jars in `comReader/main/resources` and the Android support library indicate the repo is self-contained and designed around those runtime boundaries.

14. **What to emphasize in an architecture diagram**
    The main boxes should be: hardware receivers/watch input → `comReader` ingestion and algorithms → REST API → MongoDB → Android client, with the `comReader` Swing UI and backend admin/test scripts shown as auxiliary paths around the core pipeline.

Main entry points: [`comReader/main/data/Controller.java`](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/Controller.java) (Controller), [`comReader/main/components/RoomMap.java`](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/components/RoomMap.java) (Map Models), [`RESTApi/restApp/views.py`](https://github.com/mushfiq/rssi-system/blob/master/RESTApi/restApp/views.py) (Django API), [`comReader/main/algorithm/PositionLocalizationAlgorithm.java`](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/PositionLocalizationAlgorithm.java) (Algorithm API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Acquisition"]
  node_receivers["Receivers<br/>hardware source"]
end

subgraph group_core["Localization Core"]
  node_com_port_reader["COM Reader<br/>live ingest"]
  node_file_reader["File Replay<br/>offline ingest"]
  node_controller["Controller<br/>orchestration<br/>[Controller.java]"]
  node_reading["Reading<br/>sensor record<br/>[Reading.java]"]
  node_alg_api["Algorithm API<br/>localization interface"]
  node_prob_algo["Probability Algo<br/>localization strategy"]
  node_prox_algo["Proximity Algo<br/>localization strategy"]
  node_kalman["Kalman Filter<br/>signal filter<br/>[KalmanFilter.java]"]
  node_env_map["Map Models<br/>environment model<br/>[RoomMap.java]"]
  node_map_dao["Map DAO<br/>data access<br/>[MapDAO.java]"]
  node_receiver_dao["Receiver DAO<br/>data access<br/>[ReceiverDAO.java]"]
  node_desktop_ui["Desktop UI<br/>Swing client<br/>[MainFrame.java]"]
  node_rest_client["REST Client<br/>outbound sync"]
end

subgraph group_server["Backend"]
  node_django_api["Django API<br/>web backend<br/>[views.py]"]
  node_models["Server Models<br/>domain schema<br/>[models.py]"]
  node_mongo_db[("MongoDB<br/>database")]
end

subgraph group_mobile["Mobile Client"]
  node_android_service["REST Service<br/>mobile fetch"]
  node_android_parser["Response Parser<br/>mobile decode"]
  node_map_view["Map View<br/>UI render<br/>[MapImageView.java]"]
  node_watch_activity["Watch Screen<br/>Android screen"]
end

node_receivers -->|"RSSI stream"| node_com_port_reader
node_com_port_reader -->|"raw readings"| node_controller
node_file_reader -->|"replay data"| node_controller
node_controller -->|"normalize"| node_reading
node_controller -->|"select strategy"| node_alg_api
node_alg_api -->|"impl"| node_prob_algo
node_alg_api -->|"impl"| node_prox_algo
node_prob_algo -->|"smooth"| node_kalman
node_prox_algo -->|"smooth"| node_kalman
node_prob_algo -->|"uses"| node_env_map
node_prox_algo -->|"uses"| node_env_map
node_env_map -->|"load maps"| node_map_dao
node_env_map -->|"load receivers"| node_receiver_dao
node_controller -->|"status"| node_desktop_ui
node_desktop_ui -->|"configure"| node_map_dao
node_desktop_ui -->|"configure"| node_receiver_dao
node_controller -->|"publish"| node_rest_client
node_rest_client -->|"REST calls"| node_django_api
node_django_api -->|"persist"| node_models
node_models -->|"store"| node_mongo_db
node_android_service -->|"fetch"| node_django_api
node_android_service -->|"json"| node_android_parser
node_android_parser -->|"render data"| node_map_view
node_map_view -->|"embed"| node_watch_activity
node_django_api -->|"query"| node_mongo_db

click node_com_port_reader "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/COMPortDataReader.java"
click node_file_reader "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/FileDataReader.java"
click node_controller "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/Controller.java"
click node_reading "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/Reading.java"
click node_alg_api "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/PositionLocalizationAlgorithm.java"
click node_prob_algo "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/ProbabilityBasedAlgorithm.java"
click node_prox_algo "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/ProximityAlgorithm.java"
click node_kalman "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/filter/KalmanFilter.java"
click node_env_map "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/components/RoomMap.java"
click node_map_dao "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/dao/MapDAO.java"
click node_receiver_dao "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/dao/ReceiverDAO.java"
click node_desktop_ui "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/gui/MainFrame.java"
click node_rest_client "https://github.com/mushfiq/rssi-system/blob/master/comReader/main/rest/MongoDatabaseReceiverWrapper.java"
click node_django_api "https://github.com/mushfiq/rssi-system/blob/master/RESTApi/restApp/views.py"
click node_models "https://github.com/mushfiq/rssi-system/blob/master/RESTApi/restApp/models.py"
click node_android_service "https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/services/RestMapService.java"
click node_android_parser "https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/dataobjects/ResponseParser.java"
click node_map_view "https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/userInterface/MapImageView.java"
click node_watch_activity "https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/userInterface/WatchUserActivity.java"

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_receivers toneBlue
class node_com_port_reader,node_file_reader,node_controller,node_reading,node_alg_api,node_prob_algo,node_prox_algo,node_kalman,node_env_map,node_map_dao,node_receiver_dao,node_desktop_ui,node_rest_client toneAmber
class node_django_api,node_models,node_mongo_db toneMint
class node_android_service,node_android_parser,node_map_view,node_watch_activity toneRose
```

## Components

### Acquisition

Hardware ingress and live/file RSSI ingestion

- **Receivers**: hardware source · Physical RSSI receivers capture watch signal strength

### Localization Core

Java processing, algorithms, UI, and outbound sync

- [COM Reader](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/COMPortDataReader.java): live ingest · Reads live serial/COM RSSI data from hardware · `comReader/main/data/COMPortDataReader.java`
- [File Replay](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/FileDataReader.java): offline ingest · Replays RSSI input from files for testing or simulation · `comReader/main/data/FileDataReader.java`
- [Controller](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/Controller.java): orchestration · Coordinates readers, processing, and output flow · `comReader/main/data/Controller.java`
- [Reading](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/data/Reading.java): sensor record · In-memory RSSI reading model used across the pipeline · `comReader/main/data/Reading.java`
- [Algorithm API](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/PositionLocalizationAlgorithm.java): localization interface · Shared abstraction for position localization strategies · `comReader/main/algorithm/PositionLocalizationAlgorithm.java`
- [Probability Algo](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/ProbabilityBasedAlgorithm.java): localization strategy · Probability-based localization with maps and weighting · `comReader/main/algorithm/ProbabilityBasedAlgorithm.java`
- [Proximity Algo](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/ProximityAlgorithm.java): localization strategy · Distance/proximity-oriented localization strategy · `comReader/main/algorithm/ProximityAlgorithm.java`
- [Kalman Filter](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/algorithm/filter/KalmanFilter.java): signal filter · Smooths noisy RSSI or position estimates · `comReader/main/algorithm/filter/KalmanFilter.java`
- [Map Models](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/components/RoomMap.java): environment model · Rooms, receivers, and geometry used by localization · `comReader/main/components/RoomMap.java`
- [Map DAO](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/dao/MapDAO.java): data access · Loads maps from hardcoded or Mongo-backed sources · `comReader/main/dao/MapDAO.java`
- [Receiver DAO](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/dao/ReceiverDAO.java): data access · Loads receiver definitions from hardcoded or Mongo-backed sources · `comReader/main/dao/ReceiverDAO.java`
- [Desktop UI](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/gui/MainFrame.java): Swing client · Operator UI for map, receiver, and parameter management · `comReader/main/gui/MainFrame.java`
- [REST Client](https://github.com/mushfiq/rssi-system/blob/master/comReader/main/rest/MongoDatabaseReceiverWrapper.java): outbound sync · Uploads maps, receivers, and computed positions to the API · `comReader/main/rest/MongoDatabaseReceiverWrapper.java`

### Backend

Django API and Mongo persistence

- [Django API](https://github.com/mushfiq/rssi-system/blob/master/RESTApi/restApp/views.py): web backend · REST service layer for persistence and retrieval · `RESTApi/restApp/views.py`
- [Server Models](https://github.com/mushfiq/rssi-system/blob/master/RESTApi/restApp/models.py): domain schema · Backend documents, serializers, and resources · `RESTApi/restApp/models.py`
- **MongoDB**: database · Primary persistence store for maps, receivers, and watch positions

### Mobile Client

Android visualization client

- [REST Service](https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/services/RestMapService.java): mobile fetch · Android client service fetching remote map and position data · `AndroidApp/src/services/RestMapService.java`
- [Response Parser](https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/dataobjects/ResponseParser.java): mobile decode · Converts API responses into local records · `AndroidApp/src/dataobjects/ResponseParser.java`
- [Map View](https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/userInterface/MapImageView.java): UI render · Renders the map image and watch position overlay · `AndroidApp/src/userInterface/MapImageView.java`
- [Watch Screen](https://github.com/mushfiq/rssi-system/blob/master/AndroidApp/src/userInterface/WatchUserActivity.java): Android screen · Main mobile screen for viewing the latest watch position · `AndroidApp/src/userInterface/WatchUserActivity.java`

## Connections

- Receivers → COM Reader: RSSI stream · Hardware signal readings enter the Java ingestion layer
- COM Reader → Controller: raw readings · Live input is handed to the orchestration layer
- File Replay → Controller: replay data · Offline input is also routed through the controller
- Controller → Reading: normalize · Controller manages in-memory reading records
- Controller → Algorithm API: select strategy · Processing chooses a localization algorithm implementation
- Algorithm API → Probability Algo: impl · Probability-based strategy
- Algorithm API → Proximity Algo: impl · Proximity-based strategy
- Probability Algo → Kalman Filter: smooth · Probability estimates are filtered before output
- Proximity Algo → Kalman Filter: smooth · Proximity estimates can also be filtered
- Probability Algo → Map Models: uses · Localization depends on map and receiver geometry
- Proximity Algo → Map Models: uses · Proximity localization depends on environment model
- Map Models → Map DAO: load maps · Environment definitions come from DAO-backed storage
- Map Models → Receiver DAO: load receivers · Receiver definitions come from DAO-backed storage
- Controller → Desktop UI: status · Live state is shown in the Swing operator UI
- Desktop UI → Map DAO: configure · UI supports loading and editing maps
- Desktop UI → Receiver DAO: configure · UI supports loading and editing receivers
- Controller → REST Client: publish · Computed positions and metadata are posted to the server
- REST Client → Django API: REST calls · Java client synchronizes data with the backend API
- Django API → Server Models: persist · Views/resources operate on backend documents and serializers
- Server Models → MongoDB: store · Backend writes canonical data to MongoDB
- REST Service → Django API: fetch · Android retrieves maps and watch position data
- REST Service → Response Parser: json · Responses are decoded into local records
- Response Parser → Map View: render data · Parsed records drive the display layer
- Map View → Watch Screen: embed · Custom map view is hosted by the main activity
- Django API → MongoDB: query · Backend serves data from the database