# bytecod3/ear-tag architecture

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

- Interactive diagram: https://gitdiagram.com/bytecod3/ear-tag
- Repository: https://github.com/bytecod3/ear-tag

## Overview

This repository is an in-progress LoRa cattle ear-tag system: an onboard device is intended to collect motion and GPS data, send it through a base station, and present locations to a farmer. The sampled tag firmware contains MPU6050 processing, GPS sampling, Wi-Fi provisioning, and an HTTP upload routine; the README also describes LoRa transmission. The base station currently receives and prints packets, while the web server stores location posts and provides a live-update mechanism. Firmware control flow and browser-side wiring are only partly visible, so those links are not assumed.

Main entry points: [`web-app/server.js`](https://github.com/bytecod3/ear-tag/blob/main/web-app/server.js) (HTTP and WebSocket server), [`firmware/onboard-device/src/main.cpp`](https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/main.cpp) (Onboard firmware), [`firmware/onboard-device/src/mpu.cpp`](https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/mpu.cpp) (MPU6050 processing), [`firmware/base-station/src/main.cpp`](https://github.com/bytecod3/ear-tag/blob/main/firmware/base-station/src/main.cpp) (LoRa receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tag["Ear-tag firmware"]
  node_onboard["Onboard firmware<br/>[main.cpp]"]
  node_imu["MPU6050 processing<br/>[mpu.cpp]"]
  node_gps["GPS sampling<br/>[main.cpp]"]
end

subgraph group_radio["Radio station"]
  node_base["LoRa receiver<br/>[main.cpp]"]
end

subgraph group_web["Web platform"]
  node_server["HTTP and WebSocket server<br/>[server.js]"]
  node_store[("MongoDB locations")]
  node_page["Map page<br/>[index.ejs]"]
  node_map["Map client<br/>[map.js]"]
end

subgraph group_sensors["Tag sensors"]
  node_tag_sensor["MPU6050"]
  node_gps_sensor["GPS module"]
end

node_farmer(("Farmer"))
node_browser(("Farmer device"))

node_onboard -->|"uses"| node_imu
node_imu -->|"reads I2C"| node_tag_sensor
node_onboard -->|"samples"| node_gps
node_gps -->|"reads coordinates"| node_gps_sensor
node_onboard -.->|"sends LoRa"| node_base
node_onboard -.->|"POSTs location"| node_server
node_server -->|"saves locations"| node_store
node_server -->|"queries locations"| node_store
node_server -->|"renders"| node_page
node_server -->|"broadcasts updates"| node_browser
node_farmer -->|"views map"| node_browser
node_browser -.->|"uses"| node_map

click node_onboard "https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/main.cpp"
click node_imu "https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/mpu.cpp"
click node_gps "https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/main.cpp"
click node_base "https://github.com/bytecod3/ear-tag/blob/main/firmware/base-station/src/main.cpp"
click node_server "https://github.com/bytecod3/ear-tag/blob/main/web-app/server.js"
click node_page "https://github.com/bytecod3/ear-tag/blob/main/web-app/views/index.ejs"
click node_map "https://github.com/bytecod3/ear-tag/blob/main/web-app/public/js/map.js"

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_onboard,node_imu,node_gps toneBlue
class node_base toneAmber
class node_server,node_store,node_page,node_map toneMint
class node_tag_sensor,node_gps_sensor toneRose
class node_farmer,node_browser toneIndigo
```

## Components

### Ear-tag firmware

- [Onboard firmware](https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/main.cpp): `firmware/onboard-device/src/main.cpp`
- [MPU6050 processing](https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/mpu.cpp): `firmware/onboard-device/src/mpu.cpp`
- [GPS sampling](https://github.com/bytecod3/ear-tag/blob/main/firmware/onboard-device/src/main.cpp): `firmware/onboard-device/src/main.cpp`

### Radio station

- [LoRa receiver](https://github.com/bytecod3/ear-tag/blob/main/firmware/base-station/src/main.cpp): `firmware/base-station/src/main.cpp`

### Web platform

- [HTTP and WebSocket server](https://github.com/bytecod3/ear-tag/blob/main/web-app/server.js): `web-app/server.js`
- **MongoDB locations**
- [Map page](https://github.com/bytecod3/ear-tag/blob/main/web-app/views/index.ejs): `web-app/views/index.ejs`
- [Map client](https://github.com/bytecod3/ear-tag/blob/main/web-app/public/js/map.js): `web-app/public/js/map.js`

### Tag sensors

- **MPU6050**
- **GPS module**

### Other components

- **Farmer**
- **Farmer device**

## Connections

- Onboard firmware → MPU6050 processing: uses (evidence: `firmware/onboard-device/src/main.cpp`)
- MPU6050 processing → MPU6050: reads I2C (evidence: `firmware/onboard-device/src/mpu.cpp`)
- Onboard firmware → GPS sampling: samples (evidence: `firmware/onboard-device/src/main.cpp`)
- GPS sampling → GPS module: reads coordinates (evidence: `firmware/onboard-device/src/main.cpp`)
- Onboard firmware → LoRa receiver: sends LoRa (evidence: `README.md`)
- Onboard firmware → HTTP and WebSocket server: POSTs location
- HTTP and WebSocket server → MongoDB locations: saves locations (evidence: `web-app/server.js`)
- HTTP and WebSocket server → MongoDB locations: queries locations (evidence: `web-app/server.js`)
- HTTP and WebSocket server → Map page: renders (evidence: `web-app/server.js`)
- HTTP and WebSocket server → Farmer device: broadcasts updates (evidence: `web-app/server.js`)
- Farmer → Farmer device: views map (evidence: `README.md`)
- Farmer device → Map client: uses