# abarnamurugan-commits/automated-railway-level-crossing-system-arduino architecture

> Architecture diagram of the GitHub repository abarnamurugan-commits/automated-railway-level-crossing-system-arduino, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino
- Repository: https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino

## Overview

The primary product is an Arduino railway-crossing controller: simulated arrival/departure buttons drive a six-state safety cycle, which controls the gate and warnings. A separate Python/React demo mirrors that cycle, exposes status and logs, and can run a simulated crossing; the README says it is not live-connected to the circuit. Hardware relationships are documented in the README; software relationships are supported by the sampled source. The Arduino sketch was not sampled, so its internal implementation is represented only at the documented subsystem level.

Main entry points: [`backend/app/main.py`](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/main.py) (Demo API), [`src/railway_crossing.ino`](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino) (Crossing controller), [`frontend/src/App.jsx`](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/frontend/src/App.jsx) (Status and logs view), [`backend/app/state_machine.py`](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/state_machine.py) (Crossing state machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Crossing hardware"]
  node_firmware["Crossing controller"]
  node_gate["Servo gate"]
  node_warnings["LEDs and buzzer"]
  node_display["LCD and serial"]
end

subgraph group_backend["Demo backend"]
  node_api["Demo API<br/>[main.py]"]
  node_machine["Crossing state machine<br/>[state_machine.py]"]
  node_logs[("Log storage<br/>[db.py]")]
  node_socket["Dashboard connection<br/>[main.py]"]
end

subgraph group_dashboard["Web dashboard"]
  node_dashboard["Status and logs view<br/>[App.jsx]"]
end

node_buttons(("Train buttons"))
node_operator(("Dashboard user"))

node_buttons -->|"signal arrival/departure"| node_firmware
node_firmware -->|"positions gate"| node_gate
node_firmware -->|"controls warnings"| node_warnings
node_firmware -->|"reports status"| node_display
node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests status/logs"| node_api
node_dashboard -->|"starts demo"| node_api
node_api -->|"handles crossing events"| node_machine
node_api -->|"initializes and fetches logs"| node_logs
node_machine -->|"calls log callback"| node_api
node_api -->|"writes crossing events"| node_logs
node_api -->|"broadcasts updates"| node_socket
node_socket -->|"streams status"| node_dashboard
node_api -->|"reads snapshot"| node_machine

click node_firmware "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino"
click node_gate "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino"
click node_warnings "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino"
click node_display "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino"
click node_api "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/main.py"
click node_machine "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/state_machine.py"
click node_logs "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/db.py"
click node_socket "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/main.py"
click node_dashboard "https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/frontend/src/App.jsx"

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_firmware,node_gate,node_warnings,node_display,node_operator toneBlue
class node_api,node_machine,node_logs,node_socket toneAmber
class node_dashboard toneMint
class node_buttons toneIndigo
```

## Components

### Crossing hardware

- [Crossing controller](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino): `src/railway_crossing.ino`
- [Servo gate](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino): `src/railway_crossing.ino`
- [LEDs and buzzer](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino): `src/railway_crossing.ino`
- [LCD and serial](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/src/railway_crossing.ino): `src/railway_crossing.ino`

### Demo backend

- [Demo API](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/main.py): `backend/app/main.py`
- [Crossing state machine](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/state_machine.py): `backend/app/state_machine.py`
- [Log storage](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/db.py): `backend/app/db.py`
- [Dashboard connection](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/backend/app/main.py): `backend/app/main.py`

### Web dashboard

- [Status and logs view](https://github.com/abarnamurugan-commits/automated-railway-level-crossing-system-arduino/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Other components

- **Train buttons**
- **Dashboard user**

## Connections

- Train buttons → Crossing controller: signal arrival/departure (evidence: `README.md`)
- Crossing controller → Servo gate: positions gate (evidence: `README.md`)
- Crossing controller → LEDs and buzzer: controls warnings (evidence: `README.md`)
- Crossing controller → LCD and serial: reports status (evidence: `README.md`)
- Dashboard user → Status and logs view: uses (evidence: `frontend/src/App.jsx`)
- Status and logs view → Demo API: requests status/logs (evidence: `frontend/src/App.jsx`)
- Status and logs view → Demo API: starts demo (evidence: `frontend/src/App.jsx`)
- Demo API → Crossing state machine: handles crossing events (evidence: `backend/app/main.py`)
- Demo API → Log storage: initializes and fetches logs (evidence: `backend/app/main.py`)
- Crossing state machine → Demo API: calls log callback (evidence: `backend/app/state_machine.py`)
- Demo API → Log storage: writes crossing events (evidence: `backend/app/main.py`)
- Demo API → Dashboard connection: broadcasts updates (evidence: `backend/app/main.py`)
- Dashboard connection → Status and logs view: streams status (evidence: `frontend/src/App.jsx`)
- Demo API → Crossing state machine: reads snapshot (evidence: `backend/app/main.py`)
