# mlogclub/bbs-go architecture

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

- Interactive diagram: https://gitdiagram.com/mlogclub/bbs-go
- Repository: https://github.com/mlogclub/bbs-go

## Overview

##### Project type and purpose
- This is a full-stack, modular community forum system (“bbs-go”) composed of three main pieces:
a. **server**: A Go-based REST API & background services layer (Iris MVC, GORM, cron scheduler, caches, event bus)
b. **site**: A Nuxt.js-based server-side-rendered Vue frontend for end users
c. **admin**: A Vue + Arco/Element-UI SPA for administrators

##### File structure
- Top-level modules
- **server/** – the Go backend, organized in packages:
– internal/controllers (api, admin, render)
– internal/services (business logic, event handlers)
– internal/repositories (data access)
– internal/cache, middleware, scheduler
– internal/pkg (email, sms, token, uploader, spam strategies, event bus)
– migrations, locales, config
- **site/** – the Nuxt app, with pages, components, plugins, server middleware, stores
- **admin/** – the Vite + Vue SPA, with src/components, src/api, store, router, config

##### Readme insights
- server uses Iris, GORM, Resty, cron, goquery
- site uses Nuxt.js for SSR
- admin uses Vue + Element UI (Arco)
- Supports MySQL, Redis cache, OSS image uploads, email/SMS, captcha, SEO push

##### Main components & their relationships
A. **Frontend clients**
1. **Admin SPA**
– Runs in browser (Arco UI) → calls REST endpoints on server/admin controllers
2. **Public site (SSR)**
– Nuxt server → pre-renders pages → calls REST endpoints on server/api controllers
B. **API server**
– **Router** → maps requests (api vs. admin vs. render) to Controllers
– **Controllers** → call Services
– **Services** → implement business logic, publish/subscribe events
– **Repositories** → CRUD on **MySQL** via GORM
– **Cache layer** (Redis) for hot data (user tokens, topic lists, tags)
– **Scheduler** (robfig/cron) → periodic tasks (notifications, cleanup)
– **Event bus** → internal event dispatch (ANTS pool) → eventhandler services
– **Middleware** → auth, install check, metrics
– **External integrations**:
- OSS Uploader (Aliyun OSS, Tencent COS)
- Email service (SMTP)
- SMS provider
- SEO push (search engine hooks)
- Captcha
C. **Data stores & external services**
– **MySQL database** (persistent storage)
– **Redis** (cache, captcha/session store)
– **Email/SMS gateway**
– **Object storage** (OSS)
– **Search engine** (if used via push API)

##### Architectural patterns & design principles
- **Layered MVC** in server: Router → Controller → Service → Repository → Model → DB/cache
- **Pub/Sub event bus** for decoupling side-effects (notifications, recommendations)
- **Cron-driven scheduler** for timed tasks
- **API-first design**: server exposes REST APIs for both frontends
- **SSR & SPA separation**: Nuxt for SEO, dynamic admin SPA

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        AdminSPA["Admin SPA\n(Vue, Arco UI)"]:::frontend
        PublicSite["Public Site\n(Nuxt.js SSR)"]:::frontend
    end

    subgraph "API Server (Go + Iris, GORM)"
        Router["Router\n(router.go, init.go)"]:::api
        Middleware["Middleware\n(auth, install check, metrics)"]:::api

        subgraph "Controllers"
            AdminCtrl["Admin Controllers"]:::api
            ApiCtrl["API Controllers"]:::api
            RenderCtrl["SSR Renderers"]:::api
        end

        subgraph "Services"
            ServicesBL["Business Services"]:::api
            EventHandlers["Event Handlers"]:::api
        end

        Repositories["Repositories\n(GORM)"]:::api
        CacheLayer["Cache Layer\n(Redis)"]:::api
    end

    subgraph "Background Workers"
        Scheduler["Scheduler\n(cron)"]:::api
        EventBus["Event Bus"]:::api
    end

    subgraph "Data Stores"
        MySQL[(MySQL)]:::data
        Redis[(Redis)]:::data
    end

    subgraph "External Integrations"
        OSS["Object Storage\n(Aliyun/Tencent)"]:::external
        Email["Email Service"]:::external
        SMS["SMS Provider"]:::external
        SEO["SEO Push"]:::external
        Captcha["Captcha Service"]:::external
    end

    AdminSPA -->|"HTTPS REST"| Router
    PublicSite -->|"Pre-render & REST"| Router

    Router --> Middleware
    Middleware --> AdminCtrl
    Middleware --> ApiCtrl
    Middleware --> RenderCtrl

    AdminCtrl --> ServicesBL
    ApiCtrl --> ServicesBL
    RenderCtrl --> ServicesBL

    ServicesBL --> Repositories
    ServicesBL --> CacheLayer
    ServicesBL --> OSS
    ServicesBL --> Email
    ServicesBL --> SMS
    ServicesBL --> SEO
    ServicesBL --> Captcha

    Repositories --> MySQL
    CacheLayer --> Redis

    Scheduler --> ServicesBL
    ServicesBL --> EventBus
    EventBus --> EventHandlers
    EventHandlers --> Repositories

    %% Click Events
    click AdminSPA "https://github.com/mlogclub/bbs-go/tree/master/admin/"
    click PublicSite "https://github.com/mlogclub/bbs-go/tree/master/site/"
    click Router "https://github.com/mlogclub/bbs-go/blob/master/server/internal/server/router.go"
    click Router "https://github.com/mlogclub/bbs-go/blob/master/server/internal/server/init.go"
    click AdminCtrl "https://github.com/mlogclub/bbs-go/tree/master/server/internal/controllers/admin/"
    click ApiCtrl "https://github.com/mlogclub/bbs-go/tree/master/server/internal/controllers/api/"
    click RenderCtrl "https://github.com/mlogclub/bbs-go/tree/master/server/internal/controllers/render/"
    click ServicesBL "https://github.com/mlogclub/bbs-go/tree/master/server/internal/services/"
    click EventHandlers "https://github.com/mlogclub/bbs-go/tree/master/server/internal/services/eventhandler/"
    click Repositories "https://github.com/mlogclub/bbs-go/tree/master/server/internal/repositories/"
    click CacheLayer "https://github.com/mlogclub/bbs-go/tree/master/server/internal/cache/"
    click Scheduler "https://github.com/mlogclub/bbs-go/blob/master/server/internal/scheduler/cron.go"
    click EventBus "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/event/event.go"
    click Middleware "https://github.com/mlogclub/bbs-go/tree/master/server/internal/middleware/"
    click ConfigLoader "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/config/config.go"
    click TokenManagement "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/token/user_token.go"
    click Captcha "https://github.com/mlogclub/bbs-go/tree/master/server/internal/pkg/captcha/"
    click Email "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/email/email.go"
    click SMS "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/sms/sms.go"
    click OSS "https://github.com/mlogclub/bbs-go/tree/master/server/internal/pkg/uploader/"
    click SEO "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/seo/push.go"
    click CommonUtils "https://github.com/mlogclub/bbs-go/blob/master/server/internal/pkg/common/utils.go"
    click Models "https://github.com/mlogclub/bbs-go/tree/master/server/internal/models/"
    click Migrations "https://github.com/mlogclub/bbs-go/tree/master/server/migrations/"
    click Entrypoint "https://github.com/mlogclub/bbs-go/blob/master/server/main.go"
    click ExampleConfig "https://github.com/mlogclub/bbs-go/blob/master/server/bbs-go.example.yaml"
    click DockerCompose "https://github.com/mlogclub/bbs-go/blob/master/docker-compose.yml"
    click GitHubActions "https://github.com/mlogclub/bbs-go/tree/master/.github/workflows/"
    click MakefileRoot "https://github.com/mlogclub/bbs-go/tree/master/Makefile"
    click ServerMakefile "https://github.com/mlogclub/bbs-go/tree/master/server/Makefile"

    classDef frontend fill:#D6E9FF,stroke:#004A9F,color:#000
    classDef api fill:#E8F5E9,stroke:#256029,color:#000
    classDef data fill:#FFF3E0,stroke:#E65100,color:#000
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#000
```
