cuProject

The main project of our group for cuHacking 7.

Our project is a web app that views the user's code in real-time and helps a student learn without doing everything. (Less handholding, prompts the person to do specific parts). We hope for the student to be more independent.

This repo now has an Electron + React + TypeScript scaffold for the first desktop prototype.

• Node.js 20 or newer
• npm

npm install
npm run dev

Useful checks:

npm run lint
npm test
npm run build

The backend lives in apps/api and uses Express with MongoDB Atlas.

Run it locally:

npm run api:dev

Required API environment variables are listed in .env.example. Set them in your local shell or a local .env file that is not committed.

If Node fails to resolve the MongoDB Atlas SRV record even though PowerShell DNS works, set:

API_DNS_SERVERS=1.1.1.1,8.8.8.8

To point the Electron app at the MongoDB-backed API, set:

CUPROJECT_API_URL=http://localhost:4000

The login screen requires GitHub device-flow auth. To restrict access to specific GitHub users, set a comma-separated allowlist:

CUPROJECT_AUTHORIZED_GITHUB_USERS=your-github-username,teammate-github-username

If the allowlist is empty, any GitHub account that authorizes the app can sign in. If CUPROJECT_API_URL is not set, Electron falls back to the local prototype services, but the visible login remains GitHub-only.

AI generation is optional. When configured, the API uses a retrieval-first Project Tutor for chat, and can also improve deployment-log explanations and progressive checkpoint hints. Repository scans provide context for chat, then the backend ranks relevant code snippets with line numbers before asking the model for one grounded next step. If a model answer does not cite a retrieved file and line, the app withholds it and falls back to deterministic guidance.

GEMINI_API_KEY=your-google-ai-studio-api-key
GEMINI_MODEL=gemini-3.5-flash
GEMINI_REQUEST_TIMEOUT_MS=20000
PROJECT_TUTOR_PROVIDER=auto
OPENAI_API_KEY=optional-openai-api-key-for-coding-tutor
OPENAI_CODING_MODEL=gpt-5.6
OPENAI_REASONING_EFFORT=medium
OPENAI_REQUEST_TIMEOUT_MS=30000

PROJECT_TUTOR_PROVIDER=auto tries the OpenAI coding tutor first when OPENAI_API_KEY is set, then falls back to Gemini. Use gemini or openai to force one provider.

Core endpoints:

• GET /health
• POST /auth/github/device/start
• POST /auth/github/device/poll
• GET /auth/session
• POST /auth/logout
• GET /github/repositories
• POST /learning-projects
• GET /learning-projects
• GET /learning-projects/:projectId
• POST /learning-projects/:projectId/scans
• GET /learning-projects/:projectId/scans/latest
• GET /learning-projects/:projectId/scans
• GET /learning-projects/:projectId/chat
• POST /learning-projects/:projectId/chat
• POST /learning-projects/:projectId/checkpoints/:checkpointId/hints
• POST /deployment-errors/explain

Protected endpoints use:

Authorization: Bearer <app-session-token>

The desktop prototype now includes a GitHub-connected deployment learning assistant for Node.js, TypeScript, and JavaScript repositories.

It can:

• list repositories from a GitHub token kept in the Electron main process
• create local learning projects tied to a GitHub repository
• scan deployment-relevant repository context without cloning or executing code
• retrieve line-numbered code snippets that match the student's chat question
• detect the basic stack and package manager
• run deterministic deployment-readiness checks
• let the student ask the Project Tutor contextual questions after scanning
• persist scan history and progressive hint reveals locally
• explain pasted deployment logs with rule-based diagnosis and secret redaction

Optional environment variable:

CUPROJECT_GITHUB_CLIENT_ID=...
CUPROJECT_GITHUB_SCOPE=repo read:user
CUPROJECT_AUTHORIZED_GITHUB_USERS=...
GEMINI_API_KEY=...
OPENAI_API_KEY=...

CUPROJECT_GITHUB_CLIENT_ID enables the GitHub device-flow login screen. Create a GitHub OAuth App or GitHub App, enable device flow in the app settings, and use its client ID. The default scope is repo read:user so private repositories can be listed and scanned after authorization.