AcadHydra

AcadHydra is a full-stack academic operations prototype for managing the core workflows around terms, courses, sections, enrollment, attendance, grades, requests, announcements, and audit activity.

The repository contains a Rust API and a Next.js web client. It is designed to run locally against PostgreSQL, with synthetic seed data for demos and repeatable development.

Highlights

• Role-aware workflows for administrators, registrars, teachers, and students.
• Rust, Axum, Tokio, SQLx, and PostgreSQL on the backend.
• Next.js 16 App Router, TypeScript, and shadcn/ui-style Radix primitives on the frontend.
• JWT authentication with Argon2 password hashing and scoped instructor checks.
• CRUD flows for academic structures, enrollment, announcements, attendance, and grades.
• CSV import/export endpoints and an OpenAPI/Swagger UI at /docs.
• English and Chinese interface labels.
• Minimal and larger deterministic synthetic seed modes for local demos.

Repository Layout

backend/                 Rust API, migrations, and SQLx offline metadata
web/                     Next.js web client
backend/migrations/      PostgreSQL schema migration

Requirements

• Rust stable with edition 2024 support
• Node.js 20 or newer
• pnpm 10 or newer
• PostgreSQL 14 or newer

Quick Start

1. Create a disposable PostgreSQL database and enable pgcrypto, which provides the UUID defaults used by the schema.

   CREATE EXTENSION IF NOT EXISTS pgcrypto;

2. Create local configuration files from the checked-in templates.

   cp backend/.env.example backend/.env
   cp web/.env.example web/.env.local

   Set DATABASE_URL and JWT_SECRET in backend/.env. Keep both local; never commit either file.

3. Apply the schema. The sqlx CLI is only needed for migrations.

   cargo install sqlx-cli --no-default-features --features rustls,postgres
   cd backend
   sqlx migrate run

4. Start the API in a second terminal.

   cd backend
   SQLX_OFFLINE=true cargo run

   The API listens on http://localhost:8080 by default. Health checks are available at /health and /ready; interactive API documentation is available at /docs.

5. Install and start the web client.

   cd web
   pnpm install --frozen-lockfile
   pnpm dev

   Open http://localhost:3000.

Configuration

Variable	Component	Purpose
DATABASE_URL	API	PostgreSQL connection string
JWT_SECRET	API	Signing key for application tokens
HOST	API	Bind address, default 0.0.0.0
PORT	API	Listen port, default 8080
ADMIN_EMAIL	API	Optional administrator bootstrap account
ADMIN_PASSWORD	API	Password for the bootstrap account
ADMIN_NAME	API	Display name for the bootstrap account
SEED	API	Run the small synthetic dataset on startup when true
SEED_MASSIVE	API	Run the larger synthetic dataset on startup when true
NEXT_PUBLIC_API_BASE	Web	API origin, usually http://localhost:8080

For a local demo, set SEED=true after applying the migration. Use SEED_MASSIVE=true only with a disposable database because it creates a substantially larger synthetic dataset.

API Surface

The API is grouped into:

• /api/auth/* for login, registration, profile, refresh, and logout.
• /api/v1/terms, /courses, /sections, and /enrollments for academic structures.
• /api/v1/attendance, /grades, and /final-grades for teaching records.
• /api/v1/announcements and /api/v1/requests for communication and approval workflows.
• /api/import and /api/export for CSV-oriented data exchange.

The generated OpenAPI document is served at /api-docs/openapi.json and rendered through Swagger UI at /docs.

Development Checks

Run the focused checks from the repository root:

cargo fmt --manifest-path backend/Cargo.toml -- --check
SQLX_OFFLINE=true cargo test --manifest-path backend/Cargo.toml
pnpm --dir web install --frozen-lockfile
pnpm --dir web lint
pnpm --dir web build

SQLx query metadata is checked in under backend/.sqlx, so Rust compilation and tests do not require a live database connection. Runtime API checks still require PostgreSQL.

Security Notes

This is a local-first prototype, not a production deployment blueprint. Before exposing it publicly, review CORS, rate limiting, token storage, database permissions, migration operations, audit retention, and secret management. Seed accounts and passwords are synthetic demo data only and must not be reused in a real environment.

License

Released under the MIT License.