# nikolaiunknown/socialmedia architecture

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

- Interactive diagram: https://gitdiagram.com/nikolaiunknown/socialmedia
- Repository: https://github.com/nikolaiunknown/socialmedia

## Overview

#### Purpose and Runtime

SocialMedia is a containerized Java 23/Spring Boot backend for social networking: identity, profiles, friendship, posts/images/likes, user search, and real-time chat. The application entry point is `src/main/java/com/media/socialmedia/SocialMediaApplication.java`; HTTP APIs, static assets, and Swagger/OpenAPI are served by the Spring process.

- `src/main/resources/static/api-docs.yaml`
- `Dockerfile`
- `docker-compose.yaml`

#### API and Application Boundary

REST controllers are the external HTTP boundary. They accept request DTOs, invoke domain services, and return response DTOs. Major endpoint groups cover authentication, profiles/social graph, posts/media, administration, search, and chat. `ChatHandler` is a separate real-time message ingress alongside conventional controllers.

- `src/main/java/com/media/socialmedia/Controllers/AuthController.java`
- `src/main/java/com/media/socialmedia/Controllers/PostController.java`
- `src/main/java/com/media/socialmedia/Controllers/ChatHandler.java`

#### Authentication and Authorization

Registration and login flow through registration/user services and issue JWT access tokens plus refresh-token state. Refresh tokens are persisted and exposed through an HTTP-only cookie. Spring Security config and a token filter establish authenticated request context; authorization distinguishes Admin and regular users.

- `src/main/java/com/media/socialmedia/Configs/SecurityConfig.java`
- `src/main/java/com/media/socialmedia/Security/TokenFilter.java`
- `src/main/java/com/media/socialmedia/Services/RefreshTokenService.java`

#### Core Social Domain

JPA entities model durable users, posts, chats/messages, and refresh tokens. Services implement higher-level social operations: profile changes, friend invitations/relationships, blacklist enforcement, likes, posts, and admin actions. Controllers should not directly own persistence logic; repositories form the relational persistence boundary.

- `src/main/java/com/media/socialmedia/Entity/User.java`
- `src/main/java/com/media/socialmedia/Entity/Post.java`
- `src/main/java/com/media/socialmedia/Services/FriendService.java`

#### Chat and WebSocket Flow

WebSocket/STOMP configuration exposes real-time chat transport. Incoming messages are handled through chat-facing controller/handler code, then chat services validate access/blacklist conditions, apply the stated per-user Bucket4J rate limit, persist chats/messages, and produce message DTOs. Chat access failures have domain-specific exceptions.

- `src/main/java/com/media/socialmedia/Configs/WebSocketConfig.java`
- `src/main/java/com/media/socialmedia/Services/ChatService.java`
- `src/main/java/com/media/socialmedia/Entity/Message.java`

#### Data, Cache, and Search Infrastructure

PostgreSQL is the system of record, initialized with schema SQL. Redis supports caching through a dedicated configuration/service layer. Elasticsearch holds `UserSearchDocument` records, queried through a separate search repository/service for RU/EN full-text user search. These are distinct storage concerns rather than interchangeable repositories.

- `init/postgres/tables.sql`
- `src/main/java/com/media/socialmedia/Services/CacheService.java`
- `src/main/java/com/media/socialmedia/Services/SearchService.java`

#### Media and Deployment

Image upload is handled at the HTTP layer and is intended for static serving from a Docker-mounted volume. Docker Compose runs four services: Spring backend, PostgreSQL 17, Redis 7.2.5, and Elasticsearch 7.17.28; Elasticsearch users are initialized from repository-provided data.

- `src/main/java/com/media/socialmedia/Controllers/ImageController.java`
- `init/elasticsearch/users.json`
- `docker-compose.yaml`

Main entry points: [`src/main/java/com/media/socialmedia/Controllers/AuthController.java`](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/AuthController.java) (REST controllers), [`init/postgres/tables.sql`](https://github.com/nikolaiunknown/socialmedia/blob/master/init/postgres/tables.sql) (PostgreSQL 17), [`docker-compose.yaml`](https://github.com/nikolaiunknown/socialmedia/blob/master/docker-compose.yaml) (Docker Compose), [`src/main/java/com/media/socialmedia/Services/FriendService.java`](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/FriendService.java) (Social services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Spring application"]
  node_boot["SocialMedia application<br/>Spring Boot entry point"]
  node_rest["REST controllers<br/>HTTP boundary"]
  node_images["Image controller<br/>media HTTP API"]
  node_openapi["OpenAPI specification<br/>API document<br/>[api-docs.yaml]"]
end

subgraph group_security["Security"]
  node_security_config["Security configuration<br/>Spring Security"]
  node_token_filter["JWT token filter<br/>request authentication<br/>[TokenFilter.java]"]
  node_refresh_tokens["Refresh token service<br/>token lifecycle"]
end

subgraph group_social["Social domain"]
  node_social_services["Social services<br/>domain service layer<br/>[FriendService.java]"]
  node_entities["JPA social entities<br/>relational model<br/>[User.java]"]
  node_post["Post entity<br/>JPA entity<br/>[Post.java]"]
end

subgraph group_realtime["Real-time chat"]
  node_websocket["WebSocket/STOMP config<br/>real-time transport"]
  node_chat_ingress["Chat handler<br/>message ingress<br/>[ChatHandler.java]"]
  node_chat_service["Chat service<br/>chat domain service<br/>[ChatService.java]"]
  node_message["Message entity<br/>JPA entity<br/>[Message.java]"]
end

subgraph group_data["Data infrastructure"]
  node_postgres[("PostgreSQL 17<br/>system of record<br/>[tables.sql]")]
  node_redis[("Redis 7.2.5<br/>cache<br/>[CacheService.java]")]
  node_search["User search service<br/>[SearchService.java]"]
  node_elasticsearch[("Elasticsearch 7.17.28<br/>search index<br/>[users.json]")]
end

node_compose{{"Docker Compose<br/>container deployment"}}

node_boot -->|"serves"| node_rest
node_boot -->|"serves"| node_openapi
node_rest -->|"secured by"| node_security_config
node_security_config -->|"installs"| node_token_filter
node_rest -->|"login and refresh"| node_refresh_tokens
node_refresh_tokens -->|"persists state"| node_postgres
node_rest -->|"invokes"| node_social_services
node_rest -->|"routes media upload"| node_images
node_social_services -->|"manages"| node_entities
node_social_services -->|"manages"| node_post
node_entities -->|"persists to"| node_postgres
node_post -->|"persists to"| node_postgres
node_social_services -->|"uses cache"| node_redis
node_rest -->|"queries users"| node_search
node_search -->|"queries index"| node_elasticsearch
node_websocket -->|"routes messages"| node_chat_ingress
node_chat_ingress -->|"invokes"| node_chat_service
node_chat_service -->|"creates"| node_message
node_message -->|"persists to"| node_postgres
node_chat_service -->|"rate-limit state"| node_redis
node_compose -->|"runs backend"| node_boot
node_compose -->|"runs"| node_postgres
node_compose -->|"runs"| node_redis
node_compose -->|"runs"| node_elasticsearch

click node_boot "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/SocialMediaApplication.java"
click node_rest "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/AuthController.java"
click node_images "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/ImageController.java"
click node_openapi "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/resources/static/api-docs.yaml"
click node_security_config "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Configs/SecurityConfig.java"
click node_token_filter "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Security/TokenFilter.java"
click node_refresh_tokens "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/RefreshTokenService.java"
click node_social_services "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/FriendService.java"
click node_entities "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Entity/User.java"
click node_post "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Entity/Post.java"
click node_websocket "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Configs/WebSocketConfig.java"
click node_chat_ingress "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/ChatHandler.java"
click node_chat_service "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/ChatService.java"
click node_message "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Entity/Message.java"
click node_postgres "https://github.com/nikolaiunknown/socialmedia/blob/master/init/postgres/tables.sql"
click node_redis "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/CacheService.java"
click node_search "https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/SearchService.java"
click node_elasticsearch "https://github.com/nikolaiunknown/socialmedia/blob/master/init/elasticsearch/users.json"
click node_compose "https://github.com/nikolaiunknown/socialmedia/blob/master/docker-compose.yaml"

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_boot,node_rest,node_images,node_openapi toneBlue
class node_security_config,node_token_filter,node_refresh_tokens toneAmber
class node_social_services,node_entities,node_post toneMint
class node_websocket,node_chat_ingress,node_chat_service,node_message toneRose
class node_postgres,node_redis,node_search,node_elasticsearch toneIndigo
class node_compose toneNeutral
```

## Components

### Spring application

- [SocialMedia application](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/SocialMediaApplication.java): Spring Boot entry point · Serves HTTP APIs, static assets, and OpenAPI. · `src/main/java/com/media/socialmedia/SocialMediaApplication.java`
- [REST controllers](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/AuthController.java): HTTP boundary · Authentication, profiles, posts, admin, search, and media APIs. · `src/main/java/com/media/socialmedia/Controllers/AuthController.java`
- [Image controller](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/ImageController.java): media HTTP API · Accepts image uploads for static serving. · `src/main/java/com/media/socialmedia/Controllers/ImageController.java`
- [OpenAPI specification](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/resources/static/api-docs.yaml): API document · `src/main/resources/static/api-docs.yaml`

### Security

- [Security configuration](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Configs/SecurityConfig.java): Spring Security · Defines authenticated and Admin/user authorization rules. · `src/main/java/com/media/socialmedia/Configs/SecurityConfig.java`
- [JWT token filter](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Security/TokenFilter.java): request authentication · Establishes authenticated request context. · `src/main/java/com/media/socialmedia/Security/TokenFilter.java`
- [Refresh token service](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/RefreshTokenService.java): token lifecycle · Persists refresh-token state; tokens are returned in HTTP-only cookies. · `src/main/java/com/media/socialmedia/Services/RefreshTokenService.java`

### Social domain

- [Social services](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/FriendService.java): domain service layer · Owns profiles, friendships, blacklist, likes, posts, and admin operations. · `src/main/java/com/media/socialmedia/Services/FriendService.java`
- [JPA social entities](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Entity/User.java): relational model · Durable users, posts, chats, messages, and refresh tokens. · `src/main/java/com/media/socialmedia/Entity/User.java`
- [Post entity](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Entity/Post.java): JPA entity · `src/main/java/com/media/socialmedia/Entity/Post.java`

### Real-time chat

- [WebSocket/STOMP config](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Configs/WebSocketConfig.java): real-time transport · Exposes the chat messaging transport. · `src/main/java/com/media/socialmedia/Configs/WebSocketConfig.java`
- [Chat handler](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Controllers/ChatHandler.java): message ingress · Handles incoming real-time chat messages. · `src/main/java/com/media/socialmedia/Controllers/ChatHandler.java`
- [Chat service](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/ChatService.java): chat domain service · Validates access and blacklist rules, rate-limits users, and persists messages. · `src/main/java/com/media/socialmedia/Services/ChatService.java`
- [Message entity](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Entity/Message.java): JPA entity · `src/main/java/com/media/socialmedia/Entity/Message.java`

### Data infrastructure

- [PostgreSQL 17](https://github.com/nikolaiunknown/socialmedia/blob/master/init/postgres/tables.sql): system of record · Relational persistence initialized with schema SQL. · `init/postgres/tables.sql`
- [Redis 7.2.5](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/CacheService.java): cache · Used by the dedicated cache layer. · `src/main/java/com/media/socialmedia/Services/CacheService.java`
- [User search service](https://github.com/nikolaiunknown/socialmedia/blob/master/src/main/java/com/media/socialmedia/Services/SearchService.java): search service · Performs RU/EN full-text user search. · `src/main/java/com/media/socialmedia/Services/SearchService.java`
- [Elasticsearch 7.17.28](https://github.com/nikolaiunknown/socialmedia/blob/master/init/elasticsearch/users.json): search index · Stores UserSearchDocument records. · `init/elasticsearch/users.json`

### Other components

- [Docker Compose](https://github.com/nikolaiunknown/socialmedia/blob/master/docker-compose.yaml): container deployment · Runs backend, PostgreSQL, Redis, and Elasticsearch. · `docker-compose.yaml`

## Connections

- SocialMedia application → REST controllers: serves
- SocialMedia application → OpenAPI specification: serves
- REST controllers → Security configuration: secured by
- Security configuration → JWT token filter: installs
- REST controllers → Refresh token service: login and refresh
- Refresh token service → PostgreSQL 17: persists state
- REST controllers → Social services: invokes
- REST controllers → Image controller: routes media upload
- Social services → JPA social entities: manages
- Social services → Post entity: manages
- JPA social entities → PostgreSQL 17: persists to
- Post entity → PostgreSQL 17: persists to
- Social services → Redis 7.2.5: uses cache
- REST controllers → User search service: queries users
- User search service → Elasticsearch 7.17.28: queries index
- WebSocket/STOMP config → Chat handler: routes messages
- Chat handler → Chat service: invokes
- Chat service → Message entity: creates
- Message entity → PostgreSQL 17: persists to
- Chat service → Redis 7.2.5: rate-limit state
- Docker Compose → SocialMedia application: runs backend
- Docker Compose → PostgreSQL 17: runs
- Docker Compose → Redis 7.2.5: runs
- Docker Compose → Elasticsearch 7.17.28: runs