How holychann/hubspace-public works
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: EventCommandServiceImpl.java Event write svc · EventFacadeImpl.java Event facade · ResponseFacadeImpl.java Response facade · ResponseCommandServiceImpl.java Response write svc
Components 24
Application
Use-case orchestration and controller entrypoints
- HubSpace · Application bootstrap
src/main/java/com/example/backend/BackendApplication.java - Event facade · Coordinates event use cases
src/main/java/com/example/backend/application/facade/EventFacadeImpl.java - Response facade · Coordinates response use cases
src/main/java/com/example/backend/application/facade/ResponseFacadeImpl.java
Event domain
Core polling and event management workflow
- Event command · Event write endpoints
src/main/java/com/example/backend/domain/event/controller/EventCommandController.java - Event query · Event read endpoints
src/main/java/com/example/backend/domain/event/controller/EventQueryController.java - Form endpoints · Event form-related endpoints
src/main/java/com/example/backend/domain/event/controller/form/EventFormController.java - File endpoints · Event file-related endpoints
src/main/java/com/example/backend/domain/event/controller/file/EventFileController.java - Event write svc · Transactional event commands
src/main/java/com/example/backend/domain/event/service/command/EventCommandServiceImpl.java - Event read svc · Read-optimized event queries
src/main/java/com/example/backend/domain/event/service/query/EventQueryServiceImpl.java
Response domain
Collected form submission handling
- Response query · Response read endpoints
src/main/java/com/example/backend/domain/response/controller/ResponseQueryController.java - Response write svc · Response persistence and matching
src/main/java/com/example/backend/domain/response/service/command/ResponseCommandServiceImpl.java - Response read svc · 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 · User-related HTTP endpoints
src/main/java/com/example/backend/domain/user/controller/UserController.java - JWT API · Token-related HTTP endpoints
src/main/java/com/example/backend/domain/jwt/controller/JwtController.java - User svc · OAuth/user management logic
src/main/java/com/example/backend/domain/user/service/UserService.java - JWT svc · 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 · Filters, handlers, and auth setup
src/main/java/com/example/backend/global/config/SecurityConfig.java - Polling jobs · Periodic discovery and polling workflow
src/main/java/com/example/backend/infra/scheduler/Poller.java - RabbitMQ · Async handoff between scheduler and consumers
src/main/java/com/example/backend/infra/rabbitmq/service/ProducerServiceImpl.java - Google Drive · Google Forms response fetching
src/main/java/com/example/backend/infra/google/drive/GoogleDriveServiceImpl.java - Global layer · 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 · Cached event and response lookups
src/main/java/com/example/backend/infra/redis/AbstractRedisCache.java - PostgreSQL · Operational JPA state
- DynamoDB · Bulk Google Form response storage
src/main/java/com/example/backend/global/config/DynamoDBConfig.java
Connections 28
- 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