# holychann/hubspace-public architecture

> Architecture diagram of the GitHub repository holychann/hubspace-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/holychann/hubspace-public
- Repository: https://github.com/holychann/hubspace-public

## Overview

1. This repository is a single Spring Boot backend monolith for “HubSpace,” a service that helps event applicants verify their Google Form submission status. The app exposes HTTP APIs, runs background jobs, and integrates with external Google, RabbitMQ, Redis, PostgreSQL, and DynamoDB systems.

2. The codebase is organized by domain rather than by technical layer. The main business domains are `event`, `response`, `user`, and `jwt`, with shared cross-cutting concerns under `global` and external adapters under `infra`. That makes the architecture diagram best drawn as a layered monolith with multiple storage backends.

3. Request flow starts at Spring MVC controllers in each domain. The `event` domain has separate controllers for command, query, form, and file concerns; `response` and `user` each have their own controllers; `jwt` handles token-related endpoints. Controllers do not appear to talk directly to repositories—they route into application services or facades.

4. The `application` layer contains facades that coordinate multiple domain services. `EventFacade` and `ResponseFacade` sit above the domain services and helpers, which suggests orchestration use cases that combine querying, transformation, and persistence rather than keeping logic inside controllers.

5. The `event` subsystem is the core of the polling workflow. It models event metadata, event entities, event types, request/response DTOs, converters, and separate command/query repositories and services. The presence of `QueryDSL` repositories and DTO converters indicates a read-optimized model for event lookups and a more transactional path for writes.

6. The `response` subsystem manages collected form submissions. It has its own entity, DTOs, command/query services, and helper utilities for normalizing strings, matching answers, and batch persistence. This domain is likely where applicant lookup and response validation happen, with Redis used to speed up repeated reads.

7. The `user` and `jwt` subsystems implement authentication and authorization. `SecurityConfig`, `JWTFilter`, `LoginFilter`, OAuth-related handlers, and `JwtService` indicate Google social login plus JWT-based session handling. `RefreshEntity` and `RefreshRepository` show that refresh tokens are persisted, while security events and handlers manage login success and token lifecycle behavior.

8. The `global` package contains platform-level concerns that apply across all domains: exception handling, API response wrapping, validation annotations, tracing/logging, and Spring configuration. `TraceIdFilter` and `LogTraceAspect` provide request correlation and method-level observability, while `GlobalExceptionHandler` centralizes error mapping.

9. The persistence architecture is intentionally split by data purpose. PostgreSQL via JPA is used for core relational state, especially polling status and user/auth-related records. DynamoDB stores collected Google Forms responses. Redis is used as a cache layer for repeated reads and derived data, with dedicated cache classes for event counts, metadata, search columns, user-event IDs, view counts, and response data.

10. The polling and ingestion pipeline is a major non-HTTP subsystem. `ScheduleConfig`, `EventExpirationScheduler`, and `Poller` drive periodic checks for events needing polling. The scheduler publishes work to RabbitMQ through producer services, and consumer services process messages asynchronously. This creates a decoupled boundary between scheduling and external API polling.

11. The external Google integration is isolated under `infra/google`. `GoogleDriveService` and its implementation handle retrieval of Google Form response data, and the DTOs suggest interaction with Google Forms creation and question metadata as well. There is also a `FakeGoogleDriveService`, implying the Google adapter is swappable for testing or local development.

12. RabbitMQ is used as the asynchronous handoff mechanism, not as a business store. `ProducerService` and `ConsumerService` abstract message transport so the domain pipeline can enqueue polling work and process it later. This is the main boundary that separates scheduled discovery of work from slower I/O-bound form fetching and batch writes.

13. Redis is not just a simple cache; it has helper classes for batching, JSON caching, and pipeline execution. That implies the app frequently writes or reads multiple cache keys together, and performance improvements depend on reducing round trips. Architecture-wise, Redis sits in front of repeat-read use cases rather than as a source of truth.

14. The deployment/runtime side is a containerized Spring Boot service with Docker, Nginx, and EC2. The README indicates Nginx reverse proxying and blue-green style deployment, while the repo includes `Dockerfile` and `fly.toml` for container deployment support. Monitoring is externalized to Prometheus, Loki, and Grafana, which fit the logging/tracing setup in `global`.

15. Overall, the diagram should show a Spring Boot monolith with four main business domains, a security/authentication path, a scheduled async ingestion pipeline, and three different data stores serving different roles: PostgreSQL for operational state, DynamoDB for bulk form responses, and Redis for performance caching. The important boundaries are HTTP vs background jobs, command vs query flows, and domain services vs infra adapters.

Main entry points: [`src/main/java/com/example/backend/domain/event/service/command/EventCommandServiceImpl.java`](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/service/command/EventCommandServiceImpl.java) (Event write svc), [`src/main/java/com/example/backend/application/facade/EventFacadeImpl.java`](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/application/facade/EventFacadeImpl.java) (Event facade), [`src/main/java/com/example/backend/application/facade/ResponseFacadeImpl.java`](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/application/facade/ResponseFacadeImpl.java) (Response facade), [`src/main/java/com/example/backend/domain/response/service/command/ResponseCommandServiceImpl.java`](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/service/command/ResponseCommandServiceImpl.java) (Response write svc)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_backend(("HubSpace<br/>Spring Boot app"))
  node_event_facade["Event facade<br/>orchestrator"]
  node_response_facade["Response facade<br/>orchestrator"]
end

subgraph group_event["Event domain"]
  node_event_cmd_ctrl["Event command<br/>mvc controller"]
  node_event_qry_ctrl["Event query<br/>mvc controller"]
  node_event_form_ctrl["Form endpoints<br/>mvc controller"]
  node_event_file_ctrl["File endpoints<br/>mvc controller"]
  node_event_cmd_svc["Event write svc<br/>domain service"]
  node_event_qry_svc["Event read svc<br/>domain service"]
end

subgraph group_response["Response domain"]
  node_resp_qry_ctrl["Response query<br/>mvc controller"]
  node_resp_cmd_svc["Response write svc<br/>domain service"]
  node_resp_qry_svc["Response read svc<br/>domain service"]
end

subgraph group_auth["Auth domain"]
  node_user_ctrl["User API<br/>mvc controller"]
  node_jwt_ctrl["JWT API<br/>mvc controller<br/>[JwtController.java]"]
  node_user_svc["User svc<br/>auth service<br/>[UserService.java]"]
  node_jwt_svc["JWT svc<br/>token service<br/>[JwtService.java]"]
end

subgraph group_platform["Platform"]
  node_security["Security"]
  node_jobs["Polling jobs<br/>scheduler<br/>[Poller.java]"]
  node_mq["RabbitMQ<br/>message broker"]
  node_google["Google Drive<br/>external adapter"]
  node_crosscut["Global layer<br/>api/error/logging"]
end

subgraph group_storage["Data stores"]
  node_redis[("Redis cache<br/>cache layer")]
  node_postgres[("PostgreSQL<br/>relational store")]
  node_dynamo[("DynamoDB<br/>document store")]
end

node_backend -->|"bootstraps"| node_event_facade
node_backend -->|"bootstraps"| node_response_facade
node_event_cmd_ctrl -->|"calls"| node_event_cmd_svc
node_event_qry_ctrl -->|"calls"| node_event_qry_svc
node_event_form_ctrl -->|"orchestrates"| node_event_facade
node_event_file_ctrl -->|"calls"| node_event_cmd_svc
node_resp_qry_ctrl -->|"orchestrates"| node_response_facade
node_user_ctrl -->|"calls"| node_user_svc
node_jwt_ctrl -->|"calls"| node_jwt_svc
node_security -->|"authenticates"| node_user_svc
node_security -->|"issues tokens"| node_jwt_svc
node_security -->|"handles errors"| node_crosscut
node_event_facade -->|"coordinates"| node_event_cmd_svc
node_event_facade -->|"coordinates"| node_event_qry_svc
node_response_facade -->|"coordinates"| node_resp_cmd_svc
node_response_facade -->|"coordinates"| node_resp_qry_svc
node_jobs -->|"publishes"| node_mq
node_mq -->|"consumes"| node_google
node_mq -->|"dispatches"| node_resp_cmd_svc
node_event_qry_svc -->|"reads cache"| node_redis
node_event_cmd_svc -->|"writes state"| node_postgres
node_resp_cmd_svc -->|"writes responses"| node_dynamo
node_resp_qry_svc -->|"reads cache"| node_redis
node_resp_cmd_svc -->|"updates cache"| node_redis
node_event_cmd_svc -->|"updates cache"| node_redis
node_user_svc -->|"writes users"| node_postgres
node_jwt_svc -->|"stores refresh"| node_postgres
node_crosscut -.->|"wraps failures"| node_postgres

click node_backend "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/BackendApplication.java"
click node_event_facade "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/application/facade/EventFacadeImpl.java"
click node_response_facade "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/application/facade/ResponseFacadeImpl.java"
click node_event_cmd_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/EventCommandController.java"
click node_event_qry_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/EventQueryController.java"
click node_event_form_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/form/EventFormController.java"
click node_event_file_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/file/EventFileController.java"
click node_event_cmd_svc "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/service/command/EventCommandServiceImpl.java"
click node_event_qry_svc "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/service/query/EventQueryServiceImpl.java"
click node_resp_qry_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/controller/ResponseQueryController.java"
click node_resp_cmd_svc "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/service/command/ResponseCommandServiceImpl.java"
click node_resp_qry_svc "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/service/query/ResponseQueryServiceImpl.java"
click node_user_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/user/controller/UserController.java"
click node_jwt_ctrl "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/jwt/controller/JwtController.java"
click node_user_svc "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/user/service/UserService.java"
click node_jwt_svc "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/jwt/service/JwtService.java"
click node_security "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/global/config/SecurityConfig.java"
click node_jobs "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/scheduler/Poller.java"
click node_mq "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/rabbitmq/service/ProducerServiceImpl.java"
click node_google "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/google/drive/GoogleDriveServiceImpl.java"
click node_redis "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/redis/AbstractRedisCache.java"
click node_dynamo "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/global/config/DynamoDBConfig.java"
click node_crosscut "https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/global/error/GlobalExceptionHandler.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_backend,node_event_facade,node_response_facade toneBlue
class node_event_cmd_ctrl,node_event_qry_ctrl,node_event_form_ctrl,node_event_file_ctrl,node_event_cmd_svc,node_event_qry_svc toneAmber
class node_resp_qry_ctrl,node_resp_cmd_svc,node_resp_qry_svc toneMint
class node_user_ctrl,node_jwt_ctrl,node_user_svc,node_jwt_svc toneRose
class node_security,node_jobs,node_mq,node_google,node_crosscut toneIndigo
class node_redis,node_postgres,node_dynamo toneTeal
```

## Components

### Application

Use-case orchestration and controller entrypoints

- [HubSpace](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/BackendApplication.java): Spring Boot app · Application bootstrap · `src/main/java/com/example/backend/BackendApplication.java`
- [Event facade](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/application/facade/EventFacadeImpl.java): orchestrator · Coordinates event use cases · `src/main/java/com/example/backend/application/facade/EventFacadeImpl.java`
- [Response facade](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/application/facade/ResponseFacadeImpl.java): orchestrator · Coordinates response use cases · `src/main/java/com/example/backend/application/facade/ResponseFacadeImpl.java`

### Event domain

Core polling and event management workflow

- [Event command](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/EventCommandController.java): mvc controller · Event write endpoints · `src/main/java/com/example/backend/domain/event/controller/EventCommandController.java`
- [Event query](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/EventQueryController.java): mvc controller · Event read endpoints · `src/main/java/com/example/backend/domain/event/controller/EventQueryController.java`
- [Form endpoints](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/form/EventFormController.java): mvc controller · Event form-related endpoints · `src/main/java/com/example/backend/domain/event/controller/form/EventFormController.java`
- [File endpoints](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/controller/file/EventFileController.java): mvc controller · Event file-related endpoints · `src/main/java/com/example/backend/domain/event/controller/file/EventFileController.java`
- [Event write svc](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/service/command/EventCommandServiceImpl.java): domain service · Transactional event commands · `src/main/java/com/example/backend/domain/event/service/command/EventCommandServiceImpl.java`
- [Event read svc](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/event/service/query/EventQueryServiceImpl.java): domain service · Read-optimized event queries · `src/main/java/com/example/backend/domain/event/service/query/EventQueryServiceImpl.java`

### Response domain

Collected form submission handling

- [Response query](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/controller/ResponseQueryController.java): mvc controller · Response read endpoints · `src/main/java/com/example/backend/domain/response/controller/ResponseQueryController.java`
- [Response write svc](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/service/command/ResponseCommandServiceImpl.java): domain service · Response persistence and matching · `src/main/java/com/example/backend/domain/response/service/command/ResponseCommandServiceImpl.java`
- [Response read svc](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/response/service/query/ResponseQueryServiceImpl.java): domain service · Response lookup and retrieval · `src/main/java/com/example/backend/domain/response/service/query/ResponseQueryServiceImpl.java`

### Auth domain

User login and JWT session flow

- [User API](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/user/controller/UserController.java): mvc controller · User-related HTTP endpoints · `src/main/java/com/example/backend/domain/user/controller/UserController.java`
- [JWT API](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/jwt/controller/JwtController.java): mvc controller · Token-related HTTP endpoints · `src/main/java/com/example/backend/domain/jwt/controller/JwtController.java`
- [User svc](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/user/service/UserService.java): auth service · OAuth/user management logic · `src/main/java/com/example/backend/domain/user/service/UserService.java`
- [JWT svc](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/domain/jwt/service/JwtService.java): token service · JWT issuing and refresh handling · `src/main/java/com/example/backend/domain/jwt/service/JwtService.java`

### Platform

Cross-cutting concerns, jobs, and infrastructure adapters

- [Security](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/global/config/SecurityConfig.java): spring security config · Filters, handlers, and auth setup · `src/main/java/com/example/backend/global/config/SecurityConfig.java`
- [Polling jobs](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/scheduler/Poller.java): scheduler · Periodic discovery and polling workflow · `src/main/java/com/example/backend/infra/scheduler/Poller.java`
- [RabbitMQ](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/rabbitmq/service/ProducerServiceImpl.java): message broker · Async handoff between scheduler and consumers · `src/main/java/com/example/backend/infra/rabbitmq/service/ProducerServiceImpl.java`
- [Google Drive](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/google/drive/GoogleDriveServiceImpl.java): external adapter · Google Forms response fetching · `src/main/java/com/example/backend/infra/google/drive/GoogleDriveServiceImpl.java`
- [Global layer](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/global/error/GlobalExceptionHandler.java): api/error/logging · Exceptions, tracing, and shared response handling · `src/main/java/com/example/backend/global/error/GlobalExceptionHandler.java`

### Data stores

Primary persistence and cache backends

- [Redis cache](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/infra/redis/AbstractRedisCache.java): cache layer · Cached event and response lookups · `src/main/java/com/example/backend/infra/redis/AbstractRedisCache.java`
- **PostgreSQL**: relational store · Operational JPA state
- [DynamoDB](https://github.com/holychann/hubspace-public/blob/main/src/main/java/com/example/backend/global/config/DynamoDBConfig.java): document store · Bulk Google Form response storage · `src/main/java/com/example/backend/global/config/DynamoDBConfig.java`

## Connections

- HubSpace → Event facade: bootstraps · Application starts the orchestration layer
- HubSpace → Response facade: bootstraps · Application starts the orchestration layer
- Event command → Event write svc: calls · Command endpoints route into event write logic
- Event query → Event read svc: calls · Query endpoints route into read logic
- Form endpoints → Event facade: orchestrates · Form endpoints use facade-level coordination
- File endpoints → Event write svc: calls · File endpoints delegate to command services
- Response query → Response facade: orchestrates · Response reads go through facade coordination
- User API → User svc: calls · User endpoints delegate to user service
- JWT API → JWT svc: calls · Token endpoints delegate to JWT service
- Security → User svc: authenticates · Security setup integrates user login flow
- Security → JWT svc: issues tokens · Security setup integrates JWT lifecycle handling
- Security → Global layer: handles errors · Auth failures and shared exceptions converge here
- Event facade → Event write svc: coordinates · Facade combines command-side event operations
- Event facade → Event read svc: coordinates · Facade combines query-side event operations
- Response facade → Response write svc: coordinates · Facade coordinates response persistence workflows
- Response facade → Response read svc: coordinates · Facade coordinates response read workflows
- Polling jobs → RabbitMQ: publishes · Schedulers enqueue polling work asynchronously
- RabbitMQ → Google Drive: consumes · Consumers trigger Google form fetches
- RabbitMQ → Response write svc: dispatches · Async messages drive response ingestion and writes
- Event read svc → Redis cache: reads cache · Event queries are cache-backed
- Event write svc → PostgreSQL: writes state · Event writes persist relational state
- Response write svc → DynamoDB: writes responses · Collected form submissions land in DynamoDB
- Response read svc → Redis cache: reads cache · Repeated response lookups use Redis
- Response write svc → Redis cache: updates cache · Writes refresh derived response caches
- Event write svc → Redis cache: updates cache · Event mutations refresh derived caches
- User svc → PostgreSQL: writes users · User and auth records are persisted relationally
- JWT svc → PostgreSQL: stores refresh · Refresh tokens are persisted relationally
- Global layer → PostgreSQL: wraps failures · Platform errors span persistence and service layers
