A modern, distributed microservices-based collaborative document editing platform. This workspace enables real-time collaboration on documents with a robust backend architecture supporting user management, authentication, workspace management, and page persistence.
Collaborative Knowledge Workspace is built using a microservices architecture with the following components:
- API Gateway: Entry point for all client requests using Spring Cloud Gateway
- Auth Service: Authentication and authorization using JWT tokens
- User Service: User management and profile operations
- Page Service: Document/page storage and retrieval with R2DBC reactive database
- Workspace Service: Workspace management and organization
- Collaboration Service: Real-time collaborative editing using Hocuspocus and Yjs
- UI: React-based frontend with Vite and TanStack Router
- Java 25 with Spring Boot 4.0.x
- Spring Data JPA for ORM
- Spring Data R2DBC for reactive database access
- Spring Security with JWT authentication
- gRPC for service-to-service communication
- Redis for caching and session management
- PostgreSQL as primary database
- Flyway for database migrations
- React 18+ with TypeScript
- Vite as build tool
- TanStack Router for client-side routing
- TanStack React Query for data fetching
- TipTap as rich text editor
- Tiptap Collaboration for collaborative editing
- ProseMirror document model
- Tailwind CSS for styling
- Radix UI for accessible components
- Hocuspocus for WebSocket-based real-time sync
- Yjs for CRDT-based conflict-free data sharing
The entry point for all HTTP requests, handling routing, load balancing, and request transformation.
Location: ./api-gateway
Technologies: Spring Cloud Gateway, Spring gRPC, Spring Boot 4.0
Key Features:
- HTTP request routing
- Protocol conversion (HTTP to gRPC)
- Load balancing
See: API Gateway README
Handles user authentication, token generation, and authorization checks.
Location: ./auth-service
Technologies: Spring Security, JWT, Spring Data JPA, PostgreSQL, Redis
Key Features:
- User registration and login
- JWT token generation and validation
- Session management
- Role-based access control
See: Auth Service README
Manages user profiles and user-related operations.
Location: ./user-service
Technologies: Spring Boot, Spring Data JPA, gRPC, PostgreSQL, Redis
Key Features:
- User profile management
- User metadata storage
- Service-to-service user lookups via gRPC
See: User Service README
Manages document/page storage, retrieval, and persistence with reactive database operations.
Location: ./page-service
Technologies: Spring WebFlux, R2DBC, Kafka, PostgreSQL, Flyway
Key Features:
- Reactive page storage and retrieval
- Page versioning and snapshots
- Event publishing for collaboration updates
- Database schema management with Flyway
See: Page Service README
Manages workspace organization, collaboration spaces, and access control.
Location: ./workspace-service
Technologies: Spring Boot, Spring Data JPA, gRPC, PostgreSQL, Redis
Key Features:
- Workspace creation and management
- Workspace member management
- Workspace-level permissions
Provides real-time collaborative editing capabilities using WebSockets.
Location: ./collaboration-service
Technologies: Bun, TypeScript, Hocuspocus, Yjs, Redis, Axios
Key Features:
- Real-time document synchronization
- Conflict resolution using CRDTs
- WebSocket connection management
- ProseMirror document format support
See: Collaboration Service README
React-based single-page application for end-user interaction.
Location: ./ui
Technologies: React 18+, TypeScript, Vite, TanStack Router, TanStack Query, TipTap
Key Features:
- Document editing interface
- Real-time collaboration UI
- Workspace and user management pages
- Responsive design with Tailwind CSS
See: UI README
- Java 25+ (for backend services)
- Node.js 18+ (for frontend)
- Bun 1.x+ (for collaboration service)
- PostgreSQL 14+
- Redis 6+
- Kafka (optional, for event streaming)
- Docker & Docker Compose (for containerized deployment)
-
Clone the repository
git clone <repository-url> cd collab-knowledge-workspace
-
Start dependencies (PostgreSQL, Redis, Kafka)
docker-compose up -d
-
Build and run backend services
# API Gateway cd api-gateway ./gradlew bootRun # Auth Service (in another terminal) cd auth-service ./gradlew bootRun # User Service cd user-service ./gradlew bootRun # Page Service cd page-service ./gradlew bootRun # Workspace Service cd workspace-service ./gradlew bootRun
-
Start collaboration service
cd collaboration-service bun run dev -
Start frontend
cd ui npm install npm run dev
Each service has its own configuration. See individual service READMEs for configuration details.
Common environment variables:
DATABASE_URL: PostgreSQL connection stringREDIS_URL: Redis connection stringJWT_SECRET: Secret for JWT token signingPORT: Service port (default varies by service)
# Build all services
./gradlew build # For Java services
# Build collaboration service
cd collaboration-service && bun build src/index.ts
# Build UI
cd ui && npm run build# Test Java services
./gradlew test
# Test UI
cd ui && npm testPage Service uses Flyway for migrations. Run migrations automatically on service startup or manually:
cd page-service
./gradlew flywayMigrateEach service includes a Dockerfile. Build and deploy with Docker Compose:
docker-compose up --buildSee individual service READMEs for specific deployment instructions.
HTTP request examples are available in ./manual-tests/ directory:
- Auth Service endpoints:
./manual-tests/auth-service/ - User Service endpoints:
./manual-tests/user-service/
The API Gateway routes requests to backend services. Default endpoints:
POST /auth/register- Register new userPOST /auth/login- User loginGET /users/{id}- Get user infoGET /pages/{id}- Get page contentPOST /pages- Create new pageGET /workspaces/{id}- Get workspace info
- Create a feature branch
- Make your changes
- Write tests
- Submit a pull request
collab-knowledge-workspace/
├── README.md (this file)
├── api-gateway/ # Spring Cloud Gateway
├── auth-service/ # Authentication service
├── collaboration-service/ # Real-time sync service (Bun)
├── page-service/ # Page persistence service
├── ui/ # React frontend
├── user-service/ # User management service
├── workspace-service/ # Workspace management service
└── manual-tests/ # HTTP request examples
[Add your license here]
For issues, questions, or contributions, please [add your contact/issue tracking info here].