Skip to content

APPWRITE.md

Latest commit

 

History

History
140 lines (101 loc) · 5.72 KB

APPWRITE.md

File metadata and controls

140 lines (101 loc) · 5.72 KB
Raw

Appwrite Backend Setup

This project uses Appwrite as its backend for authentication, database, cloud functions, and file storage. To run this project locally or deploy your own instance, you'll need to set up an Appwrite project.

Prerequisites

  1. Appwrite Instance — You need a running Appwrite instance:

  2. Appwrite CLI — Install and log in:

    npm install -g appwrite-cli
appwrite login

Setup Instructions

We provide npm scripts to streamline the backend setup process.

1. Initialize Project

Run the initialization script. This creates an appwrite.json file from our configuration template and links it to your Appwrite project.

npm run appwrite:init
  • Follow the prompts to create a new project or link to an existing one.
  • This will update appwrite.json with your specific projectId.

2. Deploy Configuration

Once initialized, deploy the entire backend structure (databases, collections, functions, etc.):

npm run appwrite:push

This command will:

  • Create the Sonar DB database.
  • Create all required collections with correct schemas (Sessions, Activity Logs, Reports, Settings).
  • Deploy all Cloud Functions (sonar-auth, sonar-session-sync, sonar-activity-sync, sonar-settings, sonar-teams).

Project Structure

File Description
appwrite.config.json Source-of-truth template for the backend schema (committed to repo)
appwrite.json Active config used by CLI (generated by npm run appwrite:init — do not commit if it contains secrets)

Services Overview

Authentication

  • Users are managed as Appwrite Users (not a separate collection).
  • Teams are identified by structured email addresses: {teamName}--{hackathonId}@teams.sonar.knurdz.org.
  • Admin users are identified by Appwrite labels (admin) or user prefs.role = "admin".

Database: Sonar DB

Collection Purpose
Sessions Tracks active editor sessions — team ID, status (online/offline), last seen timestamp, build type
Activity Logs Audits user actions — keystrokes, window focus events, paste events, file changes
Reports Stores generated PDF report metadata
Settings Global and per-hackathon settings (e.g., blockInternetAccess, blockNonEmptyWorkspace)

Cloud Functions

Function ID Purpose
sonar-auth Custom authentication logic — team registration, student ID lookup, version gating, hackathon management
sonar-session-sync Real-time session upsert from the editor's main process
sonar-activity-sync Syncs accumulated activity logs from editor to Appwrite
sonar-settings CRUD operations for the Settings collection; used as a secure fallback proxy when direct DB access is restricted
sonar-teams Team management and role administration

Environment Variables

Editor (.env in Sonar-Code-Editor/)

Variable Description
VITE_APPWRITE_ENDPOINT Appwrite API endpoint (e.g., https://cloud.appwrite.io/v1)
VITE_APPWRITE_PROJECT_ID Your Appwrite Project ID
VITE_APPWRITE_DB_NAME Database ID (e.g., devwatch_db)
VITE_APPWRITE_COLLECTION_SESSIONS Sessions collection ID
VITE_APPWRITE_COLLECTION_ACTIVITY_LOGS Activity Logs collection ID
VITE_APPWRITE_COLLECTION_REPORTS Reports collection ID
VITE_APPWRITE_COLLECTION_SETTINGS Settings collection ID
VITE_DEV_KEY Developer key for local dev (username:secret format). Do not use BUILD_SIGNING_KEY directly here.

Web App (.env in Sonar-Web-App/)

Variable Description
PUBLIC_APPWRITE_ENDPOINT Appwrite API endpoint
PUBLIC_APPWRITE_PROJECT_ID Appwrite Project ID
PUBLIC_APPWRITE_DB_NAME Database ID
PUBLIC_APPWRITE_COL_HACKATHONS Hackathons collection ID
PUBLIC_APPWRITE_COL_SESSIONS Sessions collection ID
PUBLIC_APPWRITE_COL_ACTIVITY_LOGS Activity Logs collection ID
PUBLIC_APPWRITE_COL_SETTINGS Settings collection ID
APPWRITE_API_KEY Server-side only — API key with users.read, users.write, documents.read, documents.write scopes

Appwrite Console (Global Function Variables)

These must be set in the Appwrite Console → Project Settings → Global Variables so all functions can access them:

Variable Description
APPWRITE_ENDPOINT Appwrite API endpoint
APPWRITE_PROJECT_ID Project ID
APPWRITE_API_KEY API key with required scopes
BUILD_SIGNING_KEY Shared secret used to sign official build tokens and verify HMAC signatures from the editor. Never expose this in .env files or client code.
DB_ID Database ID
COL_HACKATHONS Hackathons collection ID
COL_HACKATHON_PARTICIPANTS Hackathon Participants collection ID (fast studentId → teamId lookup)
COL_SESSIONS Sessions collection ID
COL_ACTIVITY_LOGS Activity Logs collection ID
COL_SETTINGS Settings collection ID
LATEST_APP_VERSION Latest release version string (e.g., 1.0.0-beta.6). Used by sonar-auth for version gating.

Build Attestation

Official production builds include a signed build-attestation.json token generated by scripts/generate-attestation.js and embedded in the compiled app. The Appwrite sonar-auth function verifies this token's HMAC signature (using BUILD_SIGNING_KEY) to distinguish official builds from unofficial or dev clients.

In development, set VITE_DEV_KEY=username:secret to authenticate using a developer HMAC flow instead.