# khu-hackhu/hackhu-hp architecture

> Architecture diagram of the GitHub repository khu-hackhu/hackhu-hp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khu-hackhu/hackhu-hp
- Repository: https://github.com/khu-hackhu/hackhu-hp

## Overview

HacKHU-HP is a club website with a React frontend and Spring API. The visible backend workflow covers account signup and session-based authentication, plus gallery uploads that are confirmed into albums and then queried for public display. The graph includes the frontend gallery surface and shared security/storage layers. The README also names a board feature, but no board source is present in this file tree; several auth, security, and integration links are therefore omitted where the excerpts do not establish their callers.

Main entry points: [`backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java`](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java) (Album creation), [`backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java`](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java) (Login service), [`backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java`](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java) (Token refresh), [`backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java`](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java) (Upload confirmation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web frontend"]
  node_app["React app<br/>[App.tsx]"]
  node_gallery_ui["Gallery screens<br/>[GalleryPage.tsx]"]
  node_gallery_api["Gallery API client<br/>[api.ts]"]
end

subgraph group_accounts["Accounts and sessions"]
  node_auth_controller["Auth endpoints"]
  node_login["Login service<br/>[LoginService.java]"]
  node_refresh["Token refresh"]
  node_session_issuer["Session issuer"]
  node_auth_repos[("Session repositories")]
  node_signup_controller["Signup endpoint"]
  node_signup["Signup service<br/>[SignupService.java]"]
  node_user_repo[("User repository")]
end

subgraph group_gallery["Gallery"]
  node_gallery_upload["Upload URL issuance"]
  node_album_command["Album creation"]
  node_album_query["Album queries"]
  node_album_repo[("Album repository")]
  node_photo_repo[("Photo repository")]
  node_url_resolver["Photo URL resolver"]
end

subgraph group_platform["Shared platform"]
  node_upload_confirm["Upload confirmation"]
  node_upload_records[("Upload records")]
  node_presigned["Presigned URLs"]
  node_object_store["S3 object store<br/>[S3ObjectStore.java]"]
  node_security["Request security"]
  node_access_tokens["Access tokens"]
end

node_browser(("Browser"))
node_cdn["CloudFront CDN"]

node_browser -->|"opens"| node_app
node_app -->|"renders"| node_gallery_ui
node_auth_controller -->|"calls"| node_login
node_auth_controller -->|"calls"| node_refresh
node_login -->|"reads"| node_user_repo
node_login -->|"uses"| node_auth_repos
node_login -->|"starts session"| node_session_issuer
node_refresh -->|"reads and updates"| node_auth_repos
node_refresh -->|"reads"| node_user_repo
node_refresh -->|"rotates tokens"| node_session_issuer
node_signup -->|"saves user"| node_user_repo
node_gallery_upload -->|"requests URLs"| node_presigned
node_gallery_upload -->|"saves records"| node_upload_records
node_gallery_upload -.->|"hands off confirmation"| node_upload_confirm
node_presigned -.->|"authorizes upload"| node_object_store
node_album_command -->|"confirms images"| node_upload_confirm
node_album_command -->|"saves album"| node_album_repo
node_album_command -->|"saves photos"| node_photo_repo
node_album_command -->|"resolves photo URLs"| node_url_resolver
node_album_query -->|"queries albums"| node_album_repo
node_album_query -->|"queries photos"| node_photo_repo
node_album_query -->|"resolves photo URLs"| node_url_resolver
node_url_resolver -.->|"resolves through"| node_cdn
node_upload_confirm -->|"claims records"| node_upload_records
node_upload_confirm -->|"checks and cleans"| node_object_store

click node_app "https://github.com/khu-hackhu/hackhu-hp/blob/develop/frontend/src/App.tsx"
click node_gallery_ui "https://github.com/khu-hackhu/hackhu-hp/blob/develop/frontend/src/features/gallery/GalleryPage.tsx"
click node_gallery_api "https://github.com/khu-hackhu/hackhu-hp/blob/develop/frontend/src/features/gallery/api.ts"
click node_auth_controller "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/controller/AuthController.java"
click node_login "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java"
click node_refresh "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java"
click node_session_issuer "https://github.com/khu-hackhu/hackhu-hp/tree/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service"
click node_auth_repos "https://github.com/khu-hackhu/hackhu-hp/tree/develop/backend/src/main/java/com/hackhu/hp/domain/auth/repository"
click node_signup_controller "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/user/controller/SignupController.java"
click node_signup "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/user/service/SignupService.java"
click node_user_repo "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/user/repository/UserRepository.java"
click node_gallery_upload "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/GalleryUploadService.java"
click node_upload_confirm "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java"
click node_upload_records "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/UploadRecordRepository.java"
click node_presigned "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/PresignedUrlService.java"
click node_object_store "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/S3ObjectStore.java"
click node_album_command "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java"
click node_album_query "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumQueryService.java"
click node_album_repo "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/repository/AlbumRepository.java"
click node_photo_repo "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/repository/PhotoRepository.java"
click node_url_resolver "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/PhotoUrlResolver.java"
click node_security "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/security/SecurityConfig.java"
click node_access_tokens "https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/auth/AccessTokenService.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_gallery_ui,node_gallery_api,node_browser toneBlue
class node_auth_controller,node_login,node_refresh,node_session_issuer,node_auth_repos,node_signup_controller,node_signup,node_user_repo toneAmber
class node_gallery_upload,node_album_command,node_album_query,node_album_repo,node_photo_repo,node_url_resolver toneMint
class node_upload_confirm,node_upload_records,node_presigned,node_object_store,node_security,node_access_tokens toneRose
class node_cdn toneIndigo
```

## Components

### Web frontend

- [React app](https://github.com/khu-hackhu/hackhu-hp/blob/develop/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Gallery screens](https://github.com/khu-hackhu/hackhu-hp/blob/develop/frontend/src/features/gallery/GalleryPage.tsx): `frontend/src/features/gallery/GalleryPage.tsx`
- [Gallery API client](https://github.com/khu-hackhu/hackhu-hp/blob/develop/frontend/src/features/gallery/api.ts): `frontend/src/features/gallery/api.ts`

### Accounts and sessions

- [Auth endpoints](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/controller/AuthController.java): `backend/src/main/java/com/hackhu/hp/domain/auth/controller/AuthController.java`
- [Login service](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java): `backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java`
- [Token refresh](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java): `backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java`
- [Session issuer](https://github.com/khu-hackhu/hackhu-hp/tree/develop/backend/src/main/java/com/hackhu/hp/domain/auth/service): `backend/src/main/java/com/hackhu/hp/domain/auth/service`
- [Session repositories](https://github.com/khu-hackhu/hackhu-hp/tree/develop/backend/src/main/java/com/hackhu/hp/domain/auth/repository): `backend/src/main/java/com/hackhu/hp/domain/auth/repository`
- [Signup endpoint](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/user/controller/SignupController.java): `backend/src/main/java/com/hackhu/hp/domain/user/controller/SignupController.java`
- [Signup service](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/user/service/SignupService.java): `backend/src/main/java/com/hackhu/hp/domain/user/service/SignupService.java`
- [User repository](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/user/repository/UserRepository.java): `backend/src/main/java/com/hackhu/hp/domain/user/repository/UserRepository.java`

### Gallery

- [Upload URL issuance](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/GalleryUploadService.java): `backend/src/main/java/com/hackhu/hp/domain/gallery/service/GalleryUploadService.java`
- [Album creation](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java): `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java`
- [Album queries](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumQueryService.java): `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumQueryService.java`
- [Album repository](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/repository/AlbumRepository.java): `backend/src/main/java/com/hackhu/hp/domain/gallery/repository/AlbumRepository.java`
- [Photo repository](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/repository/PhotoRepository.java): `backend/src/main/java/com/hackhu/hp/domain/gallery/repository/PhotoRepository.java`
- [Photo URL resolver](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/domain/gallery/service/PhotoUrlResolver.java): `backend/src/main/java/com/hackhu/hp/domain/gallery/service/PhotoUrlResolver.java`

### Shared platform

- [Upload confirmation](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java): `backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java`
- [Upload records](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/UploadRecordRepository.java): `backend/src/main/java/com/hackhu/hp/global/storage/UploadRecordRepository.java`
- [Presigned URLs](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/PresignedUrlService.java): `backend/src/main/java/com/hackhu/hp/global/storage/PresignedUrlService.java`
- [S3 object store](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/storage/S3ObjectStore.java): `backend/src/main/java/com/hackhu/hp/global/storage/S3ObjectStore.java`
- [Request security](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/security/SecurityConfig.java): `backend/src/main/java/com/hackhu/hp/global/security/SecurityConfig.java`
- [Access tokens](https://github.com/khu-hackhu/hackhu-hp/blob/develop/backend/src/main/java/com/hackhu/hp/global/auth/AccessTokenService.java): `backend/src/main/java/com/hackhu/hp/global/auth/AccessTokenService.java`

### Other components

- **Browser**
- **CloudFront CDN**

## Connections

- Browser → React app: opens (evidence: `README.md`)
- React app → Gallery screens: renders (evidence: `frontend/src/App.tsx`)
- Auth endpoints → Login service: calls (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/controller/AuthController.java`)
- Auth endpoints → Token refresh: calls (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/controller/AuthController.java`)
- Login service → User repository: reads (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java`)
- Login service → Session repositories: uses (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java`)
- Login service → Session issuer: starts session (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/service/LoginService.java`)
- Token refresh → Session repositories: reads and updates (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java`)
- Token refresh → User repository: reads (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java`)
- Token refresh → Session issuer: rotates tokens (evidence: `backend/src/main/java/com/hackhu/hp/domain/auth/service/TokenRefreshService.java`)
- Signup service → User repository: saves user (evidence: `backend/src/main/java/com/hackhu/hp/domain/user/service/SignupService.java`)
- Upload URL issuance → Presigned URLs: requests URLs (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/GalleryUploadService.java`)
- Upload URL issuance → Upload records: saves records (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/GalleryUploadService.java`)
- Upload URL issuance → Upload confirmation: hands off confirmation
- Presigned URLs → S3 object store: authorizes upload
- Album creation → Upload confirmation: confirms images (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java`)
- Album creation → Album repository: saves album (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java`)
- Album creation → Photo repository: saves photos (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java`)
- Album creation → Photo URL resolver: resolves photo URLs (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumCommandService.java`)
- Album queries → Album repository: queries albums (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumQueryService.java`)
- Album queries → Photo repository: queries photos (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumQueryService.java`)
- Album queries → Photo URL resolver: resolves photo URLs (evidence: `backend/src/main/java/com/hackhu/hp/domain/gallery/service/AlbumQueryService.java`)
- Photo URL resolver → CloudFront CDN: resolves through
- Upload confirmation → Upload records: claims records (evidence: `backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java`)
- Upload confirmation → S3 object store: checks and cleans (evidence: `backend/src/main/java/com/hackhu/hp/global/storage/UploadConfirmService.java`)
