# liaoran2002/ficq architecture

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

- Interactive diagram: https://gitdiagram.com/liaoran2002/ficq
- Repository: https://github.com/liaoran2002/ficq

## Overview

##### Project type and purpose
- This is a full-stack, multi-platform instant-messaging system (“FICQ”) that mimics QQ.
- It comprises three main modules:
- FICQ (backend): Java Spring Boot/Netty server handling REST APIs, WebSocket/TCP messaging, WebRTC signaling, persistence via MyBatis-Plus, file storage, and admin functions.
- FICQ-web: Vue.js SPA (with Vuex store, Vue Router) as the web client for chat, user/group management, and admin console.
- FICQ-uniapp: Uni-app hybrid/mobile client supporting iOS/Android/H5 with Vue-style components, uni-modules, and WSSocket/HTTP wrappers.

##### File structure
- Top-level directories:
- FICQ-uniapp: mobile client source (App.vue, pages/, components/, common/, store/, uni_modules/)
- FICQ-web: web client source (src/api/, src/components/, src/view/, src/store/, src/router/)
- FICQ: backend service (src/main/java with layered packages controller/, service/, mapper/, netty/, config/)
- Config and build: pom.xml for Java, package.json/vite.config.js for clients, uniapp manifest.json, env files.
- Notice WebSocketConfig.java and Netty packages for both WebSocket and TCP protocols.
- README outlines core features: text, file transfer, user/group management, WebRTC audio/video.

##### Main components and their relationships
a. Clients
- Mobile client (Uni-app) & Web client (Vue.js)
- Layers: UI layer (pages/components) → API wrapper (common/request.js or src/api/httpRequest.js) → HTTP & WSSocket & WebRTC calls
b. Gateway/API layer
- Spring MVC REST controllers (LoginController, Chat controllers, FileController, AdminController)
- WebSocket endpoints (WebSocketServer) and TCP endpoints (TcpSocketServer)
- WebRTC signaling via REST or WebSocket (rtcGroupApi.js, rtcPrivateApi.js)
c. Business layer
- Service interfaces & impl (UserService, MessageService, WebrtcPrivateService)
- Message listeners & multicaster (Observer pattern)
d. Data layer
- MyBatis-Plus mappers & entity models mapping to relational database.
- application.yml defines JDBC, JWT, scheduler, static resources.
e. External services
- FileService for upload/storage
- Third-party authentication or analysis if any

##### Architectural patterns and design principles
- Layered architecture (Controller → Service → Mapper → DB)
- Event-driven messaging (MessageListener, multicaster)
- Observer for WebSocket/TCP message processors (ProcessorFactory, AbstractMessageProcessor)
- MVVM in front-ends (Vue + Vuex stores)
- REST + WebSocket hybrid integration
- Single monolith backend (not microservices), but modular for controllers, netty, services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        subgraph "Mobile App (Uni-app)" 
            direction TB
            UniAppDir["FICQ-uniapp/"]:::clients
            AppVue["App.vue"]:::clients
            MainMobile["main.js"]:::clients
            Manifest["manifest.json"]:::clients
            PackageMobile["package.json"]:::clients
            Pages["pages/"]:::clients
            ComponentsMobile["components/"]:::clients
            RequestMobile["common/request.js"]:::clients
            WSSocketClient["common/wssocket.js"]:::clients
            StoreMobile["store/"]:::clients
        end
        subgraph "Web App (Vue.js)" 
            direction TB
            WebDir["FICQ-web/src/"]:::clients
            MainWeb["main.js"]:::clients
            PackageWeb["package.json"]:::clients
            Vite["vite.config.js"]:::clients
            Views["src/view/"]:::clients
            ComponentsWeb["src/components/"]:::clients
            HTTPRequest["src/api/httpRequest.js"]:::clients
            WSSocketWeb["src/api/wssocket.js"]:::clients
            RTCGroupAPI["src/api/rtcGroupApi.js"]:::clients
            RTCPrivateAPI["src/api/rtcPrivateApi.js"]:::clients
            WebRTCAPI["src/api/webrtc.js"]:::clients
            Router["src/router/index.js"]:::clients
            StoreWeb["src/store/"]:::clients
        end
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        direction TB
        subgraph "REST API Layer"
            direction TB
            Controllers["LoginController\nUserController\nFriendController\nGroupController\nPrivateMessageController\nGroupMessageController\nFileController\nAdminController"]:::api
        end
        subgraph "Real-time Gateways"
            direction TB
            WSServer["WebSocketServer"]:::api
            TCPServer["TcpSocketServer"]:::api
            WSCodec["WS Encoder/Decoder"]:::api
            TCPCodec["TCP Encoder/Decoder"]:::api
        end
        subgraph "WebRTC Signaling"
            direction TB
            RTCSignal["WebRTC Signaling Endpoints"]:::api
        end
    end

    %% Business Layer
    subgraph "Business Layer"
        direction TB
        Services["Service Interfaces & Impl"]:::biz
        ProcessorFactoryNode["ProcessorFactory"]:::biz
        MessageProcessors["AbstractMessageProcessor\nLoginProcessor\nHeartbeatProcessor\nPrivateMessageProcessor\nGroupMessageProcessor\nSystemMessageProcessor"]:::biz
        Listeners["MessageListenerMulticaster"]:::biz
    end

    %% Data & External Layer
    subgraph "Data & External"
        direction TB
        DB["Relational Database (MySQL)"]:::data
        Mappers["MyBatis Mappers"]:::data
        Entities["Entities / Models"]:::data
        FileService["File Storage Service"]:::external
    end

    %% Connections
    %% Mobile
    AppVue -->|UI| RequestMobile
    RequestMobile -->|HTTP| Controllers
    WSSocketClient -->|WSSocket| WSServer
    RequestMobile -->|"WebRTC"| RTCSignal
    %% Web
    MainWeb -->|UI| HTTPRequest
    HTTPRequest -->|HTTP| Controllers
    WSSocketWeb -->|WSSocket| WSServer
    HTTPRequest -->|"WebRTC"| RTCSignal

    %% Server internals
    Controllers -->|calls| Services
    WSServer -->|dispatch| ProcessorFactoryNode
    TCPServer -->|dispatch| ProcessorFactoryNode
    ProcessorFactoryNode -->|creates| MessageProcessors
    MessageProcessors -->|use| Services
    Services -->|persist| Mappers
    Mappers -->|map| Entities
    Services -->|store files| FileService

    %% WebRTC
    RTCSignal -->|invoke| Services

    %% Data flow
    Services -->|query/update| DB

    %% Click Events
    click UniAppDir "https://github.com/liaoran2002/ficq/tree/main/FICQ-uniapp/"
    click AppVue "https://github.com/liaoran2002/ficq/blob/main/FICQ-uniapp/App.vue"
    click MainMobile "https://github.com/liaoran2002/ficq/blob/main/FICQ-uniapp/main.js"
    click Manifest "https://github.com/liaoran2002/ficq/blob/main/FICQ-uniapp/manifest.json"
    click PackageMobile "https://github.com/liaoran2002/ficq/blob/main/FICQ-uniapp/package.json"
    click Pages "https://github.com/liaoran2002/ficq/tree/main/FICQ-uniapp/pages/"
    click ComponentsMobile "https://github.com/liaoran2002/ficq/tree/main/FICQ-uniapp/components/"
    click RequestMobile "https://github.com/liaoran2002/ficq/blob/main/FICQ-uniapp/common/request.js"
    click WSSocketClient "https://github.com/liaoran2002/ficq/blob/main/FICQ-uniapp/common/wssocket.js"
    click StoreMobile "https://github.com/liaoran2002/ficq/tree/main/FICQ-uniapp/store/"

    click WebDir "https://github.com/liaoran2002/ficq/tree/main/FICQ-web/src/"
    click MainWeb "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/main.js"
    click PackageWeb "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/package.json"
    click Vite "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/vite.config.js"
    click Views "https://github.com/liaoran2002/ficq/tree/main/FICQ-web/src/view/"
    click ComponentsWeb "https://github.com/liaoran2002/ficq/tree/main/FICQ-web/src/components/"
    click HTTPRequest "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/api/httpRequest.js"
    click WSSocketWeb "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/api/wssocket.js"
    click RTCGroupAPI "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/api/rtcGroupApi.js"
    click RTCPrivateAPI "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/api/rtcPrivateApi.js"
    click WebRTCAPI "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/api/webrtc.js"
    click Router "https://github.com/liaoran2002/ficq/blob/main/FICQ-web/src/router/index.js"
    click StoreWeb "https://github.com/liaoran2002/ficq/tree/main/FICQ-web/src/store/"

    click Controllers "https://github.com/liaoran2002/ficq/tree/main/FICQ/src/main/java/org/lc/ficq/controller/"
    click WSServer "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/ws/WebSocketServer.java"
    click TCPServer "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/tcp/TcpSocketServer.java"
    click WSCodec "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/ws/endecode/MessageProtocolEncoder.java"
    click WSCodec "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/ws/endecode/MessageProtocolDecoder.java"
    click TCPCodec "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/tcp/endecode/MessageProtocolEncoder.java"
    click TCPCodec "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/tcp/endecode/MessageProtocolDecoder.java"

    click ProcessorFactoryNode "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/ProcessorFactory.java"
    click MessageProcessors "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/AbstractMessageProcessor.java"
    click MessageProcessors "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/LoginProcessor.java"
    click MessageProcessors "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/HeartbeatProcessor.java"
    click MessageProcessors "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/PrivateMessageProcessor.java"
    click MessageProcessors "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/GroupMessageProcessor.java"
    click MessageProcessors "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/netty/processor/SystemMessageProcessor.java"

    click Services "https://github.com/liaoran2002/ficq/tree/main/FICQ/src/main/java/org/lc/ficq/service/"
    click Services "https://github.com/liaoran2002/ficq/tree/main/FICQ/src/main/java/org/lc/ficq/service/impl/"
    click Mappers "https://github.com/liaoran2002/ficq/tree/main/FICQ/src/main/java/org/lc/ficq/mapper/"
    click Entities "https://github.com/liaoran2002/ficq/tree/main/FICQ/src/main/java/org/lc/ficq/entity/"
    click Entities "https://github.com/liaoran2002/ficq/tree/main/FICQ/src/main/java/org/lc/ficq/model/"
    click FileService "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/service/thirdparty/FileService.java"
    click FileController "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/controller/FileController.java"
    click RTCSignal "https://github.com/liaoran2002/ficq/blob/main/FICQ/src/main/java/org/lc/ficq/service/WebrtcPrivateService.java"

    %% Styles
    classDef clients fill:#b3d9ff,stroke:#3399ff,color:#000
    classDef api fill:#ccffcc,stroke:#33cc33,color:#000
    classDef biz fill:#ffe0b3,stroke:#ff9933,color:#000
    classDef data fill:#eeeeee,stroke:#999999,color:#000
    classDef external fill:#e6ccff,stroke:#9933cc,color:#000
```
