Version 1.0 - Production Ready

A modern, open-source chat platform inspired by Discord, built with Next.js 16, Appwrite, and TypeScript. Firepit includes real-time messaging, servers and channels, direct messages, roles and moderation, social features, and a growing parity roadmap for Discord-like workflows.

• Servers, channels, and categories - Discord-style server organization with grouped text channels and in-app category management
• Direct messages and group DMs - Private 1:1 and multi-user conversations
• Server invites and discovery - Invite links, public server listings, and direct join flows
• Roles and permissions - Per-server roles with channel overrides and moderation-aware access control
• Messaging parity basics - Replies, mentions, reactions, threads, pins, search, typing indicators, and file attachments
• Profiles, presence, and social - User profiles, statuses, friend requests, and blocking
• Notification controls parity - Scoped notification levels, quiet hours, mute durations, DM privacy, and bulk override management
• Moderation and auditability - Global and server moderation with audit log support
• Custom emoji support - Standard emoji picker plus uploaded custom emoji assets

• Real-time chat - Appwrite-backed realtime messaging with typing indicators and presence updates
• Replies, mentions, reactions, threads, and pins - Core message workflows across channels and DMs
• Direct messages and group DMs - Shared DM infrastructure for 1:1 and multi-user conversations
• Search and attachments - Message search plus image, file, video, audio, and document attachments
• Roles, permissions, categories, and moderation - Server roles, permission overrides, category management, invite management, bans, kicks, mutes, and audit logs
• Profiles and status - User profile enrichment, avatars, pronouns, bios, and custom status messages
• Friend system and blocking - Social graph controls for safer private messaging
• Notification settings and mute controls - Consistent override behavior across servers, channels, and DMs with server-enriched labels and quiet hours
• TypeScript - Full type safety across the entire codebase
• Next.js 16 - App Router with React Server Components
• Tailwind CSS - Modern, responsive UI styling
• shadcn/ui - Accessible UI primitives
• PWA ready - Installable web app support for mobile and desktop browsers
• Comprehensive tests - 1913 passing tests with broad API, hook, and integration coverage
• Production hardening - Error boundaries, rate limiting, security validation, and observability

Before you begin, ensure you have:

• Node.js 18+ or Bun 1.2+ (Bun 1.3+ preffered for perf. improvements) installed
• An Appwrite instance (cloud or self-hosted):
  • Cloud: appwrite.io (free tier available)
  • Self-hosted: Installation Guide
• Git for cloning the repository

# 1. Clone the repository
git clone https://github.com/your-org/firepit.git
cd firepit

# 2. Install dependencies
bun install

# 3. Set up environment variables
cp .env.local.example .env.local
nano .env.local  # Edit with your Appwrite credentials

# 4. Validate your configuration
bun run validate-env

# 5. Initialize the database
bun run setup

# 6. Start the development server
bun dev  # Uses Turbopack (~700x faster than Webpack)

Open http://localhost:3000 in your browser to see the application.

Development Commands:

• bun dev - Start with Turbopack (recommended, ~1.5s cold start)
• bun dev:webpack - Start with Webpack (fallback, ~12s cold start)
• bun build - Production build with Turbopack
• bun build:webpack - Production build with Webpack (fallback)

See the /docs folder for detailed guides:

• Deployment Guide - Production deployment instructions
• Documentation Index - Durable product and platform documentation map
• Product And Onboarding - Product shell, onboarding, discovery, and profile flows
• Chat And Realtime - Messaging, DMs, pins, threads, search, emoji, typing, status, and notifications
• Server Administration - Roles, invites, permissions, moderation, and audit logging
• Feature Flags - Flag behavior and rollout notes
• Platform Operations - Performance, monitoring, releases, and operations
• Roadmap - Discord parity roadmap and product priorities
• Roadmap Implementation Spec - Technical breakdown of roadmap workstreams
• Changelog - Version history and release notes

Firepit is production-ready with:

✅ Security Hardening

• Global error boundaries
• Rate limiting on uploads and API endpoints
• Secure session management
• Input validation and sanitization

✅ Performance Optimization

• 90%+ improvement in first load times (from 30+ seconds to 2-3 seconds)
• 85% faster First Contentful Paint (8s → 0.8-1.2s)
• 50% smaller bundle size (2.5MB → 800KB-1.2MB)
• Response compression (60-70% bandwidth reduction)
• Virtual scrolling for large lists
• Optimized bundle size with code splitting
• Partial Prerendering (PPR) for instant page loads
• Aggressive caching for repeat visits (~100ms)

✅ Monitoring & Observability

• New Relic APM integration
• Comprehensive error tracking
• Performance metrics
• Audit logging

✅ Testing & Quality

• 1913 passing tests
• Comprehensive test coverage
• Automated CI/CD pipeline
• Strict ESLint configuration

See DEPLOYMENT.md for detailed production deployment instructions.

Firepit still has meaningful Discord parity gaps in a few areas:

• Richer community/server organization beyond categories, such as server templates, onboarding screens, and announcement-style surfaces, is still in progress
• Notification-center, unread-management, and digest-style attention flows are still incomplete
• Voice/video calls and screen sharing are not implemented
• Bots, slash commands, and webhooks are not implemented
• Native mobile apps are not implemented, though PWA support exists

See ROADMAP.md for the complete feature roadmap.

We welcome contributions! See CONTRIBUTING.md for:

• Development workflow
• Code style guidelines
• Testing requirements
• Pull request process
• Issue reporting templates

firepit/
├── src/
│   ├── app/              # Next.js app router pages
│   ├── components/       # React components
│   ├── lib/              # Utility functions and Appwrite integration
│   └── __tests__/        # Vitest test suites
├── scripts/
│   ├── setup-appwrite.ts    # Database initialization script
│   └── validate-env.ts      # Environment validation script
├── public/               # Static assets
├── DEPLOYMENT.md         # Deployment documentation
└── .env.local.example    # Environment variable template

The application requires several environment variables. Copy .env.local.example to .env.local and configure:

• APPWRITE_ENDPOINT - Your Appwrite API endpoint
• APPWRITE_PROJECT_ID - Your Appwrite project ID
• APPWRITE_API_KEY - Server-side API key with full permissions

For a complete list and detailed explanations, see DEPLOYMENT.md.

1. Create an Appwrite account and project at appwrite.io
2. Generate an API key with required scopes (see DEPLOYMENT.md)
3. Configure environment variables in .env.local
4. Run validation: bun run validate-env
5. Initialize database: bun run setup
6. Start the app: bun dev
7. Create your account in the UI
8. Make yourself admin by setting APPWRITE_ADMIN_USER_IDS in .env.local

For detailed instructions, see DEPLOYMENT.md.

• "Appwrite endpoint not configured" - Check your .env.local file exists and has the correct values
• "Project not found" - Verify your APPWRITE_PROJECT_ID matches your Appwrite Console
• "Missing scope" errors - Regenerate your API key with all required permissions
• Setup script fails - Ensure your API key has databases, collections, attributes, and indexes permissions
• Setup script reports an attribute limit on notification_settings - Update to the latest code and rerun bun run setup; unread persistence now uses a dedicated thread_reads collection instead of adding another notification-settings attribute

For more solutions, see DEPLOYMENT.md - Troubleshooting.

This project maintains a comprehensive test suite with 100% pass rate:

# Run all tests
bun run test

# Run tests with coverage report
bun run test:coverage

# Run tests in watch mode (during development)
bun run test --watch

Current test coverage: 40.18% statements (growing)

• 1913 tests passing across 157 test suites
• Comprehensive API route testing (44 new tests for invite system)
• Focus on security-critical modules (auth, roles, moderation), and modules critical for function (API routes, hooks, utility files, etc.)

1. Push your code to GitHub
2. Import project in Vercel
3. Add environment variables from .env.local
4. Deploy!

# Build the application
bun build

# Start production server
bun start

For production deployment with Nginx, Docker, or other platforms, see DEPLOYMENT.md - Production Deployment.

We welcome contributions! Please see CONTRIBUTING.md for:

• Development workflow
• Code style guidelines
• Testing requirements
• Pull request process
• Issue reporting templates

firepit, a realtime chat app Copyright (C) 2026 August (acarlson33)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Licensed under the GNU General Public License (GPL) v3. You can find the License here: License

Built with:

• Next.js
• Appwrite
• TailwindCSS
• shadcn/ui
• Vitest

• Documentation: DEPLOYMENT.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions