SyncStream

Full-stack real-time watch party platform with FastAPI, WebSockets, and Next.js.

Tech Stack

• Backend: FastAPI, Uvicorn, SQLite, SQLAlchemy ORM, Passlib (Bcrypt), Python-Jose (JWT)
• Frontend: Next.js (App Router), TypeScript, Tailwind CSS, Three.js, Axios, Lucide Icons

---

Project Structure

syncstream/
├── frontend/                     # Next.js Frontend Application
│   ├── .env.local                # Frontend env configuration
│   ├── src/
│   │   ├── app/
│   │   │   ├── globals.css       # Tailwind CSS styles & dark theme
│   │   │   ├── layout.tsx        # Root layout with ThreeBackground & AuthProvider
│   │   │   ├── page.tsx          # Lobby Dashboard (3D Create & Join cards)
│   │   │   ├── login/
│   │   │   │   └── page.tsx      # OAuth2 Sign-In page (3D Card)
│   │   │   ├── register/
│   │   │   │   └── page.tsx      # User Registration page (3D Card)
│   │   │   └── watch/
│   │   │       └── [code]/
│   │   │           └── page.tsx  # Synchronized Watch Room page
│   │   ├── components/
│   │   │   ├── Card3D.tsx        # Interactive 3D tilt perspective wrapper
│   │   │   ├── ChatDrawer.tsx    # Slide-out real-time chat drawer & message feed
│   │   │   ├── ThreeBackground.tsx # Ambient Three.js particle & wireframe canvas
│   │   │   ├── VideoPlayer.tsx   # HTML5 16:9 video player with ambient glow
│   │   │   └── VideoToastOverlay.tsx # In-video floating notification toasts
│   │   ├── context/
│   │   │   └── AuthContext.tsx   # React Auth context & provider (login, register, session)
│   │   ├── hooks/
│   │   │   └── useWatchPartySocket.ts # Real-time WebSocket sync hook with echo-loop prevention
│   │   ├── lib/
│   │   │   ├── api.ts            # Axios instance with auth interceptors
│   │   │   └── utils.ts          # Tailwind cn utility function
│   │   └── types/
│   │       └── toast.ts          # VideoToast interface definition
│   └── package.json
│
├── auth.py                       # Password hashing & JWT token functions
├── config.py                     # Backend settings with Pydantic-Settings
├── connection_manager.py         # Real-time WebSocket connection broker
├── database.py                   # SQLite engine & session dependency
├── deps.py                       # OAuth2 bearer & get_current_user dependencies
├── main.py                       # FastAPI entrypoint with CORS & router mounting
├── models.py                     # SQLAlchemy database models (User, Room)
├── requirements.txt              # Backend dependencies
├── routers/
│   ├── __init__.py
│   ├── auth.py                   # Auth routes (/api/auth)
│   ├── rooms.py                  # Room management routes (/api/rooms)
│   └── ws.py                     # WebSocket sync route (/ws/{room_code}/{username})
├── schemas.py                    # Pydantic schemas (User, Token, Room)
└── tests/
    ├── conftest.py               # Shared pytest fixtures with test isolation
    ├── test_auth.py              # Auth integration and unit tests
    ├── test_connection_manager.py# WebSocket room pool & broadcast tests
    ├── test_rooms.py             # Room models and schemas tests
    └── test_rooms_api_ws.py      # Room REST and WebSocket integration tests

---

Getting Started

1. Backend Setup & Running

# In the repository root:
source venv/bin/activate
pip install -r requirements.txt

# Run the development server:
python main.py
# or
uvicorn main:app --reload --port 8001

• API Docs: http://localhost:8001/docs
• Run tests: venv/bin/pytest -v

2. Frontend Setup & Running

# In a new terminal:
cd frontend
npm install
npm run dev

• Frontend Web App: http://localhost:3000
• Production Build Check: npm run build

---

API Endpoints

Method	Endpoint	Description	Auth Required
GET	/	Health check & API metadata	No
POST	/api/auth/register	Register a new user	No
POST	/api/auth/login	Login and receive JWT access token	No
GET	/api/auth/me	Retrieve profile of authenticated user	Bearer Token
POST	/api/rooms	Create a new room with a unique SYNC-XXXX code	Bearer Token
GET	/api/rooms/{code}	Retrieve room details by room code	Bearer Token
WS	/ws/{room_code}/{username}	Real-time playback & chat WebSocket connection	No