firepit

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.

Features

• 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

Codebase Features

• 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

📋 Prerequisites

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

🚀 Quick Start

# 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)

📚 Documentation

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

🚀 Production Deployment

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.

⚠️ Known Limitations

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.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

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

🗂️ Project Structure

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

🛠️ Available Scripts

🔧 Configuration

Environment Variables

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.

First-Time Setup

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.

🐛 Troubleshooting

Common Issues

• "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.

🧪 Testing

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.)

📦 Deployment

Vercel (Recommended)

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

Self-Hosted

# Build the application
bun build

# Start production server
bun start

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

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

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

📄 License

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

🙏 Acknowledgments

Built with:

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

📧 Support

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