How abhip47/synq works
1. Overall architecture
SYNQ is a server-rendered Spring Boot monolith built around Spring MVC, Spring Security, Spring Data JPA, and Thymeleaf. It is not a separate SPA frontend plus API backend; instead, HTML pages are rendered on the server and enhanced with a small amount of JavaScript for interactive flows.
2. Runtime and build boundaries
The app runs on Java/Maven via the Maven Wrapper, with Node/npm used only to build frontend assets. Tailwind compiles input.css into output.css, which is then served as static content from Spring Boot.
3. Request entry points
The main entry class is SynqApplication. HTTP traffic is split across several controllers:
- RootController and PageController for public-facing pages
- AuthController for login/registration flows
- UserController for profile/account actions
- ContactController for contact management
- ApiController for asynchronous endpoints used by the browser JS
4. Presentation layer
Views are Thymeleaf templates under src/main/resources/templates, with shared fragments like base, navbar, sidebar, and user_navbar. The user/ templates indicate a distinct authenticated area with dashboard, profile, contact search, contact editing, and success/error screens.
5. Client-side interaction
Static JavaScript in src/main/resources/static/js supports richer UX for contact operations, admin interactions, and general page behavior. The README indicates file preview and confirmation dialog behavior, so the browser handles some immediate feedback before server-side actions complete.
6. Domain model
The core entities are:
- User — authenticated account and profile data
- Contact — user-owned contact records
- SocialLink — additional profile/contact metadata
Supporting enums like Provider and MessageType suggest identity source tracking and message/status categorization.
7. Business/service layer
Business logic is separated into service interfaces and implementations:
- UserService / UserServiceImpl
- ContactService / ContactServiceImpl
- EmailService / EmailServiceImpl
- ImageService / ImageServiceImpl
This layer is where contact CRUD, user onboarding, email dispatch, and image handling are coordinated before hitting repositories or external services.
8. Persistence boundary
UserRepo and ContactRepo are Spring Data repositories, so the application persists domain data through JPA to a relational database. The README indicates support for PostgreSQL or MySQL, making the database a replaceable infrastructure dependency behind the repository layer.
9. Security and identity
Security is a major subsystem:
- SecurityConfig defines the web security rules
- form login and Google OAuth2 are both supported
- CustomOAuth2UserService, OAuthenticationSuccessHandler, and AuthFailureHandler customize external login behavior
- UserDetailsImpl and SecurityCustomDetailService adapt application users into Spring Security’s authentication model
- BCrypt is used for password handling
This layer also enforces authenticated access to user-owned data, which is important for preventing direct-object access across contacts.
10. Cloud and media workflow
ImageService plus the file validator annotations (ValidFile, FileValidator) indicate controlled file upload handling. The README identifies Cloudinary as the external image store/processor, so image upload is a distinct pipeline: browser preview first, server validation next, then offloading of media storage/transformations to Cloudinary.
11. Forms, validation, and error handling
The forms/ package contains MVC request models such as UserForm, ContactForm, and ContactSearchForm, keeping request binding separate from persistent entities. Helper classes like Message, AppConstants, SessionHelper, and ResourceNotFoundException support flash/session state, shared constants, and consistent error propagation.
12. Configuration and environment split
application-dev.properties and application-prod.properties show environment-specific configuration boundaries for database, security, and cloud credentials. AppConfig and the security-related config classes centralize framework wiring rather than scattering it across controllers.
13. How the main data flow works
A typical user flow is: browser request → controller → service → repository/database, with security checks applied before data access and optional Cloudinary/email side effects in the service layer. For interactive contact actions, the browser JS can call ApiController endpoints instead of doing full page reloads.
14. Diagramming takeaway
If you draw the architecture, the key boundaries are: browser/UI, Spring MVC controllers, service/business layer, JPA repositories, database, and two external integrations: Google OAuth2 and Cloudinary. The app’s center of gravity is authenticated, user-scoped contact management with server-side rendering and selective async enhancement.
Main entry points: ContactService.java ContactSvc · RootController.java Root · UserService.java UserSvc · SecurityConfig.java Security
Components 28
Runtime
Build and application entrypoints
- Synq · Main application entrypoint
src/main/java/com/synq/SynqApplication.java
Web
Server-rendered pages and request handling
- Root · Public landing and top-level routes
src/main/java/com/synq/controller/RootController.java - Pages · Static and informational pages
src/main/java/com/synq/controller/PageController.java - Auth · Login and registration flows
src/main/java/com/synq/controller/AuthController.java - User · Profile and account actions
src/main/java/com/synq/controller/UserController.java - Contacts · Contact management routes
src/main/java/com/synq/controller/ContactController.java - API · Async endpoints for browser JS
src/main/java/com/synq/controller/ApiController.java
Domain
Core entities and forms
- User · Account and profile model
src/main/java/com/synq/entity/User.java - Contact · User-owned contact record
src/main/java/com/synq/entity/Contact.java - SocialLink · Profile and contact metadata
src/main/java/com/synq/entity/SocialLink.java - UserForm · User binding model
src/main/java/com/synq/forms/UserForm.java - ContactForm · Contact binding model
src/main/java/com/synq/forms/ContactForm.java - SearchForm · Contact search binding model
src/main/java/com/synq/forms/ContactSearchForm.java
Services
Business logic and integrations
- UserSvc · User onboarding and profile logic
src/main/java/com/synq/service/UserService.java - ContactSvc · Contact CRUD and ownership logic
src/main/java/com/synq/service/ContactService.java - EmailSvc · Mail dispatch and notifications
src/main/java/com/synq/service/EmailService.java - ImageSvc · Upload and media handling
src/main/java/com/synq/service/ImageService.java
Data
Persistence boundary
- UserRepo · User persistence access
src/main/java/com/synq/repository/UserRepo.java - ContactRepo · Contact persistence access
src/main/java/com/synq/repository/ContactRepo.java
Infrastructure
Security, configuration, and external integrations
- Security · HTTP security and auth rules
src/main/java/com/synq/config/SecurityConfig.java - OAuth2 · Google OAuth2 user mapping
src/main/java/com/synq/config/CustomOAuth2UserService.java - Success · OAuth login success handling
src/main/java/com/synq/config/OAuthenticationSuccessHandler.java - Failure · Authentication failure handling
src/main/java/com/synq/config/AuthFailureHandler.java - Details · UserDetails bridge for Spring Security
src/main/java/com/synq/config/UserDetailsImpl.java - AuthUserSvc · Loads users for authentication
src/main/java/com/synq/service/serviceImplementation/SecurityCustomDetailService.java - AppConfig · Application wiring and cross-cutting config
src/main/java/com/synq/config/AppConfig.java - FileValidator · File upload validation
src/main/java/com/synq/validators/FileValidator.java - ValidFile · File upload constraint
src/main/java/com/synq/validators/ValidFile.java
Connections 31
- Synq → Root: bootstraps · Application starts the web tier
- Synq → Security: configures · Bootstraps security and app wiring
- Root → Pages: routes · Public pages are split across controllers
- Root → Auth: routes · Authentication pages and forms
- Root → User: routes · Authenticated user actions
- Root → Contacts: routes · Contact management routes
- Root → API: routes · Async browser endpoints
- Auth → UserSvc: uses · Registration and account setup
- User → UserSvc: uses · Profile and account updates
- Contacts → ContactSvc: uses · Contact CRUD workflow
- API → ContactSvc: uses · AJAX contact operations
- UserSvc → UserRepo: persists · User data persistence
- ContactSvc → ContactRepo: persists · Contact data persistence
- UserSvc → ImageSvc: delegates · Profile image handling
- UserSvc → EmailSvc: delegates · Onboarding and notification mail
- ContactSvc → FileValidator: validates · Checks uploaded files
- FileValidator → ValidFile: implements · Constraint annotation support
- Security → OAuth2: uses · OAuth2 login customization
- Security → Success: uses · Login success flow
- Security → Failure: uses · Login failure flow
- Security → Details: uses · Spring Security user model
- Details → AuthUserSvc: backed by · Loads application users
- AuthUserSvc → UserRepo: reads · Authentication user lookup
- UserSvc → User: manages · User domain model
- ContactSvc → Contact: manages · Contact domain model
- ContactSvc → SocialLink: manages · Associated contact metadata
- User → UserForm: binds · Profile form binding
- Contacts → ContactForm: binds · Contact form binding
- Contacts → SearchForm: binds · Search form binding
- User → AppConfig: uses · Shared app wiring
- ContactSvc → ImageSvc: uploads · Media offload pipeline