Skip to content

README.md

Latest commit

 

History

History
267 lines (202 loc) · 6.51 KB

README.md

File metadata and controls

267 lines (202 loc) · 6.51 KB

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:

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