# samba-gomis/guildboard architecture

> Architecture diagram of the GitHub repository samba-gomis/guildboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samba-gomis/guildboard
- Repository: https://github.com/samba-gomis/guildboard

## Overview

GuildBoard is a web application for managing an adventurers’ guild. The guild master uses the React interface to browse and mutate adventurers and quests; frontend services send HTTP requests to Spring controllers, which delegate to services. Domain services enforce assignment, completion, reward, XP, and leveling rules, then persist entities in PostgreSQL. Responses return through the same layers to lists, detail pages, XP displays, and assignment history. The frontend page-to-component wiring and some unsampled backend details are represented only where supported by the tree and README.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web Interface"]
  node_app["React App<br/>[App.tsx]"]
  node_quests_page["Quest Screens<br/>[QuestsPage.tsx]"]
  node_adventurers_page["Adventurer Screens"]
  node_adventurer_detail["Adventurer Detail"]
  node_quest_service_client["Quest Client<br/>[questService.ts]"]
  node_adventurer_service_client["Adventurer Client"]
  node_http_client["HTTP Client<br/>[httpClient.ts]"]
end

subgraph group_api["REST API"]
  node_quest_controller["Quest Controller"]
  node_adventurer_controller["Adventurer Controller"]
  node_error_handler["Error Handler"]
  node_api_dtos["API Contracts"]
end

subgraph group_domain["Guild Domain"]
  node_quest_service["Quest Rules<br/>[QuestService.java]"]
  node_adventurer_service["Adventurer Rules"]
  node_guild_entities["Guild Entities"]
end

subgraph group_persistence["Data Persistence"]
  node_quest_repository["Quest Repository"]
  node_adventurer_repository["Adventurer Repository"]
  node_assignment_repository["Assignment Repository"]
  node_postgresql[("PostgreSQL")]
end

node_guild_master(("Guild Master"))

node_guild_master -->|"uses"| node_app
node_app -->|"shows"| node_quests_page
node_app -->|"shows"| node_adventurers_page
node_adventurers_page -->|"opens"| node_adventurer_detail
node_quests_page -->|"requests quests"| node_quest_service_client
node_adventurers_page -->|"requests adventurers"| node_adventurer_service_client
node_adventurer_detail -->|"loads history"| node_adventurer_service_client
node_quest_service_client -->|"calls"| node_http_client
node_adventurer_service_client -->|"calls"| node_http_client
node_http_client -->|"HTTP requests"| node_quest_controller
node_http_client -->|"HTTP requests"| node_adventurer_controller
node_quest_controller -->|"delegates"| node_quest_service
node_adventurer_controller -->|"delegates"| node_adventurer_service
node_quest_controller -->|"uses DTOs"| node_api_dtos
node_adventurer_controller -->|"uses DTOs"| node_api_dtos
node_quest_service -->|"maps responses"| node_api_dtos
node_adventurer_service -->|"maps responses"| node_api_dtos
node_quest_service -->|"reads/writes"| node_quest_repository
node_quest_service -->|"reads adventurers"| node_adventurer_repository
node_quest_service -->|"reads/writes"| node_assignment_repository
node_adventurer_service -->|"reads/writes"| node_adventurer_repository
node_adventurer_service -->|"reads history"| node_assignment_repository
node_quest_repository -->|"queries"| node_postgresql
node_adventurer_repository -->|"queries"| node_postgresql
node_assignment_repository -->|"queries"| node_postgresql
node_quest_service -->|"applies rules"| node_guild_entities
node_adventurer_service -->|"maps entities"| node_guild_entities
node_error_handler -->|"formats errors"| node_api_dtos
node_quest_controller -.->|"raises errors"| node_error_handler
node_adventurer_controller -.->|"raises errors"| node_error_handler

click node_app "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/App.tsx"
click node_quests_page "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/pages/QuestsPage.tsx"
click node_adventurers_page "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/pages/AdventurersPage.tsx"
click node_adventurer_detail "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/pages/AdventurerDetailPage.tsx"
click node_quest_service_client "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/services/questService.ts"
click node_adventurer_service_client "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/services/adventurerService.ts"
click node_http_client "https://github.com/samba-gomis/guildboard/blob/main/frontend/src/services/httpClient.ts"
click node_quest_controller "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/controller/QuestController.java"
click node_adventurer_controller "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/controller/AdventurerController.java"
click node_error_handler "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/exception/GlobalExceptionHandler.java"
click node_api_dtos "https://github.com/samba-gomis/guildboard/tree/main/backend/demo/src/main/java/com/forgesoft/guildboard/dto"
click node_quest_service "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/service/QuestService.java"
click node_adventurer_service "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/service/AdventurerService.java"
click node_guild_entities "https://github.com/samba-gomis/guildboard/tree/main/backend/demo/src/main/java/com/forgesoft/guildboard/entity"
click node_quest_repository "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/repository/QuestRepository.java"
click node_adventurer_repository "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/repository/AdventurerRepository.java"
click node_assignment_repository "https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/repository/AssignmentRepository.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_app,node_quests_page,node_adventurers_page,node_adventurer_detail,node_quest_service_client,node_adventurer_service_client,node_http_client toneBlue
class node_quest_controller,node_adventurer_controller,node_error_handler,node_api_dtos toneAmber
class node_quest_service,node_adventurer_service,node_guild_entities toneMint
class node_quest_repository,node_adventurer_repository,node_assignment_repository,node_postgresql toneRose
class node_guild_master toneIndigo
```

## Components

### Web Interface

- [React App](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Quest Screens](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/pages/QuestsPage.tsx): `frontend/src/pages/QuestsPage.tsx`
- [Adventurer Screens](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/pages/AdventurersPage.tsx): `frontend/src/pages/AdventurersPage.tsx`
- [Adventurer Detail](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/pages/AdventurerDetailPage.tsx): `frontend/src/pages/AdventurerDetailPage.tsx`
- [Quest Client](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/services/questService.ts): `frontend/src/services/questService.ts`
- [Adventurer Client](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/services/adventurerService.ts): `frontend/src/services/adventurerService.ts`
- [HTTP Client](https://github.com/samba-gomis/guildboard/blob/main/frontend/src/services/httpClient.ts): `frontend/src/services/httpClient.ts`

### REST API

- [Quest Controller](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/controller/QuestController.java): `backend/demo/src/main/java/com/forgesoft/guildboard/controller/QuestController.java`
- [Adventurer Controller](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/controller/AdventurerController.java): `backend/demo/src/main/java/com/forgesoft/guildboard/controller/AdventurerController.java`
- [Error Handler](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/exception/GlobalExceptionHandler.java): `backend/demo/src/main/java/com/forgesoft/guildboard/exception/GlobalExceptionHandler.java`
- [API Contracts](https://github.com/samba-gomis/guildboard/tree/main/backend/demo/src/main/java/com/forgesoft/guildboard/dto): `backend/demo/src/main/java/com/forgesoft/guildboard/dto`

### Guild Domain

- [Quest Rules](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/service/QuestService.java): `backend/demo/src/main/java/com/forgesoft/guildboard/service/QuestService.java`
- [Adventurer Rules](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/service/AdventurerService.java): `backend/demo/src/main/java/com/forgesoft/guildboard/service/AdventurerService.java`
- [Guild Entities](https://github.com/samba-gomis/guildboard/tree/main/backend/demo/src/main/java/com/forgesoft/guildboard/entity): `backend/demo/src/main/java/com/forgesoft/guildboard/entity`

### Data Persistence

- [Quest Repository](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/repository/QuestRepository.java): `backend/demo/src/main/java/com/forgesoft/guildboard/repository/QuestRepository.java`
- [Adventurer Repository](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/repository/AdventurerRepository.java): `backend/demo/src/main/java/com/forgesoft/guildboard/repository/AdventurerRepository.java`
- [Assignment Repository](https://github.com/samba-gomis/guildboard/blob/main/backend/demo/src/main/java/com/forgesoft/guildboard/repository/AssignmentRepository.java): `backend/demo/src/main/java/com/forgesoft/guildboard/repository/AssignmentRepository.java`
- **PostgreSQL**

### Other components

- **Guild Master**

## Connections

- Guild Master → React App: uses
- React App → Quest Screens: shows
- React App → Adventurer Screens: shows
- Adventurer Screens → Adventurer Detail: opens
- Quest Screens → Quest Client: requests quests
- Adventurer Screens → Adventurer Client: requests adventurers
- Adventurer Detail → Adventurer Client: loads history
- Quest Client → HTTP Client: calls
- Adventurer Client → HTTP Client: calls
- HTTP Client → Quest Controller: HTTP requests
- HTTP Client → Adventurer Controller: HTTP requests
- Quest Controller → Quest Rules: delegates
- Adventurer Controller → Adventurer Rules: delegates
- Quest Controller → API Contracts: uses DTOs
- Adventurer Controller → API Contracts: uses DTOs
- Quest Rules → API Contracts: maps responses
- Adventurer Rules → API Contracts: maps responses
- Quest Rules → Quest Repository: reads/writes
- Quest Rules → Adventurer Repository: reads adventurers
- Quest Rules → Assignment Repository: reads/writes
- Adventurer Rules → Adventurer Repository: reads/writes
- Adventurer Rules → Assignment Repository: reads history
- Quest Repository → PostgreSQL: queries
- Adventurer Repository → PostgreSQL: queries
- Assignment Repository → PostgreSQL: queries
- Quest Rules → Guild Entities: applies rules
- Adventurer Rules → Guild Entities: maps entities
- Error Handler → API Contracts: formats errors
- Quest Controller → Error Handler: raises errors
- Adventurer Controller → Error Handler: raises errors
