Spaces

A modern, real-time collaborative document editor with AI superpowers.
Built with Next.js 16, React 19, and Liveblocks.

Features • Demo • Tech Stack • Getting Started • Architecture • Contributing

✨ Features

🔄 Real-time Collaboration

Live cursors — See where others are editing in real-time
Presence awareness — Know who's currently viewing the document
Instant sync — Changes appear immediately for all collaborators
Conflict-free — Powered by Yjs CRDT for seamless merging

📝 Rich Text Editor

Block-based editing — Notion-style blocks with BlockNote
Slash commands — Quick formatting with / menu
Markdown support — Write in markdown, see it rendered
Dark/Light mode — Easy on the eyes, any time of day

🤖 AI Integration

Choose from 5 powerful AI models:

Model	Provider	Best For
GPT-4o	OpenAI	General tasks, reasoning
Claude 3.5 Sonnet	Anthropic	Long documents, analysis
Gemini 1.5 Pro	Google	Multi-modal, large context
Mistral Large	Mistral	European data compliance
LLaMA 3.1 405B	Fireworks	Open-source, self-hostable

AI Features:

🌐 Document Translation — Translate to 10 languages
💬 Chat with Document — Ask questions about your content
⚡ Streaming responses — See AI responses in real-time

👥 User Management

Role-based access — Owner and Editor roles
Easy sharing — Invite collaborators via email
User management — View and remove document access

🌍 Supported Languages

English, French, Spanish, German, Italian, Portuguese, Chinese, Russian, Hindi, Japanese

🎬 Demo

Add screenshots or GIFs of your application here

┌─────────────────────────────────────────────────────────────┐
│  🟣 Spaces                              [Avatar] [Avatar]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  📄 My Documents          │  Document Title        [Update] │
│  ├── Project Notes        │  ─────────────────────────────  │
│  ├── Meeting Summary      │                                 │
│  └── Ideas                │  Start typing here...           │
│                           │                                 │
│  📤 Shared with me        │  👆 Cursor (You)                │
│  └── Team Roadmap         │        👆 Cursor (Jane)         │
│                           │                                 │
│  [+ New Document]         │  [Translate] [Chat] [🌙]       │
│                           │                                 │
└─────────────────────────────────────────────────────────────┘

🛠 Tech Stack

Core Framework

Technology	Version	Purpose
Next.js	16.1.1	React framework with App Router
React	19.0.0	UI library
TypeScript	5.6.2	Type safety

Real-time Collaboration

Technology	Version	Purpose
Liveblocks	3.12.1	Real-time infrastructure
Yjs	13.6.19	CRDT for conflict-free sync
BlockNote	0.45.0	Rich text editor

AI & Backend

Technology	Version	Purpose
Vercel AI SDK	6.0.3	AI streaming & providers
Firebase	12.7.0	Database & storage
Firebase Admin	13.0.1	Server auth & Firestore

UI & Styling

Technology	Version	Purpose
Tailwind CSS	4.0.9	Utility-first CSS
Radix UI	Latest	Accessible primitives
Framer Motion	12.4.7	Animations
Lucide	0.562.0	Icons
Sonner	2.0.1	Toast notifications

🚀 Getting Started

Prerequisites

Node.js 20.9 or later (required by Next.js 16.1.1)
npm 9.0 or later (or pnpm/yarn)
A Liveblocks account (real-time)
A Firebase project (database)
At least one AI provider API key

Installation

Clone the repository

git clone https://github.com/yourusername/spacesapp.git
cd spacesapp

Install dependencies

npm install

Set up environment variables

cp .env.example .env.local

Configure your environment (see Environment Variables)
Run the development server

npm run dev

Open http://localhost:3000

🔐 Environment Variables

Create a .env.local file with the following variables:

Real-time Collaboration (Required)

# Liveblocks - https://liveblocks.io/docs/get-started
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY=pk_...
LIVEBLOCKS_PRIVATE_KEY=sk_...

Firebase (Required)

# Client-side (from Firebase Console > Project Settings)
NEXT_PUBLIC_FIREBASE_APIKEY=...
NEXT_PUBLIC_FIREBASE_AUTHDOMAIN=...
NEXT_PUBLIC_FIREBASE_PROJECTID=...
NEXT_PUBLIC_FIREBASE_STORAGEBUCKET=...
NEXT_PUBLIC_FIREBASE_MESSAGINGSENDERID=...
NEXT_PUBLIC_FIREBASE_APPID=...
NEXT_PUBLIC_FIREBASE_MEASUREMENTID=...  # Optional

# Server-side (from Firebase Console > Service Accounts > Generate Key)
FIREBASE_TYPE=service_account
FIREBASE_PROJECT_ID=...
FIREBASE_PRIVATE_KEY_ID=...
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
FIREBASE_CLIENT_EMAIL=...
FIREBASE_CLIENT_ID=...
FIREBASE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
FIREBASE_TOKEN_URI=https://oauth2.googleapis.com/token
FIREBASE_AUTH_PROVIDER_X509_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
FIREBASE_CLIENT_CERTS_URL=...

AI Providers (At least one required)

# OpenAI - https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-...

# Anthropic - https://console.anthropic.com/
ANTHROPIC_API_KEY=sk-ant-...

# Google AI - https://makersuite.google.com/app/apikey
GOOGLE_GENERATIVE_AI_API_KEY=...

# Mistral - https://console.mistral.ai/
MISTRAL_API_KEY=...

# Fireworks (for LLaMA) - https://fireworks.ai/
FIREWORKS_API_KEY=...

Optional (Debug)

# Logs room ownership self-heal decisions on the server (dev only)
ROOM_OWNERSHIP_DEBUG=1

📁 Project Structure

src/
├── app/                      # Next.js App Router
│   ├── api/                  # API routes
│   │   └── auth-endpoint/    # Liveblocks authentication
│   ├── doc/[id]/             # Document pages
│   │   ├── page.tsx          # Document view
│   │   ├── layout.tsx        # Room provider wrapper
│   │   ├── loading.tsx       # Loading state
│   │   └── error.tsx         # Error boundary
│   ├── layout.tsx            # Root layout
│   └── page.tsx              # Home page
│
├── components/               # React components
│   ├── ui/                   # Shadcn UI primitives
│   ├── AIDialog.tsx          # Shared AI dialog base
│   ├── AIModelSelect.tsx     # AI model dropdown
│   ├── Avatars.tsx           # User presence avatars
│   ├── ChatToDocument.tsx    # AI Q&A feature
│   ├── Document.tsx          # Main document component
│   ├── Editor.tsx            # BlockNote editor wrapper
│   ├── LiveCursorProvider.tsx # Cursor tracking
│   ├── TranslateDocument.tsx # AI translation feature
│   └── ...
│
├── hooks/                    # Custom React hooks
│   ├── use-document-title.ts # Document title management
│   ├── use-owner.ts          # Ownership check
│   ├── use-room-id.ts        # URL room ID extraction
│   ├── use-room-users.ts     # Room users query
│   ├── use-streaming-request.ts # AI streaming handler
│   └── ...
│
├── lib/                      # Utilities & server actions
│   ├── documentActions.ts    # Document CRUD operations
│   ├── generateActions.ts    # AI generation actions
│   ├── firebase-session.ts   # Server session + auth helpers (cookie -> user)
│   ├── room-ownership.ts     # Targeted self-heal for corrupted room ownership
│   ├── migrations.ts         # Best-effort legacy room migrations
│   ├── action-utils.ts       # Consistent server-action responses
│   ├── document-utils.ts     # Document helpers
│   └── ...
│
├── firebase/                 # Firebase configuration
│   ├── firebaseConfig.ts     # Client SDK setup
│   └── firebaseAdmin.ts      # Admin SDK setup
│
├── constants/                # App constants
│   └── index.ts              # AI models, languages, prompts
│
└── types/                    # TypeScript definitions
    └── index.ts              # Shared types

🏗 Architecture

Data Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────▶│  Liveblocks │────▶│   Client    │
│  (Editor)   │◀────│   (Yjs)     │◀────│  (Editor)   │
└─────────────┘     └─────────────┘     └─────────────┘
       │                                       │
       ▼                                       ▼
┌─────────────────────────────────────────────────────┐
│                    Firebase                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │Documents │  │  Users   │  │ Rooms (per user) │  │
│  └──────────┘  └──────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────┘

Authentication Flow

User ──▶ Firebase Auth ──▶ ID Token ──▶ /api/auth/session (HttpOnly cookie)
                                           │
                                           ▼
                                 Liveblocks Auth Endpoint
                                           │
                                           ▼
                                Firebase Room Access Check
                                           │
                                           ▼
                                Liveblocks Session Token

Firestore Data Model

documents/
└── {documentId}/
    ├── title: string
    ├── createdAt: timestamp
    └── updatedAt: timestamp

users/
└── {uid}/
    └── rooms/
        └── {documentId}/
            ├── roomId: string
            ├── userId: string
            ├── role: "owner" | "editor"
            └── createdAt: timestamp

📜 Available Scripts

Command	Description
`npm run dev`	Start development server with hot reload
`npm run build`	Build for production
`npm run start`	Start production server
`npm run lint`	Run ESLint for code quality

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Workflow

Fork the repository
Clone your fork locally
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test thoroughly
Commit with a descriptive message: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a Pull Request

Code Style

We use TypeScript strict mode
Follow the existing code patterns
Use functional components with hooks
Prefer Server Components where possible
Write descriptive variable names (e.g., isLoading, hasError)

Commit Messages

Follow conventional commits:

feat: add document export feature
fix: resolve cursor sync delay
docs: update README with new env vars
refactor: simplify auth flow

🐛 Troubleshooting

Common Issues

Hydration mismatch errors

This can happen with components using browser APIs. Wrap them in ClientOnly:

import ClientOnly from "@/components/ClientOnly";

<ClientOnly fallback={<Skeleton />}>
  <BrowserOnlyComponent />
</ClientOnly>;

Liveblocks authentication fails

Check that LIVEBLOCKS_PRIVATE_KEY is set correctly
Verify you are signed in (Header should show your avatar + “Sign Out”)
Check the auth endpoint logs at /api/auth-endpoint

Firebase permission denied

Deploy the security rules from the project root:

Copy firestore.rules to Firebase Console → Firestore → Rules
Copy storage.rules to Firebase Console → Storage → Rules

Or use Firebase CLI:

firebase deploy --only firestore:rules,storage

See firestore.rules and storage.rules for the full rule definitions.

Migration warns about missing index (FAILED_PRECONDITION)

On first sign-in, the app runs a best-effort migration (migrateUserRoomsToUid) that may query a collection group index on rooms.userEmail.

If you see:

Skipping collectionGroup userEmail migration (likely missing index): FAILED_PRECONDITION

You can either ignore it (the app still works), or create the index:

Collection: rooms (collection group)
Fields: userEmail (Ascending)

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE.md for the full license text.

Note: AGPL includes network-use/source-availability requirements when you run modified versions as a service. If you're unsure how this impacts your use case, please review the license terms.

🙏 Acknowledgments

BlockNote — Amazing open-source editor
Liveblocks — Real-time infrastructure
Vercel AI SDK — Unified AI interface
Shadcn UI — Beautiful UI components

Made with ❤️ by the Spaces team

⭐ Star us on GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
firestore.rules		firestore.rules
liveblocks.config.ts		liveblocks.config.ts
next.config.mjs		next.config.mjs
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
storage.rules		storage.rules
tsconfig.json		tsconfig.json

License

brown2020/spacesappai

Folders and files

Latest commit

History

Repository files navigation