Qubar

English | 简体中文

A modern interest-based community backend written in Go with DDD (Domain-Driven Design), similar to Baidu Tieba / Reddit.

✨ Features

Qubar is a full-featured interest community platform offering:

• Interest Circles – Users can create and join topic-based communities
• Content Publishing – Rich text posts with image/video uploads
• Comments – Two-level flattened comment structure with replies and likes
• User System – Email/password registration + multi-platform OAuth login
• Permission Management – Three-tier RBAC (owner / admin / member) per circle
• Circle Management – Role assignment, ownership transfer, mute, ban, join review, profile editing
• AI Agents (Bots) – Global agents managed by platform admins + circle-scoped agents managed by circle owners/admins, with keyword / manual / @mention triggers
• Message Center – Notification fan-out via Redpanda, unread count, mark-read, and SSE real-time unread push
• @Mentions – Precise mention binding persisted for posts and comments
• Full-text Search – Search engine for users, circles and posts
• Discovery & Recommendation – Home feed, trending posts, discover page, browsing history, favorites
• Async Statistics – Write-Behind cache strategy for high-concurrency scenarios

🛠 Tech Stack

Core Frameworks

• CloudWeGo Hertz – High-performance HTTP framework (replaced Gin)
• CloudWeGo Eino – LLM application framework (OpenAI / Claude / Gemini model components)
• GORM – ORM for database access
• Sa-Token – Lightweight authentication framework
• Viper – Configuration management
• Zap – High-performance logging

Data Stores & Middleware

Component	Version	Purpose
PostgreSQL	18	Primary database, UUIDv7 primary keys, JSONB support
Redis	7+	Cache & session store, atomic ops via Lua scripts
Elasticsearch	8.x	Full-text search with real-time index sync (via CDC)
Redpanda	latest	Kafka-compatible message queue for async stats aggregation & notification fan-out
AWS S3	-	Object storage (images/videos) with presigned URLs
Nacos	3.x	Configuration center with multi-environment support
Mailtrap	-	Email delivery (verification codes / notifications)

Authentication

• Google OAuth 2.0
• GitHub OAuth
• Azure AD OAuth
• Email/password with verification code

🏗 Architecture

DDD (Domain-Driven Design)

The project follows a modular monolith architecture, with packages split by domain boundaries so it can be smoothly decomposed into microservices later:

pkg/
├── composition/          # Composition layer: wire dependencies, register routes, cross-domain Facade bridges
│   ├── hertzadapter/     # Hertz framework adapter → framework-agnostic routing abstraction
│   └── middleware/       # Global middleware (CORS, logging)
│
├── domains/              # Domain layer (each domain is self-contained)
│   ├── auth/             # Authentication (login, registration, OAuth)
│   ├── user/             # User (profiles, search)
│   ├── category/         # Category (circle categories)
│   ├── circle/           # Circle (creation, membership, permissions, management)
│   ├── post/             # Post (publishing, lists, details)
│   ├── comment/          # Comment (two-level flattened structure)
│   ├── like/             # Like (atomic ops + events)
│   ├── collect/          # Favorites
│   ├── history/          # Browsing history
│   ├── discover/         # Discover page aggregation
│   ├── trending/         # Trending posts
│   ├── recommend/        # Home feed recommendation
│   ├── notice/           # Message center (notifications + SSE unread stream)
│   ├── aiagent/          # AI agents (global + circle-scoped bots, reply triggers)
│   ├── storage/          # Storage (file uploads)
│   └── [domain]/
│       ├── application/      # Application services: use-case orchestration
│       ├── domain/           # Domain layer: models, repository interfaces, core business rules
│       ├── infrastructure/   # Infrastructure: repository impls, cache, search, events
│       └── interfaces/http/  # Interface layer: handlers, routes, DTOs
│
├── shared/               # Shared kernel (domain-agnostic)
│   ├── appctx/           # Context abstraction
│   ├── domain/           # Domain base classes (BaseModel)
│   ├── httputil/         # HTTP response utilities
│   └── routing/          # Framework-agnostic routing abstraction
│
├── conf/                 # Configuration loading (Nacos + local fallback)
└── logger/               # Logging initialization

Key Design Decisions

1. UUIDv7 primary keys – First 48 bits are a timestamp; lexicographic order = chronological order, natively supporting keyset cursor pagination
2. Framework-agnostic routing – Domain code never depends on Hertz via the routing.RouterGroup abstraction
3. Cross-domain Facades – Domains call each other through interfaces without direct coupling; switching to microservices only requires swapping implementations
4. Write-Behind caching – Real-time Redis updates + async batch persistence via Redpanda for high concurrency
5. Two-level flattened comments – root_id marks hierarchy, avoiding recursive queries and enabling efficient pagination
6. Dual-scope AI agents – Global agents (platform admin) and circle agents (circle owner/admin) are fully isolated: cross-scope access returns 404, never leaking existence

🤖 AI Agents

Qubar ships with a two-tier AI agent system:

This is the beginning of the README. Read the rest at the original. Read the full README ↗