IntegriCode

IntegriCode is a web platform for reviewing source-code similarity in programming assignments. It gives instructors a controlled way to collect student work, compare submissions, and inspect the matching regions behind a similarity score.

The project is designed for academic-integrity review--not automatic conviction. A flagged pair is evidence for an instructor to examine; it is not, by itself, proof of plagiarism.

Who the Website Is For

User	What they can do
Instructor	Create assignments, choose the programming language and due date, share an assignment key, review submissions, add historical or exclusion material, run reports, and inspect matching code segments.
Student	Open the public submission page, enter an assignment key, submit identity information securely, upload source code, and retain a public confirmation key for checking submission status.

The interface supports English and French. Assignments currently accept Java, C, C++, or validated ZIP archives containing supported source files.

Typical Workflow

1. An instructor registers, creates an assignment, and configures its language, deadline, file-size limit, retention period, and resubmission policy.
2. IntegriCode generates an assignment key that the instructor gives to students.
3. Students submit through the public portal; they do not need instructor accounts.
4. The server validates and encrypts each submission before storing it.
5. The instructor can add older repositories for comparison or upload exclusion material such as starter code and boilerplate.
6. The instructor starts a similarity report.
7. The Python engine normalizes the source and combines token, structure, line, variable, and winnowing-based comparisons.
8. The dashboard presents aggregate results, flagged pairs, component scores, and the matching segments for human review.

Main Features

• Public student submission flow with assignment keys and confirmation IDs
• Instructor authentication, email verification, and assignment ownership checks
• Configurable due dates, retention periods, resubmission rules, and thresholds
• Encrypted submitter identity and encrypted stored artifacts
• Historical-code comparisons and boilerplate/exclusion inputs
• Asynchronous similarity reports with database-backed leases
• Pair-level scores and side-by-side matching-segment inspection
• Submission event history, downloads, and complete assignment ZIP exports
• Automated expiration cleanup and database/storage health monitoring
• Optional Stripe subscription management and Resend email notifications
• Local Docker, Oracle VM, and serverless Vercel deployment modes

Privacy and Interpretation

Student identity is encrypted in the browser using the application's RSA public key. Uploaded artifacts are encrypted by the backend before permanent storage, and database records receive expiration dates based on the assignment's retention policy. On Vercel, plaintext uploads use a short-lived private staging object that is deleted after the encrypted artifact is created.

Similarity can have legitimate explanations--including common algorithms, required interfaces, starter code, and language conventions. Instructors should inspect the matched segments and assignment context before drawing conclusions.

Project Structure

This repository is a monorepo containing:

• frontend/ React app
• backend/ Express API, authentication, PostgreSQL access, storage, and workers
• engine/ Python source-comparison engine
• api/ Vercel entry points for Express, queued reports, and the Python engine
• docs/ architecture, API, lifecycle, retention, and deployment documentation

At runtime, React provides the browser interface, Express enforces application rules, PostgreSQL stores canonical state, artifact storage holds encrypted files, and the Python engine performs report analysis.

Deployment Options

For a no-charge personal demo on Vercel Hobby, follow docs/vercel-deployment.md. The Vercel adapter keeps the existing Docker/Oracle deployment available.

For a persistent single-VM installation using Oracle Cloud Always Free, follow deploy/README.md.

Run Locally With Docker

From repo root:

docker compose up --build

Before you build the containers, copy backend/.env.example to backend/.env and frontend/.env.example to frontend/.env, then manually fill in the Stripe values. Backend needs the secret-side keys (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRO_PRICE_ID, STRIPE_ENTERPRISE_PRICE_ID); frontend needs the publishable key (REACT_APP_STRIPE_PUBLISHABLE_KEY) and API base URL if you are not using the defaults.

This starts:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000
• Postgres: localhost:5433

Backend health check:

curl http://localhost:4000/health

Backend Local Setup

If you want to seed dashboard data locally from your host machine after the containers are up, use the backend setup flow below.

Windows (PowerShell)

From the repo root:

cd frontend
npm install
copy .env.example .env
# edit .env and add the frontend env values, especially REACT_APP_STRIPE_PUBLISHABLE_KEY
cd ..
cd backend
npm install
copy .env.example .env
# edit .env and add the Stripe secret keys / price IDs
cd ..
docker compose up -d --build
cd backend
npm run setup

Mac / Linux

cd frontend
npm install
cp .env.example .env
# edit .env and add the frontend env values, especially REACT_APP_STRIPE_PUBLISHABLE_KEY
cd ..
cd backend
npm install
cp .env.example .env
# edit .env and add the Stripe secret keys / price IDs
cd ..
docker compose up -d --build
cd backend
npm run setup

This creates a dev instructor, assignment, submissions, and report data for the dashboard.

Stop / Reset

Stop containers:

docker compose down

Stop and wipe database volume:

docker compose down -v

Notes

• Backend runs migrations automatically on startup.

Further Documentation

• docs/API_ROUTES.md -- HTTP endpoint reference
• docs/DATA_DICTIONARY.md -- database entities and fields
• docs/backend/architecture.md -- backend design
• docs/backend/lifecycles.md -- end-to-end workflows
• docs/RETENTION_CLEANUP.md -- expiration behavior