feat: Sequence diagrams updated

helpmehelpapplication/App_startup_and_api_sync.puml

@@ -0,0 +1,46 @@
+@startuml
+!theme plain
+skinparam backgroundColor white
+
+title Application startup and organisation data sync from API
+
+participant "HmHApplication" as App
+participant "DatabaseSetup" as Setup
+participant "DatabaseConnection" as DBConn
+participant "APICharityScraper" as API
+participant "APIToDatabaseService" as Sync
+database "MySQL DB" as DB
+collections "CharityRegistry" as Registry
+
+App -> Setup : testConnection()
+Setup -> DBConn : getMySqlConnection()
+DBConn --> Setup : connection
+Setup --> App : OK
+
+App -> Setup : createTables()
+Setup -> DB : CREATE TABLE IF NOT EXISTS ...
+DB --> Setup : tables ready
+Setup --> App : OK
+
+App -> API : checkConnection()
+API --> App : true
+App -> API : getJSONData()
+API --> App : JSON payload
+App -> API : parseJSON(json)
+API --> App : CharityRegistry
+
+App -> Sync : addAPIDataToTable(Registry.getAllCharities())
+activate Sync
+Sync -> DBConn : getMySqlConnection()
+DBConn --> Sync : SQL connection
+loop For each charity from API
+  Sync -> DB : INSERT/UPDATE Charities
+  Sync -> DB : INSERT/UPDATE CharityVanity
+end
+Sync -> DB : CREATE TEMP TABLE temp_api_charities
+Sync -> DB : INSERT current org numbers into temp table
+Sync -> DB : DELETE stale charities not referenced elsewhere
+DB --> Sync : commit complete
+Sync --> App : Sync finished
+Deactivate Sync
+@enduml

helpmehelpapplication/Authentication_backend_flow.puml

@@ -0,0 +1,77 @@
+@startuml
+!theme plain
+skinparam backgroundColor white
+
+title User registration, login and logout backend flow
+
+actor User
+participant "UI / Controller" as UI
+participant "AuthenticationService" as Auth
+participant "UserSelect" as UserSelect
+participant "UserDAO" as UserDAO
+database "MySQL DB" as DB
+
+== Registration ==
+User -> UI : Submit displayName, username, email, password
+UI -> Auth : register(displayName, username, email, password)
+activate Auth
+Auth -> UserSelect : isUsernameTaken(username)
+activate UserSelect
+UserSelect -> DB : SELECT UUID_User FROM User WHERE user_name = username
+DB --> UserSelect : username exists / not found
+UserSelect --> Auth : true / false
+Deactivate UserSelect
+
+alt Username already taken
+  Auth --> UI : false
+  UI --> User : Show registration failed
+else Username available
+  Auth -> UserDAO : registerUser(new User)
+  activate UserDAO
+  UserDAO -> DB : INSERT INTO User
+  UserDAO -> DB : INSERT INTO Settings
+  DB --> UserDAO : insert result
+  UserDAO --> Auth : success / failure
+  deactivate UserDAO
+
+  alt Registration successful
+    Auth -> Auth : currentUser = newUser
+    Auth --> UI : true
+    UI --> User : Show registration successful
+  else Registration failed
+    Auth --> UI : false
+    UI --> User : Show registration failed
+  end
+end
+Deactivate Auth
+
+== Login ==
+User -> UI : Submit username and password
+UI -> Auth : login(username, password)
+activate Auth
+Auth -> UserSelect : getUserFromDBUsernameAndPassword(username, password)
+activate UserSelect
+UserSelect -> DB : SELECT User + Settings + Messages
+DB --> UserSelect : matching user rows
+UserSelect --> Auth : User / null
+Deactivate UserSelect
+
+alt Matching user found
+  Auth -> Auth : currentUser = user
+  Auth --> UI : true
+  UI --> User : Show logged-in state
+else No match
+  Auth --> UI : false
+  UI --> User : Show login failed
+end
+Deactivate Auth
+
+== Logout ==
+User -> UI : Click logout
+UI -> Auth : logout()
+activate Auth
+Auth -> Auth : currentUser = null
+Auth --> UI : logged out
+UI --> User : Return to logged-out state
+Deactivate Auth
+@enduml

helpmehelpapplication/Frontpage_load.puml

@@ -0,0 +1,38 @@
+@startuml
+!theme plain
+skinparam backgroundColor white
+
+title User opens front page and the app loads featured organisations
+
+actor User
+participant "FrontpageController" as Frontpage
+participant "DatabaseConnection" as DBConn
+participant "CharitySelect" as CharitySelect
+participant "DonationSelect" as DonationSelect
+database "MySQL DB" as DB
+
+User -> Frontpage : Open application / front page
+activate Frontpage
+Frontpage -> DBConn : create connection
+DBConn --> Frontpage : connection helper
+
+Frontpage -> CharitySelect : getCharitiesFromDB()
+activate CharitySelect
+CharitySelect -> DB : SELECT charities + charity vanity + categories + feedback
+DB --> CharitySelect : CharityRegistry
+CharitySelect --> Frontpage : CharityRegistry
+Deactivate CharitySelect
+
+Frontpage -> DonationSelect : getDonationFromDB()
+activate DonationSelect
+DonationSelect -> DB : SELECT donations + charity + user
+DB --> DonationSelect : DonationRegistry
+DonationSelect --> Frontpage : DonationRegistry
+Deactivate DonationSelect
+
+Frontpage -> Frontpage : displayCharities(allCharities)
+Frontpage -> Frontpage : choose random featured charity
+Frontpage -> Frontpage : calculate totals and pre-approved percentage
+Frontpage --> User : Show cards, featured charity and statistics
+Deactivate Frontpage
+@enduml

helpmehelpapplication/Full_organisation_enrichment_scrape.puml

@@ -0,0 +1,39 @@
+@startuml
+!theme plain
+skinparam backgroundColor white
+
+title Full organisation enrichment scrape
+
+actor "System / Developer" as Operator
+participant "FullCharityScrape" as FullScrape
+participant "APICharityScraper" as API
+participant "URLCharityScraper" as URLScraper
+participant "LogoDownloader" as Logo
+collections "CharityRegistry" as Registry
+collections "Charity" as Charity
+
+Operator -> FullScrape : getAPIAndURLCharityData()
+activate FullScrape
+FullScrape -> API : checkConnection()
+API --> FullScrape : true
+FullScrape -> API : getJSONData()
+API --> FullScrape : JSON payload
+FullScrape -> API : parseJSON(json)
+API --> FullScrape : CharityRegistry
+
+loop For each charity in registry
+  FullScrape -> URLScraper : new URLCharityScraper(charity.getURL())
+  FullScrape -> URLScraper : scrapeCharityPage()
+  URLScraper --> FullScrape : description, categories, logoURL, keyValues
+  FullScrape -> Logo : downloadImageAsBlob(logoURL)
+  Logo --> FullScrape : logo blob
+  FullScrape -> Charity : setDescription(...)
+  FullScrape -> Charity : setCategory(...)
+  FullScrape -> Charity : setLogoURL(...)
+  FullScrape -> Charity : setKeyValues(...)
+  FullScrape -> Charity : setLogoBlob(...)
+end
+
+FullScrape --> Operator : Fully enriched CharityRegistry
+Deactivate FullScrape
+@enduml

helpmehelpapplication/Search_and_browse_organisation.puml

@@ -0,0 +1,82 @@
+@startuml
+!theme plain
+skinparam backgroundColor white
+
+title User searches and browses organisations
+
+actor User
+participant "FrontpageController / CharityPageController / DonationPageController" as SourceUI
+participant "LoaderScene" as Loader
+participant "AvailableOrganizationController" as Available
+participant "DatabaseConnection" as DBConn
+participant "CharitySelect" as CharitySelect
+database "MySQL DB" as DB
+
+User -> SourceUI : Enter search text and press search
+SourceUI -> Loader : LoadScene("availableOrganization", query)
+Loader -> Available : initialize()
+activate Available
+Available -> DBConn : create connection
+DBConn --> Available : connection helper
+Available -> CharitySelect : getCharitiesFromDB()
+activate CharitySelect
+CharitySelect -> DB : SELECT charities + charity vanity + categories + feedback
+DB --> CharitySelect : CharityRegistry
+CharitySelect --> Available : CharityRegistry
+Deactivate CharitySelect
+
+Available -> Available : setInitialSearch(query)
+Available -> Available : filterCharities(query)
+Available -> Available : displayCharities(matches)
+Available --> User : Show matching organisation cards
+
+loop While user edits the search field
+  User -> Available : Update search text
+  Available -> Available : filterCharities(newValue)
+  Available -> Available : displayCharities(filtered list)
+  Available --> User : Refresh result list
+end
+
+deactivate Available
+@enduml
+@startuml
+!theme plain
+skinparam backgroundColor white
+
+title User searches and browses organisations
+
+actor User
+participant "FrontpageController / CharityPageController / DonationPageController" as SourceUI
+participant "LoaderScene" as Loader
+participant "AvailableOrganizationController" as Available
+participant "DatabaseConnection" as DBConn
+participant "CharitySelect" as CharitySelect
+database "MySQL DB" as DB
+
+User -> SourceUI : Enter search text and press search
+SourceUI -> Loader : LoadScene("availableOrganization", query)
+Loader -> Available : initialize()
+activate Available
+Available -> DBConn : create connection
+DBConn --> Available : connection helper
+Available -> CharitySelect : getCharitiesFromDB()
+activate CharitySelect
+CharitySelect -> DB : SELECT charities + charity vanity + categories + feedback
+DB --> CharitySelect : CharityRegistry
+CharitySelect --> Available : CharityRegistry
+Deactivate CharitySelect
+
+Available -> Available : setInitialSearch(query)
+Available -> Available : filterCharities(query)
+Available -> Available : displayCharities(matches)
+Available --> User : Show matching organisation cards
+
+loop While user edits the search field
+  User -> Available : Update search text
+  Available -> Available : filterCharities(newValue)
+  Available -> Available : displayCharities(filtered list)
+  Available --> User : Refresh result list
+end
+
+deactivate Available
+@enduml