mirror of
https://github.com/praktimarc/kst4contest.git
synced 2026-08-26 20:16:54 +02:00
103 lines
2.4 KiB
Markdown
103 lines
2.4 KiB
Markdown
# Architecture context
|
|
|
|
## Current package shape
|
|
|
|
The repository currently contains major packages under `src/main/java/kst4contest/` including:
|
|
|
|
- `controller`
|
|
- `locatorUtils`
|
|
- `logic`
|
|
- `model`
|
|
- `service`
|
|
- `test`
|
|
- `utils`
|
|
- `view`
|
|
|
|
Do not treat package names alone as proof of clean MVC boundaries. Inspect actual dependencies.
|
|
|
|
## Preferred message/member data flow
|
|
|
|
The established target architecture for active chat members is:
|
|
|
|
```text
|
|
ON4KST / network
|
|
|
|
|
v
|
|
MessageBusManagementThread
|
|
|
|
|
v
|
|
ChatController
|
|
|
|
|
v
|
|
thread-safe active-member domain state
|
|
(ConcurrentMap; identity includes callsign + category)
|
|
|
|
|
v
|
|
JavaFX ObservableList UI mirror
|
|
|
|
|
v
|
|
FilteredList / SortedList / TableView / selection
|
|
```
|
|
|
|
Key rule:
|
|
|
|
`ObservableList` is a JavaFX UI projection, not the canonical store for worker-thread logic.
|
|
|
|
`MessageBusManagementThread` must not directly read or modify the UI list.
|
|
|
|
## JavaFX boundary
|
|
|
|
UI-visible mutations belong on the JavaFX Application Thread.
|
|
|
|
Prefer controller-owned helpers such as an existing `runOnFxThread` abstraction when available; otherwise use `Platform.runLater` consistently.
|
|
|
|
Do not move business/data access into the FX thread merely to silence a threading problem.
|
|
|
|
## Parser/service separation
|
|
|
|
For protocol receivers, the preferred direction is:
|
|
|
|
```text
|
|
Receiver (I/O only)
|
|
-> Parser (wire data -> DTO)
|
|
-> Service (domain/persistence logic)
|
|
-> Controller (UI coordination)
|
|
-> Observable UI model
|
|
-> View
|
|
```
|
|
|
|
A previous concrete example for UCXLog was:
|
|
|
|
```text
|
|
UcxUdpReceiver
|
|
-> UcxPacketParser
|
|
-> DTO
|
|
-> UcxLogService
|
|
-> ChatController
|
|
-> UI projection
|
|
```
|
|
|
|
This is architectural guidance, not permission for a broad refactor. Apply only when it is in scope and approved.
|
|
|
|
## DTO preference
|
|
|
|
Prefer explicit DTO classes over records when introducing protocol/transport data structures in this project, unless the approved concept intentionally changes that convention.
|
|
|
|
## Null safety
|
|
|
|
Chat members can be incomplete, especially:
|
|
|
|
- fallback members;
|
|
- historic message senders;
|
|
- server-derived partial members.
|
|
|
|
Values such as QRB and QTF can be absent.
|
|
|
|
Rules:
|
|
|
|
- absence stays absence;
|
|
- do not map `null` to numeric zero;
|
|
- UI must render unavailable state safely;
|
|
- sorting/filtering/calculation code must tolerate missing values;
|
|
- unexpected missing values must not terminate worker or UI threads.
|