📚 docs.plus

docs.plus is a free, real-time collaboration tool built on open-source technologies. It empowers communities to share and organize information logically and hierarchically, making teamwork and knowledge sharing straightforward and effective.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              CLIENT LAYER                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌──────────────────┐    ┌──────────────────┐    ┌────────────────────┐   │
│   │     Webapp       │    │  Admin Dashboard │    │  TipTap Extensions │   │
│   │    (Next.js)     │    │    (Next.js)     │    │  hyperlink, media  │   │
│   │    Port 3000     │    │    Port 3100     │    │   indent, code     │   │
│   └────────┬─────────┘    └────────┬─────────┘    └────────────────────┘   │
│            │                       │                                         │
└────────────┼───────────────────────┼─────────────────────────────────────────┘
             │ HTTP/WS               │ HTTP
             ▼                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             BACKEND LAYER                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐     │
│   │    REST API      │    │    WebSocket     │    │     Worker       │     │
│   │     (Hono)       │    │   (Hocuspocus)   │    │    (BullMQ)      │     │
│   │    Port 4000     │    │    Port 4001     │    │    Port 4002     │     │
│   │                  │    │                  │    │                  │     │
│   │  • Auth          │    │  • Real-time     │    │  • Doc storage   │     │
│   │  • Documents     │    │    collaboration │    │  • Email queue   │     │
│   │  • Workspaces    │    │  • Y.js sync     │    │  • Push notifs   │     │
│   └────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘     │
│            │                       │                       │                │
└────────────┼───────────────────────┼───────────────────────┼────────────────┘
             │                       │                       │
             ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              DATA LAYER                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   ┌───────────────────────────────┐    ┌───────────────────────────────┐   │
│   │         PostgreSQL            │    │            Redis              │   │
│   │         (Supabase)            │    │                               │   │
│   │         Port 5432             │    │         Port 6379             │   │
│   │                               │    │                               │   │
│   │  • Users & Auth               │    │  • Job queues (BullMQ)        │   │
│   │  • Documents & Workspaces     │    │  • Pub/Sub (WS sync)          │   │
│   │  • Realtime subscriptions     │    │  • Session cache              │   │
│   │  • Row Level Security         │    │  • Rate limiting              │   │
│   └───────────────────────────────┘    └───────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

                           ┌─────────────────┐
                           │ Supabase Studio │
                           │  Port 54323     │
                           │  (Dev only)     │
                           └─────────────────┘

Monorepo Structure:

🌐 packages/webapp - Next.js frontend with TipTap editor
🖥️ packages/admin-dashboard - Admin panel for platform management
⚡ packages/hocuspocus.server - REST API, WebSocket server, and background workers
🗄️ packages/supabase - Database migrations and Supabase configuration
🔌 packages/extension-* - TipTap extensions (hyperlink, multimedia, indent, inline-code)
📦 packages/eslint-config - Shared ESLint configurations

Tech Stack:

Runtime: 🚀 Bun 1.3.7+
Frontend: ⚛️ Next.js 15/16, React 19, TipTap 3, Tailwind CSS 4
Backend: 🔧 Hono, Hocuspocus (Y.js), BullMQ, Prisma ORM
Database: 🐘 PostgreSQL 17, 🔴 Redis
Infrastructure: 🐳 Docker Compose, Supabase
Real-time: 🔌 WebSocket (Hocuspocus), Supabase Realtime

📋 Prerequisites

🐳 Docker & Docker Compose v2+ - Install
- ⚠️ macOS Silicon users: Docker Desktop has IO performance issues. Use OrbStack instead (drop-in replacement, faster, lighter).
🚀 Bun >=1.3.7 - Install
🗄️ Supabase CLI - Install

🚀 Quick Start

1️⃣ Clone & Install

git clone https://github.com/docs-plus/docs.plus.git
cd docs.plus
bun install

2️⃣ Environment Configuration

Create environment files based on your development mode:

# Required: Create .env.development first (used by Docker dev and as base for local dev)
cp .env.example .env.development

Environment File Mapping:

| Docker Compose File | Environment File | Usage | | -------------------------- | ------------------ | ------------------------------------------------ | | docker-compose.prod.yml | .env.production | Production deployment | | docker-compose.dev.yml | .env.development | Docker development (all services in containers) | | docker-compose.local.yml | .env.local | Local development (infra in Docker, apps native) |

Important Differences:

.env.development (Docker Development):

Uses Docker service names for inter-container communication:
- SERVER_RESTAPI_URL=http://rest-api:4000/api (Docker service name)
- REDIS_HOST=redis (Docker service name)
- DATABASE_URL is set by Docker Compose (not in file)

.env.local (Local Development):

Uses localhost for native apps connecting to Docker infrastructure:
- SERVER_RESTAPI_URL=http://localhost:4000/api (localhost)
- REDIS_HOST=localhost (localhost)
- DATABASE_URL=postgresql://...@localhost:5432/... (explicit connection string)
Auto-created from .env.development when you run make dev-local or make infra-up
Gitignored - safe for local customizations

Note: .env.local is automatically created from .env.development on first run. You only need to create .env.development manually.

3️⃣ Initialize Supabase

<details> <summary><strong>🗄️ Option A: Local Supabase Setup (One-time, ~5-10 min)</strong></summary>

Step 1: Start Supabase 🚀

make supabase-start

First run downloads Docker images. Verify with make supabase-status.

Step 2: Activate Extensions 🔌

Open Supabase Studio
Go to Integrations
Activate: pg_cron and pgmq (Queues)

Step 3: Run Migrations 📊

Open SQL Editor
Execute scripts from packages/supabase/scripts/ in order: 01-enum.sql through 17-database-extensions.sql

Step 4: Configure Queues ⚙️

Queue Settings → Enable "Expose Queues via PostgREST"
Queues → Select message_counter → Manage permissions
Enable Select/Insert/Update/Delete for: authenticated, postgres, service_role
Add RLS policy: "Allow anon and authenticated to access messages from queue"

</details> <details> <summary><strong>☁️ Option B: Supabase Cloud Setup</strong></summary>

If you prefer not to run Supabase locally, you can use a cloud project instead:

Step 1: Create Supabase Project 🚀

Go to Supabase Dashboard
Create a new project
Copy your project URL and anon key from Settings → API

Step 2: Update Environment Variables ⚙️ Update .env.development with your cloud project credentials:

# Server-side (containers → Supabase Cloud)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here

# Client-side (browser → Supabase Cloud)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_WS_URL=wss://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

Step 3: Configure Extensions & Migrations 📊 You still need to configure your cloud project:

Activate pg_cron and pgmq (Queues) extensions in the Dashboard
Run SQL scripts from packages/supabase/scripts/ in order via SQL Editor
Configure queues and permiss

Docs.plus

Install / Use

README