# nagisa77/openisle architecture

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

- Interactive diagram: https://gitdiagram.com/nagisa77/openisle
- Repository: https://github.com/nagisa77/openisle

## Overview

1. **Overall shape**
   OpenIsle is a multi-process community platform, not a single app. The main user-facing system is a **Nuxt 3 frontend** talking to a **Spring Boot backend API**, with a separate **WebSocket service** for live notifications/messages, plus supporting bots, docs, and deployment infrastructure.

2. **Core backend boundary**
   `backend/` is the primary business system. It is organized in a classic Spring layering: **controllers → services → repositories → models/DTOs**. Controllers expose REST APIs for auth, users, posts, comments, tags, categories, notifications, search, points, messages, uploads, and admin operations.

3. **Domain center**
   The backend domain is centered on a community/forum model: **users, posts, comments, tags, categories, reactions, subscriptions, drafts, notifications, messages, points, medals, and activity logs**. There is also support for post variants like polls, lottery posts, donation flows, and change logs, which suggests the platform tracks rich post lifecycle events rather than just static content.

4. **Persistence and schema management**
   The backend persists to a relational database, with schema bootstrapping and versioned migrations under `backend/src/main/resources/db`. Flyway-style migrations and seed/init SQL indicate the app expects a structured, evolving schema. Repositories are explicit Spring data access boundaries for each aggregate.

5. **Authentication and identity**
   Authentication is split between **JWT-based local auth** and multiple OAuth providers: Google, GitHub, Discord, Twitter, and Telegram are represented in the codebase. The frontend contains dedicated callback pages for these providers, while the backend owns token issuance, password flows, and registration-mode rules.

6. **Search subsystem**
   Search is a distinct subsystem in `backend/src/main/java/com/openisle/search`. It uses **OpenSearch** when enabled, with a `NoopSearchIndexer` fallback. The design is event-driven: domain changes publish index/delete events, a search listener processes them, and reindex/initializer components manage search bootstrapping. This is a clear boundary between transactional writes and search indexing.

7. **Real-time notifications and messaging**
   Real-time delivery is handled outside the main backend by `websocket_service/`. It connects to **RabbitMQ** and uses JWT auth on WebSocket connections. The backend publishes notification payloads to RabbitMQ via a producer/service layer, and the WebSocket service consumes them to push live updates to clients. This separates synchronous API handling from live fan-out.

8. **Asynchronous and scheduled processing**
   The backend has async and scheduler config, plus jobs like `UserVisitScheduler`. This indicates background processing for analytics/cleanup/recalculation tasks. The architecture mixes immediate request/response flows with deferred processing for user activity, search indexing, and notification delivery.

9. **Frontend boundary**
   `frontend_nuxt/` is the interactive client. It is a Nuxt/Vue application with page-based routing for posts, users, login/signup, settings, message box, points, and callbacks. The frontend also hosts many reusable components for editor, comments, notifications, reactions, polls, medals, and real-time UI elements, making it the presentation and interaction layer over the backend APIs.

10. **Front-end live features**
    The frontend has composables and plugins for **websocket use, unread counts, toast notifications, auth fetch, theme handling, and markdown/editor utilities**. This shows the UI consumes both REST and live channels: REST for state, WebSocket for notifications/messages, and browser APIs for push and client-side enhancements.

11. **External integrations**
    The repo integrates with several external services that materially affect architecture: **Tencent COS** for image upload, **OpenAI** for Markdown formatting assistance, **browser web push** for notifications, and social login providers. These integrations are not thin utilities; they shape upload, auth, and notification flows across the app.

12. **Bots and community automation**
    `bots/` contains TypeScript bot instances such as coffee, daily news, open source reply, and reply bots. Combined with GitHub workflows for bot-related automation, this indicates an auxiliary automation layer that interacts with community content and external channels, separate from the main product runtime.

13. **Docs and documentation generation**
    `docs/` is a separate **Next.js** documentation site with OpenAPI-driven content generation. It is a build-time/read-only consumer of the backend API definition and repository documentation, not part of the live application runtime.

14. **Deployment and runtime infrastructure**
    `docker/`, `nginx/`, and `deploy/` define the deployment boundary. The stack is containerized around the backend, frontend, websocket service, MySQL, Redis, RabbitMQ, and OpenSearch, with Nginx acting as the edge/router. GitHub Actions handles deploys and bot workflows, so the architecture is designed for multi-service orchestration rather than a single deployable artifact.

15. **Testing and confidence model**
    The backend has unit, controller, and integration tests covering critical flows like auth, search, posts, comments, reactions, notifications, and publish modes. This suggests the main architectural seams are expected to be validated through API-level and integration-level tests, especially around domain interactions and cross-service behavior.

Main entry points: [`backend/src/main/java/com/openisle/controller`](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/controller) (Controllers), [`backend/src/main/java/com/openisle/service`](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/service) (Services), [`websocket_service/src/main/java/com/openisle/websocket/WebsocketServiceApplication.java`](https://github.com/nagisa77/openisle/blob/main/websocket_service/src/main/java/com/openisle/websocket/WebsocketServiceApplication.java) (WebSocket svc), [`nginx`](https://github.com/nagisa77/openisle/tree/main/nginx) (Nginx edge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["API app<br/>spring boot api"]
  node_backend_web["Controllers<br/>rest layer"]
  node_backend_domain["Services<br/>business logic"]
  node_backend_data["Data model<br/>entities/dao"]
  node_backend_search["Search"]
  node_backend_realtime_out["Notify producer<br/>rabbitmq publisher"]
  node_backend_jobs["Schedulers<br/>async/background"]
  node_backend_db[("DB schema<br/>flyway/sql")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Nuxt app<br/>nuxt-vue client"]
  node_frontend_live["Live UI<br/>websocket/ui composables"]
  node_frontend_auth["Auth pages<br/>oauth callbacks"]
  node_frontend_content["Content UI<br/>editor/post views"]
end

subgraph group_realtime["Realtime"]
  node_realtime_app["WebSocket svc<br/>spring websocket"]
  node_realtime_bus["RabbitMQ<br/>message bus"]
end

subgraph group_ops["Ops"]
  node_ops_nginx["Nginx edge<br/>reverse proxy"]
  node_ops_docker["Compose stack<br/>containers"]
  node_ops_docs["Docs site<br/>nextjs docs"]
  node_ops_bots["Bots<br/>automation scripts"]
end

node_frontend_app -->|"REST APIs"| node_backend_web
node_frontend_live -->|"socket client"| node_realtime_app
node_frontend_auth -->|"login flows"| node_backend_web
node_frontend_content -->|"content actions"| node_backend_web
node_backend_web -->|"delegates"| node_backend_domain
node_backend_domain -->|"reads/writes"| node_backend_data
node_backend_domain -->|"index events"| node_backend_search
node_backend_search -.->|"bootstrap schema"| node_backend_db
node_backend_domain -->|"publish live"| node_backend_realtime_out
node_backend_domain -.->|"async work"| node_backend_jobs
node_backend_data -->|"schema"| node_backend_db
node_backend_web -.->|"admin/setup"| node_backend_db
node_backend_realtime_out -->|"enqueue"| node_realtime_bus
node_realtime_app -->|"consume"| node_realtime_bus
node_realtime_app -->|"push updates"| node_frontend_live
node_ops_nginx -->|"routes"| node_frontend_app
node_ops_nginx -->|"routes"| node_backend_app
node_ops_nginx -->|"routes"| node_realtime_app
node_ops_docker -->|"deploys"| node_backend_app
node_ops_docker -->|"deploys"| node_frontend_app
node_ops_docker -->|"deploys"| node_realtime_app
node_ops_docs -.->|"reads OpenAPI"| node_backend_web
node_ops_bots -.->|"community automation"| node_backend_web

click node_frontend_app "https://github.com/nagisa77/openisle/tree/main/frontend_nuxt"
click node_frontend_live "https://github.com/nagisa77/openisle/tree/main/frontend_nuxt/composables"
click node_frontend_auth "https://github.com/nagisa77/openisle/tree/main/frontend_nuxt/pages"
click node_frontend_content "https://github.com/nagisa77/openisle/tree/main/frontend_nuxt/components"
click node_backend_app "https://github.com/nagisa77/openisle/blob/main/backend/src/main/java/com/openisle/OpenIsleApplication.java"
click node_backend_web "https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/controller"
click node_backend_domain "https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/service"
click node_backend_data "https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/model"
click node_backend_search "https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/search"
click node_backend_realtime_out "https://github.com/nagisa77/openisle/blob/main/backend/src/main/java/com/openisle/service/NotificationProducer.java"
click node_backend_jobs "https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/scheduler"
click node_backend_db "https://github.com/nagisa77/openisle/tree/main/backend/src/main/resources/db"
click node_realtime_app "https://github.com/nagisa77/openisle/blob/main/websocket_service/src/main/java/com/openisle/websocket/WebsocketServiceApplication.java"
click node_realtime_bus "https://github.com/nagisa77/openisle/tree/main/docker/rabbitmq"
click node_ops_nginx "https://github.com/nagisa77/openisle/tree/main/nginx"
click node_ops_docker "https://github.com/nagisa77/openisle/blob/main/docker/docker-compose.yaml"
click node_ops_docs "https://github.com/nagisa77/openisle/tree/main/docs"
click node_ops_bots "https://github.com/nagisa77/openisle/tree/main/bots"

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_backend_app,node_backend_web,node_backend_domain,node_backend_data,node_backend_search,node_backend_realtime_out,node_backend_jobs,node_backend_db toneBlue
class node_frontend_app,node_frontend_live,node_frontend_auth,node_frontend_content toneAmber
class node_realtime_app,node_realtime_bus toneMint
class node_ops_nginx,node_ops_docker,node_ops_docs,node_ops_bots toneRose
```

## Components

### Backend

Spring Boot API, domain services, persistence, and search.

- [API app](https://github.com/nagisa77/openisle/blob/main/backend/src/main/java/com/openisle/OpenIsleApplication.java): spring boot api · Main backend application and REST boundary for the community platform. · `backend/src/main/java/com/openisle/OpenIsleApplication.java`
- [Controllers](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/controller): rest layer · HTTP entrypoints for auth, posts, comments, users, notifications, search, uploads, admin, and stats. · `backend/src/main/java/com/openisle/controller`
- [Services](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/service): business logic · Core orchestration for auth, posts, messaging, notifications, points, medals, search, and uploads. · `backend/src/main/java/com/openisle/service`
- [Data model](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/model): entities/dao · Domain entities, repositories, DTOs, and mappers for users, posts, comments, tags, messages, and points. · `backend/src/main/java/com/openisle/model`
- [Search](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/search): opensearch indexer · Event-driven indexing boundary with OpenSearch, no-op fallback, and reindex bootstrapping. · `backend/src/main/java/com/openisle/search`
- [Notify producer](https://github.com/nagisa77/openisle/blob/main/backend/src/main/java/com/openisle/service/NotificationProducer.java): rabbitmq publisher · Publishes live notification and message payloads from the backend to the messaging bus. · `backend/src/main/java/com/openisle/service/NotificationProducer.java`
- [Schedulers](https://github.com/nagisa77/openisle/tree/main/backend/src/main/java/com/openisle/scheduler): async/background · Async and scheduled processing for activity, recalculation, and maintenance jobs. · `backend/src/main/java/com/openisle/scheduler`
- [DB schema](https://github.com/nagisa77/openisle/tree/main/backend/src/main/resources/db): flyway/sql · Database bootstrap, seed data, and versioned migrations for the relational schema. · `backend/src/main/resources/db`

### Frontend

Nuxt client and browser-side interaction layer.

- [Nuxt app](https://github.com/nagisa77/openisle/tree/main/frontend_nuxt): nuxt-vue client · Primary user-facing SPA-style frontend with page routing and shared UI components. · `frontend_nuxt`
- [Live UI](https://github.com/nagisa77/openisle/tree/main/frontend_nuxt/composables): websocket/ui composables · Browser-side realtime hooks for unread counts, toasts, auth fetch, and websocket state. · `frontend_nuxt/composables`
- [Auth pages](https://github.com/nagisa77/openisle/tree/main/frontend_nuxt/pages): oauth callbacks · Login, signup, password reset, and provider callback pages for social auth flows. · `frontend_nuxt/pages`
- [Content UI](https://github.com/nagisa77/openisle/tree/main/frontend_nuxt/components): editor/post views · Post, comment, reaction, poll, medal, notification, and message presentation components. · `frontend_nuxt/components`

### Realtime

WebSocket fan-out service for live delivery.

- [WebSocket svc](https://github.com/nagisa77/openisle/blob/main/websocket_service/src/main/java/com/openisle/websocket/WebsocketServiceApplication.java): spring websocket · Separate realtime service that authenticates sockets and pushes notifications to clients. · `websocket_service/src/main/java/com/openisle/websocket/WebsocketServiceApplication.java`
- [RabbitMQ](https://github.com/nagisa77/openisle/tree/main/docker/rabbitmq): message bus · Shared delivery channel between backend producers and websocket consumers. · `docker/rabbitmq`

### Ops

Deployment, containers, docs, and automation.

- [Nginx edge](https://github.com/nagisa77/openisle/tree/main/nginx): reverse proxy · Front door and routing layer for the multi-service deployment. · `nginx`
- [Compose stack](https://github.com/nagisa77/openisle/blob/main/docker/docker-compose.yaml): containers · Container definitions for backend, frontend, websocket service, MySQL, Redis, RabbitMQ, and OpenSearch. · `docker/docker-compose.yaml`
- [Docs site](https://github.com/nagisa77/openisle/tree/main/docs): nextjs docs · Static documentation site generated from repository content and backend OpenAPI data. · `docs`
- [Bots](https://github.com/nagisa77/openisle/tree/main/bots): automation scripts · TypeScript community bots for scheduled posts and reply automation. · `bots`

## Connections

- Nuxt app → Controllers: REST APIs · Frontend pages and components fetch application data and submit mutations through the backend API.
- Live UI → WebSocket svc: socket client · Client-side composables connect to the websocket service for live events.
- Auth pages → Controllers: login flows · Callback pages complete OAuth and JWT-based authentication against backend endpoints.
- Content UI → Controllers: content actions · Editors and content components drive post, comment, reaction, upload, and notification flows.
- Controllers → Services: delegates · Controllers hand requests to service-layer business logic.
- Services → Data model: reads/writes · Services use repositories, entities, and mappers to persist and assemble domain state.
- Services → Search: index events · Domain changes emit search indexing and delete events.
- Search → DB schema: bootstrap schema · Search initialization and reindexing depend on stored domain data.
- Services → Notify producer: publish live · Notification and message services publish payloads for realtime fan-out.
- Services → Schedulers: async work · Background tasks and scheduled jobs support analytics, cleanup, and recalculation.
- Data model → DB schema: schema · Entities and repositories map onto the relational schema managed by migrations.
- Controllers → DB schema: admin/setup · Operational endpoints and bootstrapping rely on the configured database state.
- Notify producer → RabbitMQ: enqueue · Backend producers place live payloads onto RabbitMQ.
- WebSocket svc → RabbitMQ: consume · WebSocket listeners consume queued notification and message payloads.
- WebSocket svc → Live UI: push updates · Realtime service delivers socket events that update unread counts and live UI state.
- Nginx edge → Nuxt app: routes · Edge proxy serves and routes browser traffic to the frontend.
- Nginx edge → API app: routes · Edge proxy routes API traffic to the backend application.
- Nginx edge → WebSocket svc: routes · Edge proxy exposes websocket traffic to the realtime service.
- Compose stack → API app: deploys · Compose stack defines the backend runtime and its dependencies.
- Compose stack → Nuxt app: deploys · Compose stack defines the frontend runtime.
- Compose stack → WebSocket svc: deploys · Compose stack defines the websocket service runtime.
- Docs site → Controllers: reads OpenAPI · Documentation site consumes backend API descriptions and generated docs content.
- Bots → Controllers: community automation · Bots interact with the platform through APIs and external channels.