GradeView

GradeView is a multi-service web app for viewing grades, syncing data, and generating reports. It includes a React web UI, a Node.js API, a Python-based progress report service, and supporting services like Cloud SQL Proxy.

High-level architecture

Project structure

Grades/
  api/                # Node.js API
  website/            # React web UI and server
  gradesync/           # Grade sync service (FastAPI)
  progressReport/     # Progress report service
  reverseProxy/       # Nginx reverse proxy
  docs/               # Docs and helper scripts
  scripts/            # Utility scripts
  secrets/            # Local secrets (not committed)
  docker-compose.yml  # Production-like compose
  docker-compose.dev.yml # Dev compose with Cloud SQL Proxy
  .env.example        # Environment template
  config.example.json # Legacy config migration template (optional)

Key services

• Web UI: React app served by the web container.
• API: Node.js server for authentication and grade data access.
• GradeSync: FastAPI service to sync grades from external sources.
• Progress Report: Python service for report generation.
• Cloud SQL Proxy (dev compose): Connects to a Cloud SQL instance.

Authentication notes

• Only @berkeley.edu accounts can authenticate (enforced by Google token domain check).
• Runtime authorization is DB-only (users + course_permissions).
• Runtime config is DB-only (gradeview_config, system_config, course_configs, assignment_categories).

IAM roles

• super_admin: hardcoded global admin (weszhang@berkeley.edu) with system-wide manage permission.
• course_admin: can manage GradeSync and course config for bound courses only.
• instructor: can view class/student data for bound courses, but cannot access GradeSync admin UI.
• student: can only view their own grades (and only for enrolled courses).

Configuration

1. Copy the environment template:

   cp .env.example .env

2. Fill in required values in .env:

• Database connection (GRADESYNC_DATABASE_URL or POSTGRES_*)
• Third-party credentials (GRADESCOPE_*, PL_API_TOKEN, ICLICKER_*)

3. Configure runtime settings via /v2/config and /v2/config/sync (DB-backed endpoints).
4. If using the dev compose with Cloud SQL Proxy:
   • Place your Google service account key at secrets/key.json.
   • Set INSTANCE_CONNECTION_NAME in .env.

Running with Docker

• Development-like stack:

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

• One-command health check (services + recent logs):

  docker compose -f docker-compose.dev.yml ps && docker compose -f docker-compose.dev.yml logs --tail=60 api web gradesync

• Production-like stack:

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

Cloud deployment (CI/CD)

• The deploy workflow now builds and pushes images in GitHub Actions, then the GCE VM only runs pull + up.
• This reduces VM CPU/RAM pressure and avoids slow in-place builds on the cloud host.
• Images are tagged with commit SHA and deployed as immutable versions.

Required GitHub secrets for deployment:

• GCP_SA_KEY, GCP_PROJECT_ID, GCP_ZONE, GCE_INSTANCE, GCE_SSH_USER
• GHCR_USERNAME, GHCR_TOKEN (for pulling private GHCR images on the VM)

Notes:

• Registry base path used by workflow: ghcr.io/<org>/gradeview
• Services in docker-compose.yml are configured for stable runtime (health checks + log rotation, no dev bind mounts)
• Production deploys use docker-compose.prod.yml in addition to docker-compose.yml; the override makes Cloud SQL Proxy use the GCE VM's attached service account instead of a checked-in key file.
• GitHub Actions deploys require repo secrets GHCR_USERNAME and GHCR_TOKEN. Use a dedicated classic PAT with at least read:packages and write:packages.

Common ports

• Web UI: 3000
• API: 8000
• Progress Report: 8080

Documentation by feature

• Documentation hub: docs/README.md
• Database: docs/features/database.md
• Auth & IAM: docs/features/auth-and-iam.md
• Config & Settings: docs/features/config-and-settings.md
• GradeSync: docs/features/gradesync.md
• Dev & Deployment: docs/features/dev-and-deploy.md

Troubleshooting

• If login fails, confirm the account is @berkeley.edu and has DB permissions in users + course_permissions.
• For DB connection issues, confirm Cloud SQL Proxy settings and POSTGRES_* values.