Contributing

First Time Setup

Prerequisites

# For working with database stuffs
cargo install sqlx-cli --version 0.9.0 --locked --no-default-features --features rustls,postgres,sqlx-toml
# For working on docs/
cargo install mdbook@0.5.4 mdbook-mermaid@0.17.1 --locked # optional

Clone

git clone https://github.com/freeCodeCamp/exam-platform.git
cd exam-platform
bun install
docker network create platform

bun install also installs the Husky pre-commit hook.

Environment

Copy every example, then fill blanks:

for d in apps/auth-api apps/examiner-dashboard apps/web-app apps/desktop-app databases/examiner; do
  cp -n "$d/.env.example" "$d/.env"
done

.env is read automatically only by:

Rust apps read only the process environment. Export the app’s .env into the shell before cargo:

set -a; source apps/auth-api/.env; set +a
cargo run -p auth-api

Or use direnv: echo dotenv > .envrc && direnv allow in each app directory, then run cargo from there. .envrc is not in .gitignore; do not commit it.

All variables: Environment Variables.

eDb

cd databases/examiner
docker compose up -d --wait
set -a; source .env; set +a
cargo run -p edb --bin edb-migrate

Run edb-migrate again after pulling new migrations. Reset with docker compose down -v.

Editor

VS Code: install recommended extensions (.vscode/extensions.json). Settings run clippy on save, set ENVIRONMENT=development for rust-analyzer, and link both Cargo workspaces.

Development

Run

cargo run rows need their .env exported first (Environment). bun run dev starts wApp and eDd client together. eDd client proxies /api to eDd server. wApp and dApp call aAPI at AUTH_API_URL.

Images: docker compose -f apps/<app>/compose.yaml up --build. Build context is repo root.

Workspaces

Shared versions live in package.json catalogs: reference with catalog: or catalog:astro, do not pin in members.

Check

CI (.github/workflows/ci.yml) runs only jobs whose paths changed. Run the same locally before pushing:

# Root Cargo workspace (eDb running; source databases/examiner/.env for EDB_ADMIN_URL)
cargo fmt --all --check
cargo clippy --workspace --all-targets --locked
cargo clippy -p runtime --no-default-features --all-targets --locked
DATABASE_URL=$EDB_ADMIN_URL cargo test --workspace --locked

# dApp backend
cargo fmt --all --check --manifest-path apps/desktop-app/Cargo.toml
cargo clippy --workspace --all-targets --locked --manifest-path apps/desktop-app/Cargo.toml
cargo test --workspace --locked --manifest-path apps/desktop-app/Cargo.toml

# Bun
bun run check
bun run build

# Deploy Action (migration gate, rollback)
(cd deploy && bun test)

Clippy all is deny. Format Rust with rustfmt (rustfmt.toml), eDd client with bun --filter examiner-dashboard-client fmt (oxfmt).

Database Changes

eDb schema, migrations and queries live in crate edb (databases/examiner/). Run every step from that directory with eDb up (docker compose up -d --wait). Only add, release, then remove: drop or rename only once no running or previous eDd or aAPI image uses the object. Never edit an applied migration.

sqlx-cli reads EDB_MIGRATOR_URL from its .env; cargo does not, so export it first.

1. Create a reversible migration pair:

cargo sqlx migrate add -r -s <name> # migrations/NNNN_<name>.{up,down}.sql

2. Write up and down SQL, naming the schema (edd.users; shared if both apps write the table, see eDb schemas), and grant each app role what it needs on new tables. down is for local development only; production never runs it.
3. Apply it to local eDb:

cargo run -p edb --bin edb-migrate # or: cargo sqlx migrate run

To iterate on uncommitted migration: cargo sqlx migrate revert, make edits, then run it again.

4. Add or change queries in src/edd/, src/aapi/ or src/shared/ (one module per table group, each an impl Database block of query!/query_as!). SQLX_OFFLINE is true in .cargo/config.toml, so cargo check -p edb checks them against committed .sqlx/, and fails on a new or changed query. To validate against local eDb, override it: SQLX_OFFLINE=false cargo check -p edb.
5. Test with #[sqlx::test(migrations = false)], calling testing::setup first: it bootstraps roles and schemas, then migrates as edb_migrator. Query through testing::database_as to run as the app’s role. #[sqlx::test] reads DATABASE_URL, not sqlx.toml, and creates a database per test:

DATABASE_URL=$EDB_ADMIN_URL cargo test -p edb

6. Refresh offline query data:

cargo sqlx prepare

The Husky pre-commit hook runs this and stages .sqlx/ when eDb files are staged. This step never blocks the commit: if it warns with cargo sqlx prepare failed; .sqlx/ may be stale, manually run step 6.

7. Commit migration, queries and .sqlx/ together. Local (.cargo/config.toml), Docker and CI builds all use SQLX_OFFLINE=true. CI fails on a stale .sqlx/: offline clippy on a missing query, cargo sqlx prepare --check on one whose types changed.

Commits and PRs

Conventional Commits: release-please reads them to version each app (Releases).

<type>(<scope>): <summary>

Follow Database and Rust conventions.