Skip to main content

​
Why Self-Host?

Sunschool is open source and designed for easy self-hosting, giving you complete control over your educational platform:

Data Ownership

Your data stays on your infrastructure. Nothing gets sold or used to train external models.

Privacy Control

Keep sensitive student information in your own environment with full audit capability.

Customization

Modify prompts, features, and workflows to match your educational philosophy.

Transparency

Read the code, audit the AI prompts, and verify exactly how the system works.

​
Architecture Overview

Sunschool uses a modern, production-ready stack: 
client/          React 19 frontend (Vite)
server/          Express.js 5 API with JWT auth
shared/          TypeScript schemas and types
drizzle/         Database migration files
scripts/         Utility and admin scripts
tests/           Playwright e2e tests

​
Technology Stack

LayerTechnology
FrontendReact 19 + TypeScript, React Native Web, React Query, Wouter, Vite
BackendNode.js 22, Express.js 5, JWT auth, Drizzle ORM
DatabasePostgreSQL (Neon serverless compatible)
AIOpenRouter API (primary), Bittensor Subnet 1 (experimental), Perplexity API
DeploymentRailway (auto-deploy), Docker-ready
TestingJest (unit), Playwright (e2e)

​
Deployment Options

​
Cloud Platforms

Deploy the frontend static build:
npm run build
# Outputs to client/dist/
Point your serverless functions to the backend or deploy separately.
Build and run with Docker:
docker build -t sunschool .
docker run -p 5000:5000 --env-file .env sunschool
Requires PostgreSQL database accessible from container.
Install Node.js 22, PostgreSQL, and run:
npm install
npm run build
npm start
Use PM2 or systemd for process management.

​
Local Development

For development and testing: 
git clone https://github.com/allonethingxyz/sunschool.git
cd sunschool
npm install

# Create .env file (see Environment Configuration)
cp .env.example .env

# Run in development mode
npm run dev
Development server runs at http://localhost:5000 with hot reload.

​
System Requirements

Minimum requirements - For production deployments, see the Requirements page.
  • Node.js: v20+ (v22 recommended)
  • PostgreSQL: 12+ (Neon serverless supported)
  • npm: 8+
  • Memory: 512MB minimum (2GB+ recommended)
  • Storage: 1GB+ for application and database

​
Key Features

​
AI-Powered Learning

  • Grade-specific prompts - K-2, 3-4, 5-6, 7-8, 9+ with reading level validation
  • Multi-provider AI - OpenRouter primary with Bittensor fallback
  • SVG illustrations - LLM-generated educational graphics via Gemini 3.1
  • Adaptive quizzes - Concept mastery tracking with spaced repetition

​
Security & Authentication

  • JWT-based auth - Secure token-based authentication
  • Role-based access - Admin, Parent, and Learner roles
  • Password hashing - scrypt with salt for secure storage
  • First user admin - Automatic admin promotion for initial user

​
Data Management

  • Auto migrations - Schema updates run on server startup
  • External sync - Optional PostgreSQL backup connections
  • Data export - Full data export capability for parents/admins
  • Privacy-first - No external tracking or data sharing

​
Next Steps

System Requirements

Verify your environment meets the prerequisites

Environment Setup

Configure environment variables and API keys

Database Setup

Initialize PostgreSQL and run migrations

Security

Implement authentication and access controls

​
Support

For issues or questions: