MeshMind Study Hub Backend API

A privacy-first, group-focused study platform backend built with FastAPI, PostgreSQL, and modern web technologies.

🚀 Features

• User Authentication & Authorization: JWT-based auth with refresh tokens
• Group Management: Create and manage study groups with different visibility levels
• Real-time Messaging: WebSocket support for group chat
• AI-Powered Quiz Generation: Generate quizzes using OpenAI/Anthropic APIs
• Note Sharing: Collaborative note-taking with version control
• Action Items: Track study tasks and assignments
• File Storage: S3-compatible file uploads for attachments
• RESTful API: Complete REST API with OpenAPI documentation

🛠️ Tech Stack

• Framework: FastAPI (Python 3.11+)
• Database: PostgreSQL with SQLAlchemy ORM
• Authentication: JWT tokens with bcrypt password hashing
• Real-time: WebSockets for live communication
• File Storage: S3-compatible storage (AWS S3, MinIO)
• AI Integration: OpenAI GPT, Anthropic Claude
• Containerization: Docker support
• Database Migrations: Alembic

📋 Prerequisites

• Python 3.11+
• PostgreSQL 12+
• Redis (optional, for caching)
• Docker (optional)

🚀 Quick Start

1. Clone the Repository

git clone <your-repo-url>
cd study-hub-backend

2. Environment Setup

# Copy environment template
cp env.example .env

# Edit .env with your configuration
nano .env

3. Database Setup

# Create PostgreSQL database
createdb studyhub

# Create database user (optional)
sudo -u postgres psql
CREATE USER studyhub_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE studyhub TO studyhub_user;
GRANT ALL PRIVILEGES ON SCHEMA public TO studyhub_user;
GRANT CREATE ON SCHEMA public TO studyhub_user;
ALTER SCHEMA public OWNER TO studyhub_user;
\q

4. Install Dependencies

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

5. Run Database Migrations

# Generate initial migration
alembic revision --autogenerate -m "Initial migration"

# Apply migrations
alembic upgrade head

6. Start the Server

# Development mode
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production mode
uvicorn app.main:app --host 0.0.0.0 --port 8000

📖 API Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🔧 Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql+asyncpg://username:password@localhost:5432/studyhub
SECRET_KEY	JWT secret key	your-super-secret-jwt-key-change-this-in-production
ALLOWED_ORIGINS	CORS allowed origins	http://localhost:3000,http://localhost:5173
DEBUG	Debug mode	true
ENVIRONMENT	Environment type	development

Required Services

• PostgreSQL: Primary database
• Redis: Optional, for caching and background tasks
• S3/MinIO: File storage (optional)

🐳 Docker Deployment

Build and Run

# Build the image
docker build -t study-hub-backend .

# Run with environment file
docker run -p 8000:8000 --env-file .env study-hub-backend

Docker Compose

version: '3.8'
services:
  backend:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://postgres:password@db:5432/studyhub
    depends_on:
      - db
      - redis

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: studyhub
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  postgres_data:

🔐 Security Features

• JWT-based authentication with refresh tokens
• Password hashing with bcrypt
• CORS protection
• Input validation with Pydantic
• SQL injection protection with SQLAlchemy ORM
• Environment-based configuration

📁 Project Structure

backend/
├── app/
│   ├── api/v1/endpoints/     # API endpoints
│   ├── core/                 # Core configuration
│   ├── models/               # Database models
│   ├── schemas/              # Pydantic schemas
│   ├── services/             # Business logic
│   └── websocket/            # WebSocket handlers
├── alembic/                  # Database migrations
├── tests/                    # Test files
├── Dockerfile               # Docker configuration
├── requirements.txt         # Python dependencies
└── alembic.ini             # Alembic configuration

🧪 Testing

# Run tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_auth.py

📝 API Endpoints

Authentication

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User login
• POST /api/v1/auth/refresh - Refresh token

Groups

• GET /api/v1/groups/ - List user groups
• POST /api/v1/groups/ - Create group
• GET /api/v1/groups/{id} - Get group details
• PUT /api/v1/groups/{id} - Update group

Messages

• POST /api/v1/messages/ - Send message
• GET /api/v1/messages/group/{id} - Get group messages
• POST /api/v1/messages/upload-audio - Upload audio message

Quizzes

• POST /api/v1/quizzes/generate - Generate AI quiz
• POST /api/v1/quizzes/ - Create manual quiz
• GET /api/v1/quizzes/group/{id} - Get group quizzes

Notes

• POST /api/v1/notes/ - Create note
• GET /api/v1/notes/group/{id} - Get group notes
• PUT /api/v1/notes/{id} - Update note

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is proprietary software. All rights reserved.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team

🔄 Changelog

v1.0.0

• Initial release
• User authentication and authorization
• Group management
• Real-time messaging
• AI-powered quiz generation
• Note sharing and collaboration
• Action items tracking
• File storage integration

---

Study Hub - Empowering collaborative learning through technology.