How nagisa77/openisle works
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: controller Controllers · service Services · WebsocketServiceApplication.java WebSocket svc · nginx Nginx edge
Components 18
Backend
Spring Boot API, domain services, persistence, and search.
- API app · Main backend application and REST boundary for the community platform.
backend/src/main/java/com/openisle/OpenIsleApplication.java - Controllers · HTTP entrypoints for auth, posts, comments, users, notifications, search, uploads, admin, and stats.
backend/src/main/java/com/openisle/controller - Services · Core orchestration for auth, posts, messaging, notifications, points, medals, search, and uploads.
backend/src/main/java/com/openisle/service - Data model · Domain entities, repositories, DTOs, and mappers for users, posts, comments, tags, messages, and points.
backend/src/main/java/com/openisle/model - Search · Event-driven indexing boundary with OpenSearch, no-op fallback, and reindex bootstrapping.
backend/src/main/java/com/openisle/search - Notify producer · Publishes live notification and message payloads from the backend to the messaging bus.
backend/src/main/java/com/openisle/service/NotificationProducer.java - Schedulers · Async and scheduled processing for activity, recalculation, and maintenance jobs.
backend/src/main/java/com/openisle/scheduler - DB schema · 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 · Primary user-facing SPA-style frontend with page routing and shared UI components.
frontend_nuxt - Live UI · Browser-side realtime hooks for unread counts, toasts, auth fetch, and websocket state.
frontend_nuxt/composables - Auth pages · Login, signup, password reset, and provider callback pages for social auth flows.
frontend_nuxt/pages - Content UI · Post, comment, reaction, poll, medal, notification, and message presentation components.
frontend_nuxt/components
Realtime
WebSocket fan-out service for live delivery.
- WebSocket svc · Separate realtime service that authenticates sockets and pushes notifications to clients.
websocket_service/src/main/java/com/openisle/websocket/WebsocketServiceApplication.java - RabbitMQ · Shared delivery channel between backend producers and websocket consumers.
docker/rabbitmq
Ops
Deployment, containers, docs, and automation.
- Nginx edge · Front door and routing layer for the multi-service deployment.
nginx - Compose stack · Container definitions for backend, frontend, websocket service, MySQL, Redis, RabbitMQ, and OpenSearch.
docker/docker-compose.yaml - Docs site · Static documentation site generated from repository content and backend OpenAPI data.
docs - Bots · TypeScript community bots for scheduled posts and reply automation.
bots
Connections 23
- 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.