Cpplify

Interactive C++ Notebook Platform — Jupyter-level usability for C++ developers, educators, and researchers.

Why Cpplify?

C++ developers lack the interactive development experience that Python enjoys with Jupyter. Cpplify solves this with:

• 🚀 Instant Setup — Single Docker command gets you started
• 📝 Multi-cell C++ — State persists across cells, just like Jupyter notebooks
• 🔐 Cloud-backed — Auth via GitHub, notebooks saved to Azure Blob Storage
• ⚡ Real-time Execution — Powered by Cling C++ interpreter

Quick Start

Prerequisites

• Docker 20.10+ & Docker Compose v2+
• Node.js 18+ (for frontend dev)

Development

# 1. Clone and configure
cp backend/.env.example backend/.env   # Fill in Supabase & Azure credentials
cp frontend/.env.example frontend/.env

# 2. Start backend (Docker with hot-reload)
docker compose -f docker-compose.dev.yml up --watch

# 3. Start frontend (separate terminal)
cd frontend && bun install && bun run dev

• Backend: http://localhost:8080/health
• Frontend: http://localhost:5173

Production

docker compose -f docker-compose.yml up --build

Features

Feature	Status
Code cells with C++ execution	✅ Complete
Markdown/text cells	✅ Complete
GitHub OAuth (Supabase)	✅ Complete
Cloud notebook storage (Azure Blob)	✅ Complete
Auto-save notebooks	✅ Complete
Kernel state persistence across cells	✅ Complete
Library magic commands (%use boost)	📋 Planned
CUDA cell support	📋 Planned
Real-time collaboration	📋 Planned

Architecture

┌──────────────────────────────────────────────────────────┐
│              React Frontend (Vite + TypeScript)           │
│         Monaco Editor • Supabase Auth • Auto-save        │
└─────────────────────┬────────────────────────────────────┘
                      │ REST API + Bearer JWT (ES256)
┌─────────────────────┴────────────────────────────────────┐
│              Go Backend (chi router + IoC)                │
│    Auth Middleware • Kernel Manager • Notebook CRUD       │
├─────────┬───────────┬──────────────┬─────────────────────┤
│ Kernel  │ Supabase  │  Supabase    │  Azure Blob         │
│ (Cling) │ Auth/JWKS │  PostgreSQL  │  Storage            │
└─────────┴───────────┴──────────────┴─────────────────────┘
                      │
┌─────────────────────┴────────────────────────────────────┐
│           Docker Container (Miniconda + Cling)           │
│              Go + Air (hot-reload) • Python 3            │
└──────────────────────────────────────────────────────────┘

Project Structure

cpplify/
├── backend/                      # Go backend server
│   ├── cmd/server/main.go        # Composition root (IoC wiring)
│   ├── internal/
│   │   ├── api/                  # Handlers, router, auth middleware
│   │   ├── auth/                 # Supabase JWKS JWT validation
│   │   ├── config/               # Environment variable loading
│   │   ├── domain/               # Interfaces & models
│   │   ├── kernel/               # Cling process lifecycle manager
│   │   └── storage/              # Supabase metadata + Azure Blob
│   ├── .env                      # Backend configuration
│   └── supabase_schema.sql       # Database schema
├── frontend/                     # React notebook UI
│   ├── src/
│   │   ├── api/kernelApi.ts      # API client with JWT injection
│   │   ├── contexts/             # Auth context (Supabase)
│   │   ├── pages/                # Dashboard, Notebook, Auth
│   │   └── components/notebook/  # Cell components
│   └── .env                      # Frontend configuration
├── kernel/
│   └── kernel_wrapper.py         # Python bridge: Go ↔ Cling REPL
├── docs/                         # Documentation
├── Dockerfile.dev                # Development container
├── docker-compose.dev.yml        # Dev compose (hot-reload + watch)
└── docker-compose.yml            # Production compose

API Endpoints

All /api routes require Authorization: Bearer <supabase-jwt>.

Endpoint	Method	Description
/health	GET	Health check
/api/session	POST	Create kernel session
/api/session/{id}	DELETE	Terminate session
/api/session/{id}/reset	POST	Reset kernel state
/api/execute	POST	Execute C++ code
/api/notebooks	GET	List user notebooks
/api/notebooks	POST	Create notebook
/api/notebooks/{id}	GET	Get notebook content
/api/notebooks/{id}	PUT	Update (auto-save)
/api/notebooks/{id}	DELETE	Delete notebook

Cloud Services

Service	Purpose
Supabase	GitHub OAuth + metadata storage (PostgreSQL)
Azure Blob	Notebook file storage (.cly JSON format)
Azure Container Instances	Backend deployment (planned)

Development

Docker Development (Recommended)

# Start with hot-reload
docker compose -f docker-compose.dev.yml up --watch

# View logs
docker compose -f docker-compose.dev.yml logs -f

# Enter container shell
docker exec -it cpplify-dev bash

# Restart after config changes
docker compose -f docker-compose.dev.yml restart

Development Workflow

1. Run docker compose -f docker-compose.dev.yml up --watch
2. Edit Go code locally → air auto-rebuilds inside the container
3. Edit frontend locally → Vite HMR applies changes instantly
4. Access frontend at http://localhost:5173, backend at http://localhost:8080

Environment Setup

Backend (backend/.env):

PORT=8080
SUPABASE_URL=https://<project>.supabase.co
SUPABASE_ANON_KEY=<anon-key>
SUPABASE_SERVICE_KEY=<service-role-key>
AZURE_STORAGE_CONNECTION_STRING=<connection-string>
AZURE_STORAGE_CONTAINER=cpplify-notebooks

Frontend (frontend/.env):

VITE_SUPABASE_URL=https://<project>.supabase.co
VITE_SUPABASE_ANON_KEY=<anon-key>
VITE_API_URL=http://localhost:8080

Local Native Development (Advanced)

Only use this if you need IDE debugging for the Go backend and have Cling installed locally.

cd backend
KERNEL_PATH="cling" go run cmd/server/main.go

Roadmap

Phase	Scope	Status
Phase 1	Frontend + Backend + Kernel + Auth + Storage	✅ Complete
Phase 2	Library integration, export, polish	🚧 Next
Phase 3	CUDA/GPU support, profiling	📋 Planned
Phase 4	Multi-user, real-time collaboration	📋 Planned

Contributing

We welcome contributions! Please see docs/CONTRIBUTING.md.

License

MIT License — see docs/LICENSE for details.

---

Cpplify — Interactive C++ for everyone 🚀