TellaAI

Getting Started

Quick setup guide for the SophieAI platform

Getting Started

This guide will help you set up and run the SophieAI educational platform locally.

Estimated Setup Time: 15-20 minutes for first-time setup, 5 minutes for experienced developers

Prerequisites

Essential Dependencies:

  • Node.js: Version 18 or higher (Download)
  • Bun: Package manager and runtime (recommended) (Install Guide)
  • PostgreSQL: Version 14 or higher (Download)
  • Redis: For background job processing (Download)

Quick Install with Package Managers:

# macOS with Homebrew
brew install node postgresql redis
npm install -g bun

# Ubuntu/Debian
sudo apt update && sudo apt install nodejs postgresql redis-server
npm install -g bun

Required Service Accounts:

  • AWS Account: For S3 file storage
  • Google Cloud Console: For OAuth and AI services
  • Groq Account: For AI API access

API Keys Required: You'll need to obtain API keys from each service. Keep them secure and never commit them to version control.

Minimum System Requirements:

  • RAM: 8GB (16GB recommended)
  • Storage: 10GB free space
  • CPU: 2+ cores (4+ recommended)
  • Network: Stable internet connection for AI services

Production Recommendations:

  • RAM: 32GB+
  • Storage: SSD with 100GB+ free space
  • CPU: 8+ cores
  • Network: High-speed, low-latency connection

Architecture Overview

The SophieAI platform consists of:

  • Backend API: Fastify-based Node.js server
  • Database: PostgreSQL with Prisma ORM
  • Authentication: Better-auth with Google OAuth
  • File Storage: AWS S3 for documents and media
  • Background Jobs: BullMQ with Redis
  • AI Services: Google AI SDK and Groq SDK

Environment Setup

Clone Repository

git clone <repository-url>
cd SophieAI

Pro Tip: Use SSH for cloning if you have GitHub SSH keys configured for better security and convenience.

Backend Setup

Navigate to the backend directory and install dependencies:

cd backend
bun install

Node Version: Ensure you're using Node.js 18+ by running node --version. Use nvm or fnm to manage Node versions if needed.

Environment Variables

Create a .env file in the backend directory with the following variables:

.env
# Database
DATABASE_URL="postgresql://username:password@localhost:5432/sophieai"

# Server Configuration
BIND_PORT=5000
BIND_ADDR=127.0.0.1
NODE_ENV=development

# Client Configuration
CLIENT_ORIGIN="http://localhost:3000"
TRUSTED_ORIGINS="http://localhost:3000"

# Better-auth Configuration
BETTER_AUTH_URL="http://localhost:5000"

# Google OAuth (required for authentication)
GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_CLIENT_SECRET="your_google_client_secret"

# AI Services
GROQ_API_KEY="your_groq_api_key"
GOOGLE_API_KEY="your_google_api_key"

# AWS S3 (required for file uploads)
AWS_ACCESS_KEY="your_aws_access_key"
AWS_SECRET_KEY="your_aws_secret_key"
AWS_S3_BUCKET="your_s3_bucket_name"
AWS_REGION="us-east-1"

# Redis (required for background jobs)
REDIS_URL="redis://localhost:6379"

# Optional Features
ENABLE_SWAGGER=true

Security Notice: Never commit your .env file to version control. Add it to your .gitignore file immediately.

Database Setup

Start PostgreSQL and create the database:

CREATE DATABASE sophieai;

Run database migrations and generate Prisma client:

bunx prisma migrate dev
bunx prisma generate

Verify Database: Run bunx prisma studio to open a web interface and verify your database connection.

Redis Setup

# Using Homebrew
brew services start redis

# Verify Redis is running
redis-cli ping
# Start Redis service
sudo systemctl start redis
sudo systemctl enable redis

# Verify Redis is running
redis-cli ping
# Run Redis in Docker
docker run -d -p 6379:6379 --name redis redis:alpine

# Verify connection
docker exec redis redis-cli ping
# Using Windows Subsystem for Linux (WSL)
sudo apt update
sudo apt install redis-server
sudo service redis-server start

# Verify Redis is running
redis-cli ping

AWS S3 Setup

  1. Create an AWS account and S3 bucket
  2. Configure bucket CORS policy:
CORS Configuration
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "POST", "PUT", "DELETE"],
    "AllowedOrigins": ["http://localhost:3000"],
    "ExposeHeaders": ["ETag"]
  }
]
  1. Set up IAM user with S3 permissions
  2. Add credentials to environment variables

Cost Management: S3 costs are based on storage and requests. Consider setting up lifecycle policies for cost optimization in production.

Google OAuth Setup

  1. Go to Google Cloud Console
  2. Create a new project or select existing one
  3. Enable Google+ API and Google Calendar API
  4. Create OAuth 2.0 credentials:
    • Authorized redirect URI: http://localhost:5000/api/auth/callback/google
  5. Add client ID and secret to environment variables

Security: Keep your client secret secure. In production, use environment variables and secure secret management.

AI Service Setup

Groq API Setup:

  1. Sign up at Groq
  2. Navigate to API Keys section
  3. Generate a new API key
  4. Add GROQ_API_KEY to your environment variables

Features:

  • Fast inference speeds
  • Cost-effective for high-volume usage
  • Support for popular LLM models

Google AI API Setup:

  1. Enable Generative AI API in Google Cloud Console
  2. Create an API key in the credentials section
  3. Add GOOGLE_API_KEY to your environment variables

Features:

  • Gemini model access
  • Integrated with Google services
  • Reliable and scalable infrastructure

Running the Application

Start Backend Server

# Development mode with auto-reload
bun run dev

# Production mode
bun run start

The backend server will start on http://localhost:5000

Server Started: You should see log messages indicating successful database connection and server startup.

Verify Setup

Check that the server is running:

curl http://localhost:5000/health

When ENABLE_SWAGGER=true, Swagger documentation is available at:

http://localhost:5000/docs

API Documentation: The Swagger UI provides interactive API documentation where you can test endpoints directly.

Development Tools

Database Management

View and manage data with Prisma Studio:

bunx prisma studio

Logs

Application logs are output to console in development mode. In production, consider using a log aggregation service.

Testing

Run the test suite:

# Unit tests
bun test

# Integration tests
bun test:integration

Troubleshooting

Production Deployment

Production Ready: Before deploying to production, review our Production Deployment Guide for security best practices and performance optimizations.

Environment Considerations

  • Use production-grade PostgreSQL instance
  • Set up Redis cluster for scalability
  • Use environment variables for all secrets
  • Enable HTTPS for all services
  • Configure proper CORS origins

Performance Optimization

  • Enable database connection pooling
  • Set up Redis clustering
  • Configure CDN for static assets
  • Implement rate limiting
  • Use horizontal scaling for API servers

API Usage

Authentication

All API endpoints require authentication. Start by signing in:

curl -X POST http://localhost:5000/api/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

Example API Calls

Create a course:

curl -X POST http://localhost:5000/api/courses \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mathematics 101",
    "professor": "Dr. Smith",
    "semester": "Fall 2024",
    "color": "blue",
    "emoji": "📐"
  }'

Upload a document:

curl -X POST http://localhost:5000/api/documents/upload \
  -F "file=@document.pdf" \
  -F "title=Course Material" \
  -F "courseId=course_123"

Next Steps

Setup Complete! Your SophieAI development environment is ready. Here are some recommended next steps:

SophieAI Platform Documentation

Complete documentation for the SophieAI educational platform

API Reference

Technical API specification for SophieAI platform