# itsswayize/loadshed architecture

> Architecture diagram of the GitHub repository itsswayize/loadshed, 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/itsswayize/loadshed
- Repository: https://github.com/itsswayize/loadshed

## Overview

LightSched serves South African load-shedding information through a web frontend backed by separate stage, place-name, and schedule services. The main user flow is browser → web routes → backend REST requests → rendered pages; stage updates also publish asynchronously, while alert messages are consumed by a worker and forwarded as mobile notifications. The graph reflects shown calls and README-documented integrations; some backend details and the alert worker’s internals were not excerpted.

Main entry points: [`web/src/main/java/wethinkcode/web/WebService.java`](https://github.com/itsswayize/loadshed/blob/main/web/src/main/java/wethinkcode/web/WebService.java) (Web gateway), [`stage/src/main/java/wethinkcode/stage/StageService.java`](https://github.com/itsswayize/loadshed/blob/main/stage/src/main/java/wethinkcode/stage/StageService.java) (Stage API), [`places/src/main/java/wethinkcode/places/PlaceNameService.java`](https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/PlaceNameService.java) (Places API), [`places/src/main/java/wethinkcode/places/PlacesCsvParser.java`](https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/PlacesCsvParser.java) (CSV parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web frontend"]
  node_web["Web gateway<br/>[WebService.java]"]
  node_pages["HTML templates"]
end

subgraph group_domain["Domain services"]
  node_stage["Stage API<br/>[StageService.java]"]
  node_places["Places API"]
  node_csv["CSV parser"]
  node_placesdb[("Places memory store<br/>[PlacesDb.java]")]
  node_schedule["Schedule API"]
end

subgraph group_messaging["Messaging and alerts"]
  node_mq_sender["Topic sender<br/>[MqTopicSender.java]"]
  node_mq_config["MQ config<br/>[MQ.java]"]
  node_alert["Alert worker<br/>[AlertService.java]"]
end

subgraph group_shared["Shared data"]
  node_place_model["Place models"]
  node_schedule_dto["Schedule DTOs"]
  node_stage_dto["Stage DTO<br/>[StageDO.java]"]
end

node_user(("Browser user"))
node_broker["ActiveMQ broker"]
node_ntfy["ntfy notifications"]

node_user -->|"requests pages"| node_web
node_web -->|"fetches stage"| node_stage
node_web -->|"fetches place data"| node_places
node_web -->|"fetches schedule"| node_schedule
node_web -->|"renders pages"| node_pages
node_places -->|"parses dataset"| node_csv
node_csv -->|"builds store"| node_placesdb
node_places -->|"serves place data"| node_place_model
node_placesdb -->|"implements model"| node_place_model
node_schedule -->|"returns schedule"| node_schedule_dto
node_stage -->|"reads and returns"| node_stage_dto
node_stage -->|"publishes updates"| node_mq_sender
node_stage -->|"broadcasts stage"| node_broker
node_mq_sender -.->|"uses settings"| node_mq_config
node_web -->|"queues alerts"| node_broker
node_broker -->|"delivers messages"| node_alert
node_alert -->|"pushes notifications"| node_ntfy

click node_web "https://github.com/itsswayize/loadshed/blob/main/web/src/main/java/wethinkcode/web/WebService.java"
click node_pages "https://github.com/itsswayize/loadshed/tree/main/web/src/main/resources/templates"
click node_stage "https://github.com/itsswayize/loadshed/blob/main/stage/src/main/java/wethinkcode/stage/StageService.java"
click node_places "https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/PlaceNameService.java"
click node_csv "https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/PlacesCsvParser.java"
click node_placesdb "https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/db/memory/PlacesDb.java"
click node_place_model "https://github.com/itsswayize/loadshed/tree/main/places/src/main/java/wethinkcode/places/model"
click node_schedule "https://github.com/itsswayize/loadshed/blob/main/schedule/src/main/java/wethinkcode/schedule/ScheduleService.java"
click node_schedule_dto "https://github.com/itsswayize/loadshed/tree/main/common/src/main/java/wethinkcode/loadshed/common/transfer"
click node_stage_dto "https://github.com/itsswayize/loadshed/blob/main/common/src/main/java/wethinkcode/loadshed/common/transfer/StageDO.java"
click node_mq_sender "https://github.com/itsswayize/loadshed/blob/main/common/src/main/java/wethinkcode/loadshed/common/mq/MqTopicSender.java"
click node_mq_config "https://github.com/itsswayize/loadshed/blob/main/common/src/main/java/wethinkcode/loadshed/common/mq/MQ.java"
click node_alert "https://github.com/itsswayize/loadshed/blob/main/alert/src/main/java/wethinkcode/alert/AlertService.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_web,node_pages,node_user toneBlue
class node_stage,node_places,node_csv,node_placesdb,node_schedule toneAmber
class node_mq_sender,node_mq_config,node_alert toneMint
class node_place_model,node_schedule_dto,node_stage_dto toneRose
class node_broker,node_ntfy toneIndigo
```

## Components

### Web frontend

- [Web gateway](https://github.com/itsswayize/loadshed/blob/main/web/src/main/java/wethinkcode/web/WebService.java): `web/src/main/java/wethinkcode/web/WebService.java`
- [HTML templates](https://github.com/itsswayize/loadshed/tree/main/web/src/main/resources/templates): `web/src/main/resources/templates`

### Domain services

- [Stage API](https://github.com/itsswayize/loadshed/blob/main/stage/src/main/java/wethinkcode/stage/StageService.java): `stage/src/main/java/wethinkcode/stage/StageService.java`
- [Places API](https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/PlaceNameService.java): `places/src/main/java/wethinkcode/places/PlaceNameService.java`
- [CSV parser](https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/PlacesCsvParser.java): `places/src/main/java/wethinkcode/places/PlacesCsvParser.java`
- [Places memory store](https://github.com/itsswayize/loadshed/blob/main/places/src/main/java/wethinkcode/places/db/memory/PlacesDb.java): `places/src/main/java/wethinkcode/places/db/memory/PlacesDb.java`
- [Schedule API](https://github.com/itsswayize/loadshed/blob/main/schedule/src/main/java/wethinkcode/schedule/ScheduleService.java): `schedule/src/main/java/wethinkcode/schedule/ScheduleService.java`

### Messaging and alerts

- [Topic sender](https://github.com/itsswayize/loadshed/blob/main/common/src/main/java/wethinkcode/loadshed/common/mq/MqTopicSender.java): `common/src/main/java/wethinkcode/loadshed/common/mq/MqTopicSender.java`
- [MQ config](https://github.com/itsswayize/loadshed/blob/main/common/src/main/java/wethinkcode/loadshed/common/mq/MQ.java): `common/src/main/java/wethinkcode/loadshed/common/mq/MQ.java`
- [Alert worker](https://github.com/itsswayize/loadshed/blob/main/alert/src/main/java/wethinkcode/alert/AlertService.java): `alert/src/main/java/wethinkcode/alert/AlertService.java`

### Shared data

- [Place models](https://github.com/itsswayize/loadshed/tree/main/places/src/main/java/wethinkcode/places/model): `places/src/main/java/wethinkcode/places/model`
- [Schedule DTOs](https://github.com/itsswayize/loadshed/tree/main/common/src/main/java/wethinkcode/loadshed/common/transfer): `common/src/main/java/wethinkcode/loadshed/common/transfer`
- [Stage DTO](https://github.com/itsswayize/loadshed/blob/main/common/src/main/java/wethinkcode/loadshed/common/transfer/StageDO.java): `common/src/main/java/wethinkcode/loadshed/common/transfer/StageDO.java`

### Other components

- **Browser user**
- **ActiveMQ broker**
- **ntfy notifications**

## Connections

- Browser user → Web gateway: requests pages (evidence: `README.md`)
- Web gateway → Stage API: fetches stage (evidence: `web/src/main/java/wethinkcode/web/WebService.java`)
- Web gateway → Places API: fetches place data (evidence: `web/src/main/java/wethinkcode/web/WebService.java`)
- Web gateway → Schedule API: fetches schedule (evidence: `web/src/main/java/wethinkcode/web/WebService.java`)
- Web gateway → HTML templates: renders pages (evidence: `web/src/main/java/wethinkcode/web/WebService.java`)
- Places API → CSV parser: parses dataset (evidence: `places/src/main/java/wethinkcode/places/PlaceNameService.java`)
- CSV parser → Places memory store: builds store (evidence: `places/src/main/java/wethinkcode/places/PlacesCsvParser.java`)
- Places API → Place models: serves place data (evidence: `places/src/main/java/wethinkcode/places/PlaceNameService.java`)
- Places memory store → Place models: implements model (evidence: `places/src/main/java/wethinkcode/places/db/memory/PlacesDb.java`)
- Schedule API → Schedule DTOs: returns schedule (evidence: `schedule/src/main/java/wethinkcode/schedule/ScheduleService.java`)
- Stage API → Stage DTO: reads and returns (evidence: `stage/src/main/java/wethinkcode/stage/StageService.java`)
- Stage API → Topic sender: publishes updates (evidence: `stage/src/main/java/wethinkcode/stage/StageService.java`)
- Stage API → ActiveMQ broker: broadcasts stage (evidence: `README.md`)
- Topic sender → MQ config: uses settings
- Web gateway → ActiveMQ broker: queues alerts (evidence: `web/src/main/java/wethinkcode/web/WebService.java`)
- ActiveMQ broker → Alert worker: delivers messages (evidence: `README.md`)
- Alert worker → ntfy notifications: pushes notifications (evidence: `README.md`)
