# chinalhr/javaquarkbbs architecture

> Architecture diagram of the GitHub repository chinalhr/javaquarkbbs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chinalhr/javaquarkbbs
- Repository: https://github.com/chinalhr/javaquarkbbs

## Overview

##### Project Type and Purpose
- It is a full-stack community/BBS system built in Java.
- The system divides responsibilities between administration (quark-admin), public facing portal (quark-portal), RESTful backend services (quark-rest), real-time chat functionality (quark-chat), and a shared common module (quark-common) handling DAOs, entities, DTOs, and base services.
- The project leverages modern technologies like Spring Boot, Spring MVC, REST APIs, WebSocket (and Netty for the chat server), Shiro for security, and caching solutions (Redis and Ehcache).

##### Key Components
a. quark-common:
- Acts as the foundational service layer.
- Contains Spring Data with MySQL access, base controllers, DAOs, entity definitions, DTOs, and utility classes.
b. quark-admin:
- Provides an administration backend using Spring Boot.
- Implements fine-grained URL-based permission management with Shiro for managing posts, labels, users, roles, and replies.
c. quark-rest:
- Exposes RESTFul API endpoints using Spring MVC.
- Integrates Swagger2 for API documentation.
- Provides additional services like WebSocket endpoints for push notifications (supporting both one-to-one and one-to-many communications).
d. quark-portal:
- Serves as the front-end client for the community.
- Uses Spring MVC for page rendering combined with LayUI, jQuery, and Thymeleaf templating to dynamically render pages by calling the REST APIs.
e. quark-chat:
- Implements a real-time chat service.
- Built on Netty and WebSocket with a defined application-layer protocol (with commands like PING, PONG, AUTH, MESSAGE, etc.).
- Uses a JSON-based message format and heartbeat mechanism.
f. External/Shared Infrastructure:
- MySQL as the primary relational database.
- Redis for caching of hot data.
- Ehcache for secondary (database) caching.
- Nginx is used in deployment as a reverse proxy and image server.

##### Relationships and Interactions
- The quark-common module supports all other modules by providing shared entities, DTOs, and DAO functionalities.
- The quark-admin module interacts with the database (via quark-common) and provides backend administrative functions, authentication, and permission management.
- The quark-rest module provides API endpoints consumed by the quark-portal for public community operations; it can also expose WebSocket connections for client notifications.
- The quark-portal acts as the user-facing interface and consumes REST APIs from quark-rest.
- The quark-chat module operates as an independent real-time chat server that handles its own protocols and interacts with clients via WebSockets, possibly using Redis for session/connection management.
- Components like Redis, MySQL, and Nginx directly serve multiple modules, so represent them as shared infrastructure nodes.

##### Architectural Patterns and Design Principles
- Emphasizes modularity and separation of concerns (front-end, admin, API, chat).
- Uses layered architecture (controllers, services, DAOs) with cross-cutting functionalities provided by quark-common.
- Employs RESTful paradigms for external communication.
- Adopts real-time communication patterns using WebSocket and Netty in the chat module.
- Implements security with Shiro and uses caching layers for performance optimization.

##### Technology Highlights
- Spring Boot/Spring MVC as the primary framework.
- Shiro for security in quark-admin.
- Swagger2 for REST API documentation in quark-rest.
- Netty for chat server performance.
- Redis and Ehcache for caching.
- Traditional web technologies (jQuery, LayUI, Thymeleaf) for the portal.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Presentation Layer"
        QPORTAL("quark-portal"):::module
        QADMIN("quark-admin"):::module
    end

    subgraph "Service Layer"
        QREST("quark-rest"):::module
    end

    subgraph "Communication Layer"
        QCHAT("quark-chat"):::module
    end

    subgraph "Data/Business Logic Layer"
        QCOMMON("quark-common"):::module
    end

    subgraph "Infrastructure"
        MYSQL("MySQL"):::infra
        REDIS("Redis"):::infra
        NGINX("Nginx"):::infra
    end

    QPORTAL -->|"HTTP/REST"| QREST
    QREST -->|"access"| QCOMMON
    QADMIN -->|"access"| QCOMMON
    QCOMMON -->|"DBOps"| MYSQL
    QADMIN -->|"DBOps"| MYSQL
    QCHAT -->|"session_management"| REDIS
    NGINX -->|"serves"| QPORTAL
    NGINX -->|"serves"| QADMIN

    click QCOMMON "https://github.com/chinalhr/javaquarkbbs/tree/master/quark-common/src/main/java/com/quark/common"
    click QADMIN "https://github.com/chinalhr/javaquarkbbs/tree/master/quark-admin/src/main/java/com/quark/admin"
    click QREST "https://github.com/chinalhr/javaquarkbbs/tree/master/quark-rest/src/main/java/com/quark/rest"
    click QPORTAL "https://github.com/chinalhr/javaquarkbbs/tree/master/quark-portal/src/main/java/com/quark/porent"
    click QCHAT "https://github.com/chinalhr/javaquarkbbs/tree/master/quark-chat/src/main/java/com/quark/chat"

    classDef module fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef infra fill:#F9E79F,stroke:#B7950B,stroke-width:2px,stroke-dasharray: 5, 5;
```
