# patmesh/social-feed-system architecture

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

- Interactive diagram: https://gitdiagram.com/patmesh/social-feed-system
- Repository: https://github.com/patmesh/social-feed-system

## Overview

This repository implements a social application as several Spring services: authentication, posts and feeds, a user-follow graph, persisted notifications, and WebSocket delivery. A typical user creates a post through the post API; the post service saves it and publishes an event, while graph-side fanout gathers followers and publishes notification events. Users can also query their notifications. Auth signup/login and follow notifications are separate flows. The excerpts show service-layer calls and some persistence/event publishing; cross-service routing and several event consumers are not shown, so those links are omitted or marked unverified.

Main entry points: [`api-gateway-service/src/main/java/com/dev/apigatewayservice/config/GatewayConfig.java`](https://github.com/patmesh/social-feed-system/blob/main/api-gateway-service/src/main/java/com/dev/apigatewayservice/config/GatewayConfig.java) (API Gateway), [`user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java`](https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java) (Auth Service), [`user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java`](https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java) (Post Service), [`graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java`](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java) (Follower Fanout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["API Edge"]
  node_gateway["API Gateway<br/>[GatewayConfig.java]"]
end

subgraph group_identity["Identity"]
  node_auth_api["Auth API"]
  node_auth_service["Auth Service<br/>[AuthService.java]"]
  node_auth_store[("Account Storage")]
  node_refresh["Refresh Tokens"]
  node_auth_events["User Event Producer"]
end

subgraph group_social["Posts and Graph"]
  node_post_api["Post API"]
  node_post_service["Post Service<br/>[PostService.java]"]
  node_post_store[("Post Storage")]
  node_graph_client["Graph Client<br/>[GraphClient.java]"]
  node_post_events["Post Event Producer"]
  node_graph_api["Graph API"]
  node_user_service["Graph User Service<br/>[UserService.java]"]
  node_graph_repository["Graph Repository"]
  node_query_engine["Gremlin Query Engine"]
  node_graph_store[("Graph Database<br/>[GremlinConfig.java]")]
  node_post_consumer["Post Event Consumer"]
  node_fanout["Follower Fanout"]
  node_graph_events["Notification Event Producer"]
end

subgraph group_notify["Notifications"]
  node_notification_consumer["Notification Consumer"]
  node_notification_processor["Notification Processor"]
  node_notification_store[("Notification Storage")]
  node_notification_api["Notification API"]
  node_notification_query["Notification Query"]
end

subgraph group_realtime["Realtime Delivery"]
  node_ws_handler["WebSocket Handler"]
  node_presence["Presence Service"]
  node_redis[("Redis Presence Store<br/>[RedisConfig.java]")]
end

node_client(("Application Client"))
node_kafka["Kafka"]

node_client -.->|"sends requests"| node_gateway
node_gateway -.->|"routes requests"| node_auth_api
node_gateway -.->|"routes requests"| node_post_api
node_gateway -.->|"routes requests"| node_notification_api
node_auth_api -->|"calls"| node_auth_service
node_auth_service -->|"reads and writes"| node_auth_store
node_auth_service -->|"manages tokens"| node_refresh
node_auth_service -->|"publishes signup"| node_auth_events
node_auth_events -.->|"publishes events"| node_kafka
node_post_api -->|"calls"| node_post_service
node_post_service -->|"reads and writes"| node_post_store
node_post_service -->|"publishes post event"| node_post_events
node_post_service -->|"fetches followings"| node_graph_client
node_post_events -.->|"publishes events"| node_kafka
node_graph_api -.->|"dispatches graph actions"| node_user_service
node_user_service -->|"reads and mutates graph"| node_graph_repository
node_graph_repository -.->|"executes graph queries"| node_query_engine
node_query_engine -.->|"runs Gremlin"| node_graph_store
node_post_consumer -.->|"dispatches post events"| node_fanout
node_fanout -->|"loads followers"| node_user_service
node_fanout -->|"publishes batches"| node_graph_events
node_graph_events -.->|"publishes events"| node_kafka
node_kafka -.->|"delivers events"| node_notification_consumer
node_notification_consumer -.->|"processes events"| node_notification_processor
node_notification_processor -.->|"persists notifications"| node_notification_store
node_notification_api -->|"calls"| node_notification_query
node_notification_query -->|"queries notifications"| node_notification_store
node_presence -->|"stores presence"| node_redis
node_notification_consumer -.->|"delivers live updates"| node_ws_handler

click node_gateway "https://github.com/patmesh/social-feed-system/blob/main/api-gateway-service/src/main/java/com/dev/apigatewayservice/config/GatewayConfig.java"
click node_auth_api "https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/controller/AuthController.java"
click node_auth_service "https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java"
click node_auth_store "https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/repository/UserRepository.java"
click node_refresh "https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/service/RefreshTokenService.java"
click node_auth_events "https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/kafka/producer/KafkaEventProducer.java"
click node_post_api "https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/controller/PostController.java"
click node_post_service "https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java"
click node_post_store "https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/repository/PostRepository.java"
click node_graph_client "https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/client/GraphClient.java"
click node_post_events "https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/kafka/producer/KafkaEventProducer.java"
click node_graph_api "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/controller/GraphController.java"
click node_user_service "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/service/UserService.java"
click node_graph_repository "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/core/GraphRepository.java"
click node_query_engine "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/core/QueryExecutionEngineImpl.java"
click node_graph_store "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/config/GremlinConfig.java"
click node_post_consumer "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/kafka/consumer/PostEventConsumer.java"
click node_fanout "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java"
click node_graph_events "https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/kafka/producer/KafkaEventProducer.java"
click node_notification_consumer "https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/kafka/consumer/NotificationConsumer.java"
click node_notification_processor "https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/service/NotificationProcessor.java"
click node_notification_store "https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/repository/NotificationRepository.java"
click node_notification_api "https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/controller/NotificationController.java"
click node_notification_query "https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/service/NotificationQueryService.java"
click node_ws_handler "https://github.com/patmesh/social-feed-system/blob/main/ws-notification-service/src/main/java/com/dev/ws_notification_service/handler/NotificationWebSocketHandler.java"
click node_presence "https://github.com/patmesh/social-feed-system/blob/main/ws-notification-service/src/main/java/com/dev/ws_notification_service/service/PresenceService.java"
click node_redis "https://github.com/patmesh/social-feed-system/blob/main/ws-notification-service/src/main/java/com/dev/ws_notification_service/config/RedisConfig.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_gateway,node_client toneBlue
class node_auth_api,node_auth_service,node_auth_store,node_refresh,node_auth_events toneAmber
class node_post_api,node_post_service,node_post_store,node_graph_client,node_post_events,node_graph_api,node_user_service,node_graph_repository,node_query_engine,node_graph_store,node_post_consumer,node_fanout,node_graph_events toneMint
class node_notification_consumer,node_notification_processor,node_notification_store,node_notification_api,node_notification_query toneRose
class node_ws_handler,node_presence,node_redis,node_kafka toneIndigo
```

## Components

### API Edge

- [API Gateway](https://github.com/patmesh/social-feed-system/blob/main/api-gateway-service/src/main/java/com/dev/apigatewayservice/config/GatewayConfig.java): `api-gateway-service/src/main/java/com/dev/apigatewayservice/config/GatewayConfig.java`

### Identity

- [Auth API](https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/controller/AuthController.java): `user-auth-service/src/main/java/com/dev/userauthservice/controller/AuthController.java`
- [Auth Service](https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java): `user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java`
- [Account Storage](https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/repository/UserRepository.java): `user-auth-service/src/main/java/com/dev/userauthservice/repository/UserRepository.java`
- [Refresh Tokens](https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/service/RefreshTokenService.java): `user-auth-service/src/main/java/com/dev/userauthservice/service/RefreshTokenService.java`
- [User Event Producer](https://github.com/patmesh/social-feed-system/blob/main/user-auth-service/src/main/java/com/dev/userauthservice/kafka/producer/KafkaEventProducer.java): `user-auth-service/src/main/java/com/dev/userauthservice/kafka/producer/KafkaEventProducer.java`

### Posts and Graph

- [Post API](https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/controller/PostController.java): `user-post-service/src/main/java/com/dev/user_post_service/controller/PostController.java`
- [Post Service](https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java): `user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java`
- [Post Storage](https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/repository/PostRepository.java): `user-post-service/src/main/java/com/dev/user_post_service/repository/PostRepository.java`
- [Graph Client](https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/client/GraphClient.java): `user-post-service/src/main/java/com/dev/user_post_service/client/GraphClient.java`
- [Post Event Producer](https://github.com/patmesh/social-feed-system/blob/main/user-post-service/src/main/java/com/dev/user_post_service/kafka/producer/KafkaEventProducer.java): `user-post-service/src/main/java/com/dev/user_post_service/kafka/producer/KafkaEventProducer.java`
- [Graph API](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/controller/GraphController.java): `graph-service/src/main/java/com/dev/graphservice/controller/GraphController.java`
- [Graph User Service](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/service/UserService.java): `graph-service/src/main/java/com/dev/graphservice/service/UserService.java`
- [Graph Repository](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/core/GraphRepository.java): `graph-service/src/main/java/com/dev/graphservice/core/GraphRepository.java`
- [Gremlin Query Engine](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/core/QueryExecutionEngineImpl.java): `graph-service/src/main/java/com/dev/graphservice/core/QueryExecutionEngineImpl.java`
- [Graph Database](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/config/GremlinConfig.java): `graph-service/src/main/java/com/dev/graphservice/config/GremlinConfig.java`
- [Post Event Consumer](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/kafka/consumer/PostEventConsumer.java): `graph-service/src/main/java/com/dev/graphservice/kafka/consumer/PostEventConsumer.java`
- [Follower Fanout](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java): `graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java`
- [Notification Event Producer](https://github.com/patmesh/social-feed-system/blob/main/graph-service/src/main/java/com/dev/graphservice/kafka/producer/KafkaEventProducer.java): `graph-service/src/main/java/com/dev/graphservice/kafka/producer/KafkaEventProducer.java`

### Notifications

- [Notification Consumer](https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/kafka/consumer/NotificationConsumer.java): `notification-service/src/main/java/com/dev/notification_service/kafka/consumer/NotificationConsumer.java`
- [Notification Processor](https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/service/NotificationProcessor.java): `notification-service/src/main/java/com/dev/notification_service/service/NotificationProcessor.java`
- [Notification Storage](https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/repository/NotificationRepository.java): `notification-service/src/main/java/com/dev/notification_service/repository/NotificationRepository.java`
- [Notification API](https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/controller/NotificationController.java): `notification-service/src/main/java/com/dev/notification_service/controller/NotificationController.java`
- [Notification Query](https://github.com/patmesh/social-feed-system/blob/main/notification-service/src/main/java/com/dev/notification_service/service/NotificationQueryService.java): `notification-service/src/main/java/com/dev/notification_service/service/NotificationQueryService.java`

### Realtime Delivery

- [WebSocket Handler](https://github.com/patmesh/social-feed-system/blob/main/ws-notification-service/src/main/java/com/dev/ws_notification_service/handler/NotificationWebSocketHandler.java): `ws-notification-service/src/main/java/com/dev/ws_notification_service/handler/NotificationWebSocketHandler.java`
- [Presence Service](https://github.com/patmesh/social-feed-system/blob/main/ws-notification-service/src/main/java/com/dev/ws_notification_service/service/PresenceService.java): `ws-notification-service/src/main/java/com/dev/ws_notification_service/service/PresenceService.java`
- [Redis Presence Store](https://github.com/patmesh/social-feed-system/blob/main/ws-notification-service/src/main/java/com/dev/ws_notification_service/config/RedisConfig.java): `ws-notification-service/src/main/java/com/dev/ws_notification_service/config/RedisConfig.java`

### Other components

- **Application Client**
- **Kafka**

## Connections

- Application Client → API Gateway: sends requests
- API Gateway → Auth API: routes requests
- API Gateway → Post API: routes requests
- API Gateway → Notification API: routes requests
- Auth API → Auth Service: calls (evidence: `user-auth-service/src/main/java/com/dev/userauthservice/controller/AuthController.java`)
- Auth Service → Account Storage: reads and writes (evidence: `user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java`)
- Auth Service → Refresh Tokens: manages tokens (evidence: `user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java`)
- Auth Service → User Event Producer: publishes signup (evidence: `user-auth-service/src/main/java/com/dev/userauthservice/service/AuthService.java`)
- User Event Producer → Kafka: publishes events
- Post API → Post Service: calls (evidence: `user-post-service/src/main/java/com/dev/user_post_service/controller/PostController.java`)
- Post Service → Post Storage: reads and writes (evidence: `user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java`)
- Post Service → Post Event Producer: publishes post event (evidence: `user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java`)
- Post Service → Graph Client: fetches followings (evidence: `user-post-service/src/main/java/com/dev/user_post_service/service/PostService.java`)
- Post Event Producer → Kafka: publishes events
- Graph API → Graph User Service: dispatches graph actions (evidence: `graph-service/src/main/java/com/dev/graphservice/controller/GraphController.java`)
- Graph User Service → Graph Repository: reads and mutates graph (evidence: `graph-service/src/main/java/com/dev/graphservice/service/UserService.java`)
- Graph Repository → Gremlin Query Engine: executes graph queries
- Gremlin Query Engine → Graph Database: runs Gremlin
- Post Event Consumer → Follower Fanout: dispatches post events
- Follower Fanout → Graph User Service: loads followers (evidence: `graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java`)
- Follower Fanout → Notification Event Producer: publishes batches (evidence: `graph-service/src/main/java/com/dev/graphservice/service/PostFanoutService.java`)
- Notification Event Producer → Kafka: publishes events
- Kafka → Notification Consumer: delivers events
- Notification Consumer → Notification Processor: processes events
- Notification Processor → Notification Storage: persists notifications
- Notification API → Notification Query: calls (evidence: `notification-service/src/main/java/com/dev/notification_service/controller/NotificationController.java`)
- Notification Query → Notification Storage: queries notifications (evidence: `notification-service/src/main/java/com/dev/notification_service/service/NotificationQueryService.java`)
- Presence Service → Redis Presence Store: stores presence (evidence: `ws-notification-service/src/main/java/com/dev/ws_notification_service/service/PresenceService.java`)
- Notification Consumer → WebSocket Handler: delivers live updates
