Local Setup

This guide will walk you through setting up Syllabi on your local machine for development.

Step 1: Clone the Repository

git clone https://github.com/Achu-shankar/Syllabi.git
cd Syllabi

The repository structure:

syllabi/
├── frontend/          # Next.js application
├── backend/           # Python FastAPI service (optional)
├── README.md
└── .env.example

Step 2: Setup Frontend

Install Dependencies

cd frontend
npm install

This will install all required packages including:

• Next.js 15
• Vercel AI SDK v5
• Supabase client
• TailwindCSS
• And more...

Configure Environment Variables

Create a .env.local file in the frontend/ directory:

cp .env.example .env.local

Edit .env.local with your credentials:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here
 
# OpenAI Configuration
OPENAI_API_KEY=sk-your_openai_key_here
 
# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
 
# Optional: Analytics
NEXT_PUBLIC_POSTHOG_KEY=your_posthog_key
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com
 
# Optional: Integrations (add when needed)
# DISCORD_CLIENT_ID=
# DISCORD_CLIENT_SECRET=
# DISCORD_BOT_TOKEN=
# SLACK_CLIENT_ID=
# SLACK_CLIENT_SECRET=

Setup Database

1. Create Supabase Project

1. Go to supabase.com (opens in a new tab)
2. Click "New Project"
3. Fill in project details
4. Wait for project to be ready (~2 minutes)

2. Run Database Schema

You have three options to set up your database:

Option 1: Quick Setup with Schema File (Recommended)

This is the easiest way for new users:

1. Navigate to Supabase Dashboard → SQL Editor
2. Open the file frontend/supabase/schema.sql from the repository
3. Copy the entire contents of the schema file
4. Paste into the SQL Editor
5. Click "Run" to execute

This single file creates all tables, indexes, RLS policies, and functions in one go!

Option 2: Using Supabase CLI

If you have the Supabase CLI installed:

cd frontend
supabase link --project-ref your-project-ref
supabase db push

Option 3: Individual Migration Files

For development or to understand incremental changes:

# Navigate to migrations folder
cd frontend/supabase/migrations
 
# Copy each SQL file content to Supabase SQL Editor one by one
# Files are numbered chronologically (20240801000000_*.sql)

Key tables created:

• chatbots - Chatbot configurations
• chat_sessions - User conversations
• chat_messages - Individual messages
• chatbot_content_sources - Uploaded documents
• document_chunks - Vectorized content
• chatbot_skills - Custom actions
• integrations - External integrations

3. Enable Row Level Security (RLS)

In Supabase Dashboard → Authentication → Policies:

• Enable RLS on all tables
• Apply provided policy templates from migrations

4. Setup Storage Buckets

In Supabase Dashboard → Storage:

1. Create bucket: chat-files (for user uploads)
2. Create bucket: chatbot-assets (for logos/images)
3. Set both to public

Start Development Server

# Make sure you're in frontend/ directory
npm run dev

The app will be available at: http://localhost:3000 (opens in a new tab)

You should see:

▲ Next.js 15.5.4
- Local:        http://localhost:3000
✓ Ready in 2.5s

Step 3: Setup Backend (Optional)

The backend is only needed for:

• Video transcription
• Audio processing
• Advanced PDF parsing
• Background processing tasks

Install Python Dependencies

cd backend
python -m venv venv
 
# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
 
# Install dependencies
pip install -r requirements.txt

Configure Backend Environment

Create .env file in backend/ directory:

cp .env.example .env

Edit .env:

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key
 
# OpenAI
OPENAI_API_KEY=sk-your_openai_key_here
 
# Redis (for Celery)
REDIS_URL=redis://localhost:6379/0
 
# API Configuration
API_PORT=8000
API_HOST=0.0.0.0

Start Redis

# macOS/Linux:
redis-server
 
# Or with Docker:
docker run -p 6379:6379 redis:alpine

Start Backend Server

# In backend/ directory with venv activated
uvicorn app.main:app --reload --port 8000

Backend will be available at: http://localhost:8000 (opens in a new tab)

Start Celery Worker

In a new terminal:

cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
celery -A app.worker.celery_app worker --loglevel=info

Step 4: Test Your Setup

1. Open the App

Visit: http://localhost:3000 (opens in a new tab)

2. Sign Up

Create an account using email/password

3. Create a Chatbot

1. Click "Create Chatbot"
2. Fill in name and description
3. Configure AI model (GPT-4o-mini recommended for testing)
4. Save

4. Test Chat

1. Open your chatbot
2. Type a message
3. You should see streaming response! ✨

5. Upload a Document

1. Go to Knowledge Base
2. Upload a PDF or text file
3. Wait for indexing
4. Ask questions about the document

Common Issues

Port Already in Use

# Kill process on port 3000
# macOS/Linux:
lsof -ti:3000 | xargs kill -9
# Windows:
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Database Connection Error

• Check Supabase URL and keys are correct
• Ensure project is not paused (free tier)
• Verify network connection

OpenAI API Error

• Verify API key is correct
• Check you have credits in OpenAI account
• Ensure key has proper permissions

Module Not Found

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Development Workflow

Frontend Development

cd frontend
 
# Start dev server (hot reload enabled)
npm run dev
 
# Run type checking
npm run type-check
 
# Run linter
npm run lint
 
# Build for production
npm run build

Backend Development

cd backend
 
# Run tests
pytest
 
# Format code
black app/
 
# Type checking
mypy app/

Next Steps

Now that your local environment is set up:

1. Explore the Repository Structure
2. Learn about Frontend Architecture
3. Try Deploying to Vercel
4. Read the User Guide to understand features

Need Help?

• Check Troubleshooting
• Ask in GitHub Discussions (opens in a new tab)
• Join our Discord