# conductors-senior-project-rit/full-stack-web-app architecture

> Architecture diagram of the GitHub repository conductors-senior-project-rit/full-stack-web-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/conductors-senior-project-rit/full-stack-web-app
- Repository: https://github.com/conductors-senior-project-rit/full-stack-web-app

## Overview

TrackSense is a web application for viewing train-station activity and managing train records. Users authenticate in the web client, then access role-protected record data and verification screens; volunteers can review records and assign symbols or locomotive numbers. The backend tree also indicates station reporting/status, user preferences, and notification capabilities. The supplied server excerpt is commented out, so it does not establish live route registration; connections below are limited to calls shown in sampled source or responsibilities documented in the tree and excerpts.

Main entry points: [`backend/src/service/user_service.py`](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/user_service.py) (User service), [`backend/src/service/record_service.py`](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/record_service.py) (Record service), [`backend/src/api/volunteer_handler.py`](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/volunteer_handler.py) (Volunteer endpoints), [`backend/src/service/station_service.py`](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/station_service.py) (Station service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_app["App routes<br/>[App.js]"]
  node_authctx["Auth context<br/>[AuthContext.js]"]
  node_dataui["Record screens<br/>[Data.js]"]
  node_verifyui["Verification screens<br/>[VerifyEOT.js]"]
  node_stationui["Station pages<br/>[Station.js]"]
end

subgraph group_api["Backend API"]
  node_userapi["User endpoints<br/>[user_api.py]"]
  node_prefsapi["Preference endpoints"]
  node_volunteer["Volunteer endpoints"]
  node_signalapi["Signal updates"]
  node_stationapi["Station endpoints<br/>[station_auth.py]"]
  node_onlineapi["Station status<br/>[station_online.py]"]
  node_recordapi["Record endpoints"]
  node_timeapi["Recent activity<br/>[time_frame_pull.py]"]
  node_notifyapi["Notification endpoints"]
end

subgraph group_services["Domain services"]
  node_recordservice["Record service<br/>[record_service.py]"]
  node_userservice["User service<br/>[user_service.py]"]
  node_stationservice["Station service<br/>[station_service.py]"]
  node_symbolservice["Symbol service<br/>[symbol_service.py]"]
end

subgraph group_data["Persistence"]
  node_recordrepo["Record repositories<br/>[record_repo.py]"]
  node_userrepo["User repository<br/>[user_repo.py]"]
  node_stationrepo["Station repository<br/>[station_repo.py]"]
  node_symbolrepo["Symbol repository<br/>[symbol_repo.py]"]
  node_ormrepo["ORM repository core<br/>[repository.py]"]
end

node_browser(("Browser user"))
node_db[("SQL database<br/>[database.py]")]
node_pushover["Pushover"]
node_email["Email delivery"]

node_browser -->|"uses"| node_app
node_app -->|"provides auth"| node_authctx
node_authctx -->|"checks role"| node_userapi
node_dataui -->|"requests records"| node_recordapi
node_verifyui -->|"requests verification"| node_volunteer
node_stationui -->|"requests station"| node_stationapi
node_volunteer -->|"loads and verifies"| node_recordservice
node_volunteer -->|"manages symbols"| node_symbolservice
node_signalapi -->|"updates record"| node_recordservice
node_recordservice -->|"queries and writes"| node_recordrepo
node_recordrepo -->|"uses ORM core"| node_ormrepo
node_userapi -->|"handles accounts"| node_userservice
node_prefsapi -->|"handles preferences"| node_userservice
node_userservice -->|"reads and writes"| node_userrepo
node_userservice -->|"lists stations"| node_stationrepo
node_userservice -->|"sends account mail"| node_email
node_stationapi -->|"handles station auth"| node_stationservice
node_onlineapi -->|"updates status"| node_stationservice
node_stationservice -->|"reads and writes"| node_stationrepo
node_symbolservice -->|"reads and writes"| node_symbolrepo
node_recordapi -->|"collates records"| node_recordservice
node_timeapi -->|"pulls activity"| node_recordservice
node_ormrepo -->|"queries and flushes"| node_db
node_notifyapi -->|"sends alert"| node_pushover

click node_app "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/App.js"
click node_authctx "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/AuthContext.js"
click node_dataui "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/Data.js"
click node_verifyui "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/VerifyEOT.js"
click node_stationui "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/Station.js"
click node_userapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/user_api.py"
click node_prefsapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/user_preferences_api.py"
click node_volunteer "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/volunteer_handler.py"
click node_signalapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/signal_update_handler.py"
click node_stationapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/station_auth.py"
click node_onlineapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/station_online.py"
click node_recordapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/record_collation.py"
click node_timeapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/time_frame_pull.py"
click node_notifyapi "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/notification_handler.py"
click node_recordservice "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/record_service.py"
click node_userservice "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/user_service.py"
click node_stationservice "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/station_service.py"
click node_symbolservice "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/symbol_service.py"
click node_recordrepo "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/record_repo.py"
click node_userrepo "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/user_repo.py"
click node_stationrepo "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/station_repo.py"
click node_symbolrepo "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/symbol_repo.py"
click node_ormrepo "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/db_core/repository.py"
click node_db "https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/database.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_app,node_authctx,node_dataui,node_verifyui,node_stationui,node_browser toneBlue
class node_userapi,node_prefsapi,node_volunteer,node_signalapi,node_stationapi,node_onlineapi,node_recordapi,node_timeapi,node_notifyapi,node_db toneAmber
class node_recordservice,node_userservice,node_stationservice,node_symbolservice toneMint
class node_recordrepo,node_userrepo,node_stationrepo,node_symbolrepo,node_ormrepo toneRose
class node_pushover,node_email toneIndigo
```

## Components

### Web client

- [App routes](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/App.js): `tracksenseweb/src/App.js`
- [Auth context](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/AuthContext.js): `tracksenseweb/src/components/AuthContext.js`
- [Record screens](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/Data.js): `tracksenseweb/src/components/Data.js`
- [Verification screens](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/VerifyEOT.js): `tracksenseweb/src/components/VerifyEOT.js`
- [Station pages](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/tracksenseweb/src/components/Station.js): `tracksenseweb/src/components/Station.js`

### Backend API

- [User endpoints](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/user_api.py): `backend/src/api/user_api.py`
- [Preference endpoints](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/user_preferences_api.py): `backend/src/api/user_preferences_api.py`
- [Volunteer endpoints](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/volunteer_handler.py): `backend/src/api/volunteer_handler.py`
- [Signal updates](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/signal_update_handler.py): `backend/src/api/signal_update_handler.py`
- [Station endpoints](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/station_auth.py): `backend/src/api/station_auth.py`
- [Station status](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/station_online.py): `backend/src/api/station_online.py`
- [Record endpoints](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/record_collation.py): `backend/src/api/record_collation.py`
- [Recent activity](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/time_frame_pull.py): `backend/src/api/time_frame_pull.py`
- [Notification endpoints](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/api/notification_handler.py): `backend/src/api/notification_handler.py`

### Domain services

- [Record service](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/record_service.py): `backend/src/service/record_service.py`
- [User service](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/user_service.py): `backend/src/service/user_service.py`
- [Station service](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/station_service.py): `backend/src/service/station_service.py`
- [Symbol service](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/service/symbol_service.py): `backend/src/service/symbol_service.py`

### Persistence

- [Record repositories](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/record_repo.py): `backend/src/db/record_repo.py`
- [User repository](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/user_repo.py): `backend/src/db/user_repo.py`
- [Station repository](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/station_repo.py): `backend/src/db/station_repo.py`
- [Symbol repository](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/symbol_repo.py): `backend/src/db/symbol_repo.py`
- [ORM repository core](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/src/db/db_core/repository.py): `backend/src/db/db_core/repository.py`

### Other components

- **Browser user**
- [SQL database](https://github.com/conductors-senior-project-rit/full-stack-web-app/blob/main/backend/database.py): `backend/database.py`
- **Pushover**
- **Email delivery**

## Connections

- Browser user → App routes: uses
- App routes → Auth context: provides auth
- Auth context → User endpoints: checks role
- Record screens → Record endpoints: requests records
- Verification screens → Volunteer endpoints: requests verification
- Station pages → Station endpoints: requests station
- Volunteer endpoints → Record service: loads and verifies
- Volunteer endpoints → Symbol service: manages symbols
- Signal updates → Record service: updates record
- Record service → Record repositories: queries and writes
- Record repositories → ORM repository core: uses ORM core
- User endpoints → User service: handles accounts
- Preference endpoints → User service: handles preferences
- User service → User repository: reads and writes
- User service → Station repository: lists stations
- User service → Email delivery: sends account mail
- Station endpoints → Station service: handles station auth
- Station status → Station service: updates status
- Station service → Station repository: reads and writes
- Symbol service → Symbol repository: reads and writes
- Record endpoints → Record service: collates records
- Recent activity → Record service: pulls activity
- ORM repository core → SQL database: queries and flushes
- Notification endpoints → Pushover: sends alert