Class Portal

A lightweight course portal for ~30 students with Google Sheets as the backend.

Features

Implemented

• FastAPI application scaffold
• Configuration via environment variables
• Docker containerization
• Development environment with hot reload
• SQLite for tokens and rate limiting
• Health check endpoint (/health)
• Google Sheets integration (with caching)
• Data models (Student, Quiz, QuizSubmission)
• Magic link authentication
• Student account claiming
• Onboarding flow
• Quiz system with auto-grading
• Admin analytics dashboard (per-question quiz performance)
• Admin grading page (spreadsheet view of all student scores)
• CSV export of grades

Planned

• CI/CD with GitHub Actions
• Production deployment to DigitalOcean
• Interactive Tools Feature
  • Tools landing page (/tools)
  • Individual tool pages (/tools/{tool_id})
  • Command builder UI (beginner flags)
  • Scenario-based exercises with collapsible hints
  • Embedded mini-quizzes with instant feedback
  • Output simulator (sample command outputs)
  • Progress tracking (localStorage)

Tech Stack

Component	Technology
Backend	FastAPI (Python 3.12)
Database	Google Sheets + SQLite
Templates	Jinja2
Auth	Magic links (JWT sessions)
Container	Docker
Hosting	DigitalOcean Droplet

Project Structure

classapp/
├── app/
│   ├── main.py            # FastAPI entry point
│   ├── config.py          # Settings (pydantic-settings)
│   ├── routers/           # Route handlers
│   ├── services/          # Business logic
│   ├── models/            # Data models
│   ├── db/                # Database (SQLite)
│   └── templates/         # Jinja2 templates
├── content/
│   ├── quizzes/           # Quiz markdown files
│   └── tools/             # Interactive tool reference pages
├── tests/                 # Pytest tests
├── scripts/               # Utility scripts
├── nginx/                 # Nginx config
├── Dockerfile
├── docker-compose.yml     # Production
└── docker-compose.dev.yml # Development

Development

Prerequisites

• Python 3.12+
• Docker (optional, recommended)

Setup

1. Clone the repository

   git clone <repo-url>
   cd classapp

2. Create environment file

   cp .env.example .env
   # Edit .env with your values

3. Option A: Run with Docker (recommended)

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

4. Option B: Run locally

   python -m venv venv
   source venv/bin/activate  # or `venv\Scripts\activate` on Windows
   pip install -r requirements-dev.txt
   uvicorn app.main:app --reload

5. Access the app

   http://localhost:8000
   

Environment Variables

Variable	Required	Default	Description
SECRET_KEY	Yes	-	JWT signing key (32+ chars)
BASE_URL	Yes	-	Public URL of the app
GOOGLE_SHEETS_ID	Yes	-	Google Spreadsheet ID
GOOGLE_SERVICE_ACCOUNT_PATH	Yes	-	Path to service account JSON
SMTP_HOST	Yes	-	SMTP server hostname
SMTP_PORT	No	587	SMTP server port
SMTP_USER	Yes	-	SMTP username
SMTP_PASS	Yes	-	SMTP password
ENV	No	development	Environment (development/production)
LOG_LEVEL	No	INFO	Log level
SQLITE_PATH	No	data/app.db	SQLite database path

Testing

Run all tests

pytest

Run with coverage

pytest --cov=app --cov-report=html

Run specific test file

pytest tests/test_root.py -v

Run tests in Docker

docker compose -f docker-compose.dev.yml run --rm app pytest

Deployment

Production Docker Compose

The docker-compose.yml is configured for production:

# On the server
docker compose pull
docker compose up -d

Manual Deployment

1. Build the image

   docker build -t classapp .

2. Run the container

   docker run -d \
     --name classapp \
     -p 127.0.0.1:8000:8000 \
     --env-file .env \
     -v /var/lib/classapp:/var/lib/classapp \
     classapp

CI/CD (Planned)

GitHub Actions workflow will:

1. Run tests on pull requests
2. Build and push Docker image to GHCR on merge to main
3. SSH to droplet and deploy

API Endpoints

Currently Available

Method	Path	Description
GET	/	Root endpoint (returns app info)
GET	/health	Health check (SQLite + Sheets status)

Authentication & User Routes

Method	Path	Description
POST	/auth/request-link	Request magic link
GET	/auth/verify	Verify magic link token
POST	/auth/logout	Logout
GET	/claim	Account claim form
POST	/claim	Submit claim
GET	/onboarding	Onboarding form
POST	/onboarding	Submit onboarding
GET	/home	Dashboard
GET	/quizzes	Quiz list
GET	/quiz/{id}	Quiz form
POST	/quiz/{id}	Submit quiz
GET	/me	Profile
GET	/tools	Tools landing page
GET	/tools/{id}	Individual tool page

Admin Routes (requires admin_email in Config sheet)

Method	Path	Description
GET	/admin/analytics	Quiz analytics overview
GET	/admin/quiz/{id}	Per-question analytics for a quiz
GET	/admin/grading	Grading table (all students x all quizzes)
GET	/admin/grading/csv	Download grades as CSV

Admin Configuration

The admin dashboard requires setting admin_email in the Config sheet of your Google Spreadsheet:

key	value
admin_email	admin@example.com

Only the user with this email can access admin pages:

• Analytics (/admin/analytics) - Quiz completion rates and average scores
• Quiz Details (/admin/quiz/{id}) - Per-question analytics with answer distribution
• Grading (/admin/grading) - Spreadsheet view of all students' best scores per quiz
• CSV Export (/admin/grading/csv) - Download grades as CSV file

Admin users see an "Admin" link in the navigation bar on all pages.

Documentation

• SPEC.md - Technical specification
• PLAN.md - Implementation plan

License

Private - All rights reserved