# abhip47/synq architecture

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

- Interactive diagram: https://gitdiagram.com/abhip47/synq
- Repository: https://github.com/abhip47/synq

## Overview

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: [`src/main/java/com/synq/service/ContactService.java`](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/ContactService.java) (ContactSvc), [`src/main/java/com/synq/controller/RootController.java`](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/RootController.java) (Root), [`src/main/java/com/synq/service/UserService.java`](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/UserService.java) (UserSvc), [`src/main/java/com/synq/config/SecurityConfig.java`](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/SecurityConfig.java) (Security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_synq_app(("Synq<br/>Spring Boot app"))
end

subgraph group_web["Web"]
  node_root_controller["Root<br/>MVC controller"]
  node_page_controller["Pages<br/>MVC controller"]
  node_auth_controller["Auth<br/>MVC controller"]
  node_user_controller["User<br/>MVC controller"]
  node_contact_controller["Contacts<br/>MVC controller"]
  node_api_controller["API<br/>MVC controller<br/>[ApiController.java]"]
end

subgraph group_domain["Domain"]
  node_user_entity[("User<br/>JPA entity<br/>[User.java]")]
  node_contact_entity[("Contact<br/>JPA entity<br/>[Contact.java]")]
  node_social_link[("SocialLink<br/>JPA entity<br/>[SocialLink.java]")]
  node_user_form["UserForm<br/>request form<br/>[UserForm.java]"]
  node_contact_form["ContactForm<br/>request form<br/>[ContactForm.java]"]
  node_contact_search_form["SearchForm<br/>request form"]
end

subgraph group_services["Services"]
  node_user_service{{"UserSvc<br/>[UserService.java]"}}
  node_contact_service{{"ContactSvc"}}
  node_email_service{{"EmailSvc<br/>[EmailService.java]"}}
  node_image_service{{"ImageSvc<br/>[ImageService.java]"}}
end

subgraph group_data["Data"]
  node_user_repo[("UserRepo<br/>JPA repository<br/>[UserRepo.java]")]
  node_contact_repo[("ContactRepo<br/>JPA repository<br/>[ContactRepo.java]")]
end

subgraph group_infra["Infrastructure"]
  node_security_config["Security"]
  node_oauth_service["OAuth2<br/>auth adapter"]
  node_success_handler["Success<br/>auth handler"]
  node_failure_handler["Failure<br/>auth handler"]
  node_details_service["Details<br/>security adapter"]
  node_security_user_service["AuthUserSvc<br/>security service"]
  node_app_config["AppConfig<br/>framework config<br/>[AppConfig.java]"]
  node_file_validator["FileValidator<br/>[FileValidator.java]"]
  node_valid_file["ValidFile<br/>annotation<br/>[ValidFile.java]"]
end

node_synq_app -->|"bootstraps"| node_root_controller
node_synq_app -->|"configures"| node_security_config
node_root_controller -->|"routes"| node_page_controller
node_root_controller -->|"routes"| node_auth_controller
node_root_controller -->|"routes"| node_user_controller
node_root_controller -->|"routes"| node_contact_controller
node_root_controller -->|"routes"| node_api_controller
node_auth_controller -->|"uses"| node_user_service
node_user_controller -->|"uses"| node_user_service
node_contact_controller -->|"uses"| node_contact_service
node_api_controller -->|"uses"| node_contact_service
node_user_service -->|"persists"| node_user_repo
node_contact_service -->|"persists"| node_contact_repo
node_user_service -->|"delegates"| node_image_service
node_user_service -->|"delegates"| node_email_service
node_contact_service -->|"validates"| node_file_validator
node_file_validator -->|"implements"| node_valid_file
node_security_config -->|"uses"| node_oauth_service
node_security_config -->|"uses"| node_success_handler
node_security_config -->|"uses"| node_failure_handler
node_security_config -->|"uses"| node_details_service
node_details_service -->|"backed by"| node_security_user_service
node_security_user_service -->|"reads"| node_user_repo
node_user_service -->|"manages"| node_user_entity
node_contact_service -->|"manages"| node_contact_entity
node_contact_service -->|"manages"| node_social_link
node_user_controller -->|"binds"| node_user_form
node_contact_controller -->|"binds"| node_contact_form
node_contact_controller -->|"binds"| node_contact_search_form
node_user_controller -.->|"uses"| node_app_config
node_contact_service -->|"uploads"| node_image_service

click node_synq_app "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/SynqApplication.java"
click node_root_controller "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/RootController.java"
click node_page_controller "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/PageController.java"
click node_auth_controller "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/AuthController.java"
click node_user_controller "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/UserController.java"
click node_contact_controller "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/ContactController.java"
click node_api_controller "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/ApiController.java"
click node_user_entity "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/entity/User.java"
click node_contact_entity "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/entity/Contact.java"
click node_social_link "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/entity/SocialLink.java"
click node_user_form "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/forms/UserForm.java"
click node_contact_form "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/forms/ContactForm.java"
click node_contact_search_form "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/forms/ContactSearchForm.java"
click node_user_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/UserService.java"
click node_contact_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/ContactService.java"
click node_email_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/EmailService.java"
click node_image_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/ImageService.java"
click node_user_repo "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/repository/UserRepo.java"
click node_contact_repo "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/repository/ContactRepo.java"
click node_security_config "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/SecurityConfig.java"
click node_oauth_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/CustomOAuth2UserService.java"
click node_success_handler "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/OAuthenticationSuccessHandler.java"
click node_failure_handler "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/AuthFailureHandler.java"
click node_details_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/UserDetailsImpl.java"
click node_security_user_service "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/serviceImplementation/SecurityCustomDetailService.java"
click node_app_config "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/AppConfig.java"
click node_file_validator "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/validators/FileValidator.java"
click node_valid_file "https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/validators/ValidFile.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_synq_app toneBlue
class node_root_controller,node_page_controller,node_auth_controller,node_user_controller,node_contact_controller,node_api_controller toneAmber
class node_user_entity,node_contact_entity,node_social_link,node_user_form,node_contact_form,node_contact_search_form toneMint
class node_user_service,node_contact_service,node_email_service,node_image_service toneRose
class node_user_repo,node_contact_repo toneIndigo
class node_security_config,node_oauth_service,node_success_handler,node_failure_handler,node_details_service,node_security_user_service,node_app_config,node_file_validator,node_valid_file toneTeal
```

## Components

### Runtime

Build and application entrypoints

- [Synq](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/SynqApplication.java): Spring Boot app · Main application entrypoint · `src/main/java/com/synq/SynqApplication.java`

### Web

Server-rendered pages and request handling

- [Root](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/RootController.java): MVC controller · Public landing and top-level routes · `src/main/java/com/synq/controller/RootController.java`
- [Pages](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/PageController.java): MVC controller · Static and informational pages · `src/main/java/com/synq/controller/PageController.java`
- [Auth](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/AuthController.java): MVC controller · Login and registration flows · `src/main/java/com/synq/controller/AuthController.java`
- [User](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/UserController.java): MVC controller · Profile and account actions · `src/main/java/com/synq/controller/UserController.java`
- [Contacts](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/ContactController.java): MVC controller · Contact management routes · `src/main/java/com/synq/controller/ContactController.java`
- [API](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/controller/ApiController.java): MVC controller · Async endpoints for browser JS · `src/main/java/com/synq/controller/ApiController.java`

### Domain

Core entities and forms

- [User](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/entity/User.java): JPA entity · Account and profile model · `src/main/java/com/synq/entity/User.java`
- [Contact](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/entity/Contact.java): JPA entity · User-owned contact record · `src/main/java/com/synq/entity/Contact.java`
- [SocialLink](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/entity/SocialLink.java): JPA entity · Profile and contact metadata · `src/main/java/com/synq/entity/SocialLink.java`
- [UserForm](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/forms/UserForm.java): request form · User binding model · `src/main/java/com/synq/forms/UserForm.java`
- [ContactForm](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/forms/ContactForm.java): request form · Contact binding model · `src/main/java/com/synq/forms/ContactForm.java`
- [SearchForm](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/forms/ContactSearchForm.java): request form · Contact search binding model · `src/main/java/com/synq/forms/ContactSearchForm.java`

### Services

Business logic and integrations

- [UserSvc](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/UserService.java): service · User onboarding and profile logic · `src/main/java/com/synq/service/UserService.java`
- [ContactSvc](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/ContactService.java): service · Contact CRUD and ownership logic · `src/main/java/com/synq/service/ContactService.java`
- [EmailSvc](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/EmailService.java): service · Mail dispatch and notifications · `src/main/java/com/synq/service/EmailService.java`
- [ImageSvc](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/ImageService.java): service · Upload and media handling · `src/main/java/com/synq/service/ImageService.java`

### Data

Persistence boundary

- [UserRepo](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/repository/UserRepo.java): JPA repository · User persistence access · `src/main/java/com/synq/repository/UserRepo.java`
- [ContactRepo](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/repository/ContactRepo.java): JPA repository · Contact persistence access · `src/main/java/com/synq/repository/ContactRepo.java`

### Infrastructure

Security, configuration, and external integrations

- [Security](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/SecurityConfig.java): Spring Security config · HTTP security and auth rules · `src/main/java/com/synq/config/SecurityConfig.java`
- [OAuth2](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/CustomOAuth2UserService.java): auth adapter · Google OAuth2 user mapping · `src/main/java/com/synq/config/CustomOAuth2UserService.java`
- [Success](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/OAuthenticationSuccessHandler.java): auth handler · OAuth login success handling · `src/main/java/com/synq/config/OAuthenticationSuccessHandler.java`
- [Failure](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/AuthFailureHandler.java): auth handler · Authentication failure handling · `src/main/java/com/synq/config/AuthFailureHandler.java`
- [Details](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/UserDetailsImpl.java): security adapter · UserDetails bridge for Spring Security · `src/main/java/com/synq/config/UserDetailsImpl.java`
- [AuthUserSvc](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/service/serviceImplementation/SecurityCustomDetailService.java): security service · Loads users for authentication · `src/main/java/com/synq/service/serviceImplementation/SecurityCustomDetailService.java`
- [AppConfig](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/config/AppConfig.java): framework config · Application wiring and cross-cutting config · `src/main/java/com/synq/config/AppConfig.java`
- [FileValidator](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/validators/FileValidator.java): validator · File upload validation · `src/main/java/com/synq/validators/FileValidator.java`
- [ValidFile](https://github.com/abhip47/synq/blob/main/src/main/java/com/synq/validators/ValidFile.java): annotation · File upload constraint · `src/main/java/com/synq/validators/ValidFile.java`

## Connections

- 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
