kst4contest/.agents/skills/kst4contest-change/references/architecture.md

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:

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:

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:

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.