# weebonweed/sentinelgrid architecture

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

- Interactive diagram: https://gitdiagram.com/weebonweed/sentinelgrid
- Repository: https://github.com/weebonweed/sentinelgrid

## Overview

SentinelGrid is a Spring Boot social interaction engine for posts, comments, likes, bot/human authorship, and notification dispatch. The principal request flow is HTTP ingestion through controllers into application services, which apply domain rules and coordinate durable PostgreSQL writes with transient Redis state before mapping responses. Redis also provides bot-cap reservations, cooldowns, virality scores, and notification queues; a scheduled sweeper processes queued notifications. Relationships are limited to calls shown in indexed source references or capabilities and infrastructure explicitly described in the README; some internal notification wiring is therefore documented rather than source-verified.

Main entry points: [`src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java) (Comment service), [`src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java`](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java) (Like service), [`src/main/java/com/sentinelgrid/repository`](https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/repository) (JPA repositories), [`src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java`](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java) (Post service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_posts_api["Post endpoints"]
  node_comments_api["Comment endpoints"]
  node_likes_api["Like endpoints"]
  node_api_dtos["Requests and responses"]
end

subgraph group_app["Application Services"]
  node_post_service["Post service"]
  node_comment_service["Comment service"]
  node_like_service["Like service"]
  node_notification_service["Notification service"]
  node_author_resolver["Author validation"]
  node_entity_mapper["Response mapping<br/>[EntityMapper.java]"]
  node_domain["Posts, comments, likes, authors"]
end

subgraph group_state["Persistence and Coordination"]
  node_repositories["JPA repositories"]
  node_postgres[("PostgreSQL")]
  node_bot_cap["Bot cap reservation"]
  node_cooldown["Author cooldown"]
  node_virality["Virality scoring"]
  node_notifications_redis["Notification queues"]
  node_redis_keys["Redis key builder"]
  node_redis[("Redis")]
end

subgraph group_runtime["Runtime Infrastructure"]
  node_sweeper["Notification sweeper"]
  node_config_security["Configuration and security"]
  node_error_handler["Error translation"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_posts_api
node_client -->|"sends requests"| node_comments_api
node_client -->|"sends requests"| node_likes_api
node_posts_api -->|"delegates via contract"| node_post_service
node_comments_api -->|"delegates via contract"| node_comment_service
node_likes_api -->|"delegates via contract"| node_like_service
node_posts_api -->|"accepts and returns"| node_api_dtos
node_comments_api -->|"accepts and returns"| node_api_dtos
node_likes_api -->|"accepts and returns"| node_api_dtos
node_post_service -->|"reads and writes"| node_repositories
node_comment_service -->|"reads and writes"| node_repositories
node_like_service -->|"reads and writes"| node_repositories
node_post_service -->|"validates author"| node_author_resolver
node_comment_service -->|"validates author"| node_author_resolver
node_post_service -->|"maps response"| node_entity_mapper
node_comment_service -->|"maps response"| node_entity_mapper
node_like_service -->|"maps response"| node_entity_mapper
node_author_resolver -->|"checks author existence"| node_repositories
node_comment_service -->|"reserves bot capacity"| node_bot_cap
node_comment_service -->|"checks cooldown"| node_cooldown
node_comment_service -->|"adds reply score"| node_virality
node_like_service -->|"adds like score"| node_virality
node_like_service -->|"requests notification"| node_notification_service
node_notification_service -->|"dispatches notifications"| node_notifications_redis
node_sweeper -->|"processes pending"| node_notification_service
node_repositories -->|"persists durable state"| node_postgres
node_bot_cap -->|"reserves and releases"| node_redis
node_cooldown -->|"acquires TTL lock"| node_redis
node_virality -->|"increments score"| node_redis
node_notifications_redis -->|"queues and drains"| node_redis
node_bot_cap -->|"builds keys"| node_redis_keys
node_cooldown -->|"builds keys"| node_redis_keys
node_virality -->|"builds keys"| node_redis_keys
node_notifications_redis -->|"builds keys"| node_redis_keys
node_client -.->|"receives error response"| node_error_handler

click node_posts_api "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/controller/PostController.java"
click node_comments_api "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/controller/CommentController.java"
click node_likes_api "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/controller/LikeController.java"
click node_api_dtos "https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/dto"
click node_post_service "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java"
click node_comment_service "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java"
click node_like_service "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java"
click node_notification_service "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/NotificationServiceImpl.java"
click node_author_resolver "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/util/AuthorResolver.java"
click node_entity_mapper "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/mapper/EntityMapper.java"
click node_domain "https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/entity"
click node_repositories "https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/repository"
click node_bot_cap "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/BotCapRedisService.java"
click node_cooldown "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/CooldownRedisService.java"
click node_virality "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/ViralityRedisService.java"
click node_notifications_redis "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/NotificationRedisService.java"
click node_redis_keys "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/keys/RedisKeyBuilder.java"
click node_sweeper "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/scheduler/NotificationSweeperScheduler.java"
click node_config_security "https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/config"
click node_error_handler "https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/handler/GlobalExceptionHandler.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_posts_api,node_comments_api,node_likes_api,node_api_dtos,node_client toneBlue
class node_post_service,node_comment_service,node_like_service,node_notification_service,node_author_resolver,node_entity_mapper,node_domain toneAmber
class node_repositories,node_postgres,node_bot_cap,node_cooldown,node_virality,node_notifications_redis,node_redis_keys,node_redis toneMint
class node_sweeper,node_config_security,node_error_handler toneRose
```

## Components

### HTTP API

- [Post endpoints](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/controller/PostController.java): `src/main/java/com/sentinelgrid/controller/PostController.java`
- [Comment endpoints](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/controller/CommentController.java): `src/main/java/com/sentinelgrid/controller/CommentController.java`
- [Like endpoints](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/controller/LikeController.java): `src/main/java/com/sentinelgrid/controller/LikeController.java`
- [Requests and responses](https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/dto): `src/main/java/com/sentinelgrid/dto`

### Application Services

- [Post service](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java): `src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java`
- [Comment service](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java): `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`
- [Like service](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java): `src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java`
- [Notification service](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/service/impl/NotificationServiceImpl.java): `src/main/java/com/sentinelgrid/service/impl/NotificationServiceImpl.java`
- [Author validation](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/util/AuthorResolver.java): `src/main/java/com/sentinelgrid/util/AuthorResolver.java`
- [Response mapping](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/mapper/EntityMapper.java): `src/main/java/com/sentinelgrid/mapper/EntityMapper.java`
- [Posts, comments, likes, authors](https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/entity): `src/main/java/com/sentinelgrid/entity`

### Persistence and Coordination

- [JPA repositories](https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/repository): `src/main/java/com/sentinelgrid/repository`
- **PostgreSQL**
- [Bot cap reservation](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/BotCapRedisService.java): `src/main/java/com/sentinelgrid/redis/service/BotCapRedisService.java`
- [Author cooldown](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/CooldownRedisService.java): `src/main/java/com/sentinelgrid/redis/service/CooldownRedisService.java`
- [Virality scoring](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/ViralityRedisService.java): `src/main/java/com/sentinelgrid/redis/service/ViralityRedisService.java`
- [Notification queues](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/service/NotificationRedisService.java): `src/main/java/com/sentinelgrid/redis/service/NotificationRedisService.java`
- [Redis key builder](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/redis/keys/RedisKeyBuilder.java): `src/main/java/com/sentinelgrid/redis/keys/RedisKeyBuilder.java`
- **Redis**

### Runtime Infrastructure

- [Notification sweeper](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/scheduler/NotificationSweeperScheduler.java): `src/main/java/com/sentinelgrid/scheduler/NotificationSweeperScheduler.java`
- [Configuration and security](https://github.com/weebonweed/sentinelgrid/tree/main/src/main/java/com/sentinelgrid/config): `src/main/java/com/sentinelgrid/config`
- [Error translation](https://github.com/weebonweed/sentinelgrid/blob/main/src/main/java/com/sentinelgrid/handler/GlobalExceptionHandler.java): `src/main/java/com/sentinelgrid/handler/GlobalExceptionHandler.java`

### Other components

- **API client**

## Connections

- API client → Post endpoints: sends requests (evidence: `src/main/java/com/sentinelgrid/controller/PostController.java`)
- API client → Comment endpoints: sends requests (evidence: `src/main/java/com/sentinelgrid/controller/CommentController.java`)
- API client → Like endpoints: sends requests (evidence: `src/main/java/com/sentinelgrid/controller/LikeController.java`)
- Post endpoints → Post service: delegates via contract (evidence: `src/main/java/com/sentinelgrid/controller/PostController.java`)
- Comment endpoints → Comment service: delegates via contract (evidence: `src/main/java/com/sentinelgrid/controller/CommentController.java`)
- Like endpoints → Like service: delegates via contract (evidence: `src/main/java/com/sentinelgrid/controller/LikeController.java`)
- Post endpoints → Requests and responses: accepts and returns (evidence: `src/main/java/com/sentinelgrid/controller/PostController.java`)
- Comment endpoints → Requests and responses: accepts and returns (evidence: `src/main/java/com/sentinelgrid/controller/CommentController.java`)
- Like endpoints → Requests and responses: accepts and returns (evidence: `src/main/java/com/sentinelgrid/controller/LikeController.java`)
- Post service → JPA repositories: reads and writes (evidence: `src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java`)
- Comment service → JPA repositories: reads and writes (evidence: `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`)
- Like service → JPA repositories: reads and writes (evidence: `src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java`)
- Post service → Author validation: validates author (evidence: `src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java`)
- Comment service → Author validation: validates author (evidence: `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`)
- Post service → Response mapping: maps response (evidence: `src/main/java/com/sentinelgrid/service/impl/PostServiceImpl.java`)
- Comment service → Response mapping: maps response (evidence: `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`)
- Like service → Response mapping: maps response (evidence: `src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java`)
- Author validation → JPA repositories: checks author existence (evidence: `src/main/java/com/sentinelgrid/util/AuthorResolver.java`)
- Comment service → Bot cap reservation: reserves bot capacity (evidence: `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`)
- Comment service → Author cooldown: checks cooldown (evidence: `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`)
- Comment service → Virality scoring: adds reply score (evidence: `src/main/java/com/sentinelgrid/service/impl/CommentServiceImpl.java`)
- Like service → Virality scoring: adds like score (evidence: `src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java`)
- Like service → Notification service: requests notification (evidence: `src/main/java/com/sentinelgrid/service/impl/LikeServiceImpl.java`)
- Notification service → Notification queues: dispatches notifications (evidence: `src/main/java/com/sentinelgrid/service/impl/NotificationServiceImpl.java`)
- Notification sweeper → Notification service: processes pending
- JPA repositories → PostgreSQL: persists durable state
- Bot cap reservation → Redis: reserves and releases
- Author cooldown → Redis: acquires TTL lock
- Virality scoring → Redis: increments score
- Notification queues → Redis: queues and drains
- Bot cap reservation → Redis key builder: builds keys (evidence: `src/main/java/com/sentinelgrid/redis/service/BotCapRedisService.java`)
- Author cooldown → Redis key builder: builds keys (evidence: `src/main/java/com/sentinelgrid/redis/service/CooldownRedisService.java`)
- Virality scoring → Redis key builder: builds keys (evidence: `src/main/java/com/sentinelgrid/redis/service/ViralityRedisService.java`)
- Notification queues → Redis key builder: builds keys (evidence: `src/main/java/com/sentinelgrid/redis/service/NotificationRedisService.java`)
- API client → Error translation: receives error response (evidence: `src/main/java/com/sentinelgrid/handler/GlobalExceptionHandler.java`)