🎯 Discuss Lite

A lightweight, modern, self-hosted forum platform for small communities

Minimal • Fast • Extensible • Self-hosted

🚀 Quick Start • 📚 Documentation • 🤝 Contributing

---

✨ Features

🎭 User Experience

• 🔐 Secure Authentication - Session-based auth with HTTPOnly cookies
• 📱 Responsive Design - Mobile-first with dark/light theme toggle
• ⚡ Fast & Lightweight - Optimized for performance and minimal resource usage
• 🎨 Modern UI - Clean, accessible interface inspired by GitHub Discussions

🛠️ Forum Features

• 📂 Organized Categories - Hierarchical forum structure
• 💬 Rich Discussions - Threads, replies, and nested conversations
• ✍️ Markdown Support - Full markdown rendering with syntax highlighting
• 🔍 Powerful Search - Full-text search across all content
• 📎 File Attachments - Image uploads with validation
• 🔔 Notifications - In-app notifications for mentions and replies

🛡️ Moderation & Admin

• 👥 Role-based Access - Admin, moderator, and user roles
• 🚩 Content Moderation - Flag inappropriate content
• 🗑️ Soft Delete - Maintain data integrity with soft deletion
• 📊 Admin Dashboard - Comprehensive moderation tools
• 📈 Analytics - View moderation logs and statistics

🔧 Developer Experience

• 📖 OpenAPI Documentation - Interactive API docs at /docs
• 🐳 Docker Ready - One-command deployment
• 🧪 Comprehensive Testing - Backend and frontend test suites
• 🔄 CI/CD Pipeline - Automated testing and deployment
• 📝 Type Safety - Full TypeScript and Pydantic validation

🏗️ Tech Stack

Component	Technology	Description
Frontend	Next.js + TypeScript + Tailwind CSS	Modern React framework with type safety
Backend	FastAPI + Python + Pydantic	High-performance async API framework
Database	PostgreSQL + SQLAlchemy	Robust relational database with ORM
Cache	Redis	Optional caching and session storage
Deployment	Docker + docker-compose	Containerized deployment
Testing	PyTest + React Testing Library	Comprehensive test coverage
Code Quality	Black + isort + ESLint + Prettier	Automated code formatting and linting

🚀 Quick Start

Get Discuss Lite running in under 5 minutes!

📋 Prerequisites

• 🐳 Docker and docker-compose
• 🐙 Git

⚡ Local Development Setup

# 1. Clone the repository
git clone https://github.com/code-xon/discuss-lite.git
cd discuss-lite

# 2. Set up environment
cp .env.example .env
# Edit .env with your settings (optional - defaults work for development)

# 3. Launch the application
docker-compose up --build

# 4. Set up the database (in another terminal)
docker-compose exec backend alembic upgrade head
docker-compose exec backend python scripts/seed_data.py

🌐 Access Your Forum

Once running, access these URLs:

Service	URL	Description
🎨 Frontend	http://localhost:3000	Main forum interface
🔧 API	http://localhost:8000	REST API endpoints
📚 API Docs	http://localhost:8000/docs	Interactive OpenAPI documentation
🗄️ Database	localhost:5432	PostgreSQL (if needed)
⚡ Cache	localhost:6379	Redis (if needed)

🎯 First Steps

1. Create Account - Visit http://localhost:3000/auth and sign up
2. Explore Categories - Browse the seeded forum categories
3. Create Thread - Start your first discussion
4. Customize - Modify settings in the admin panel (/admin)

💡 Default Admin Account: admin / admin123 (created by seed script)

⚙️ Environment Configuration

Create a .env file based on .env.example:

cp .env.example .env

Key Configuration Options:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql+asyncpg://discuss:discuss_password@postgres:5432/discuss_lite
REDIS_URL	Redis connection string	redis://redis:6379
SECRET_KEY	JWT and session signing key	Auto-generated
APP_ENV	Environment (development/production)	development
FRONTEND_URL	Frontend application URL	http://localhost:3000
BACKEND_URL	Backend API URL	http://localhost:8000

📚 API Documentation

🎯 API Design Principles

• RESTful - Standard HTTP methods and resource-based URLs
• Consistent Responses - Standardized JSON response format
• OpenAPI Compliant - Full API specification available
• Versioned - API versioning with /api/v1/ prefix

📋 Response Format

All API responses follow this consistent structure:

{
  "success": true,
  "data": {
    // Response data here
  },
  "error": null
}

Error Response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

🔗 Core API Endpoints

🔐 Authentication

POST /api/auth/signup       # User registration
POST /api/auth/login        # User authentication
POST /api/auth/logout       # Session termination

📂 Categories & Threads

GET    /api/categories                    # List all categories
POST   /api/categories                    # Create category (admin)
GET    /api/categories/{id}/threads       # Get threads in category
GET    /api/threads/{id}                  # Get thread details
POST   /api/threads                       # Create new thread
PUT    /api/threads/{id}                  # Update thread
DELETE /api/threads/{id}                  # Delete thread

💬 Replies & Content

POST   /api/threads/{id}/replies          # Create reply
PUT    /api/replies/{id}                  # Update reply
DELETE /api/replies/{id}                  # Delete reply
POST   /api/uploads                       # Upload files
GET    /api/search?q=query                # Search content

🚩 Moderation

POST   /api/flags                         # Flag content
GET    /api/flags                         # View moderation queue (admin)

🎮 Interactive API Explorer

Visit http://localhost:8000/docs for the interactive OpenAPI documentation where you can:

• 📖 Explore all endpoints with detailed descriptions
• 🧪 Test API calls directly in your browser
• 📋 View request/response schemas
• 🔐 Authenticate and test protected endpoints

🧪 Testing

Ensure code quality with comprehensive test suites:

🔧 Backend Testing

# Run all backend tests
docker-compose exec backend pytest

# Run with coverage report
docker-compose exec backend pytest --cov=app --cov-report=html

# Run specific test file
docker-compose exec backend pytest app/tests/test_api.py

🎨 Frontend Testing

# Run frontend tests
docker-compose exec frontend npm test

# Run tests once (CI mode)
docker-compose exec frontend npm test -- --watchAll=false --coverage

🚀 Deployment

🐳 Production Deployment (Recommended)

1. Prepare production environment:

   # Create production docker-compose file
   cp infra/docker-compose.yml docker-compose.prod.yml
   # Edit for production settings (ports, environment variables)

2. Deploy with Docker:

   # Build and run in background
   docker-compose -f docker-compose.prod.yml up --build -d
   
   # Run database migrations
   docker-compose -f docker-compose.prod.yml exec backend alembic upgrade head
   
   # Seed initial data (optional)
   docker-compose -f docker-compose.prod.yml exec backend python scripts/seed_data.py

🖥️ Manual Deployment

For systems without Docker:

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 8000

Frontend Setup

cd frontend
npm install
npm run build
npm start

💻 Development

🎯 Code Quality Tools

Language	Linting	Formatting	Testing
Python	flake8	Black + isort	PyTest
TypeScript	ESLint	Prettier	React Testing Library

🗄️ Database Management

# Create new migration
docker-compose exec backend alembic revision --autogenerate -m "Add new feature"

# Apply migrations
docker-compose exec backend alembic upgrade head

# Rollback migration
docker-compose exec backend alembic downgrade -1

# View migration history
docker-compose exec backend alembic history

📁 Project Architecture

discuss-lite/
├── 📁 backend/                 # FastAPI Backend
│   ├── 📁 app/
│   │   ├── 📁 api/v1/endpoints/  # API route handlers
│   │   ├── 📁 db/               # Database models & connections
│   │   ├── 📁 utils/            # Helper utilities
│   │   ├── 📄 main.py           # FastAPI application
│   │   └── 📄 config.py         # Environment configuration
│   ├── 📄 requirements.txt      # Python dependencies
│   └── 📄 Dockerfile           # Backend container config
├── 📁 frontend/                # Next.js Frontend
│   ├── 📁 src/pages/           # Next.js pages & components
│   ├── 📁 src/styles/          # Global styles
│   ├── 📄 package.json         # Node dependencies
│   └── 📄 Dockerfile           # Frontend container config
├── 📁 infra/                   # Infrastructure
│   └── 📄 docker-compose.yml   # Local development setup
├── 📁 scripts/                 # Utility scripts
│   └── 📄 seed_data.py         # Database seeding
├── 📁 .github/workflows/       # CI/CD pipelines
└── 📄 README.md               # This file!

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 Quick Setup for Contributors

# Fork and clone
git clone https://github.com/your-username/discuss-lite.git
cd discuss-lite

# Set up development environment
cp .env.example .env
docker-compose up --build

# Run tests before submitting
docker-compose exec backend pytest
docker-compose exec frontend npm test -- --watchAll=false

📋 Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Test thoroughly:
   • Backend: docker-compose exec backend pytest
   • Frontend: docker-compose exec frontend npm test
   • Manual testing in browser
5. Commit with clear messages: git commit -m "feat: Add amazing feature"
6. Push to your branch: git push origin feature/amazing-feature
7. Create a Pull Request with detailed description

🎯 Contribution Guidelines

• 📝 Code Style: Follow existing patterns and run formatters
• 🧪 Testing: Add tests for new features
• 📚 Documentation: Update docs for API changes
• 🔄 Compatibility: Ensure backward compatibility
• 🎨 UI/UX: Maintain consistent design patterns

🐛 Found a Bug?

1. Check existing Issues
2. Create a new issue with:
   • Clear title and description
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details

💡 Have a Feature Request?

We'd love to hear your ideas! Create an Issue with:

• Feature description
• Use case and benefits
• Implementation ideas (optional)

📄 License

MIT License - see LICENSE file for details.

Copyright (c) 2025 Ramkrishna

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

📞 Contact & Support

• 👨‍💻 Author: Ramkrishna
• 📧 Email: ramkrishna@code-xon.fun
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🙏 Acknowledgments

• FastAPI - The modern Python web framework
• Next.js - The React framework for production
• PostgreSQL - The world's most advanced open source database
• Tailwind CSS - A utility-first CSS framework
• Docker - Containerization platform

---

Made with ❤️ for the open source community

⭐ Star us on GitHub • 📖 Read the docs • 🚀 Quick start