Getting Started

Prerequisites

• Node.js 20+ and npm (for api.faculytics)
• Bun (for app.faculytics and docs.dev.faculytics)
• Python 3.11+ and uv (for embedding.worker.faculytics)
• Rust toolchain (for scripts/moodle_course_builder)
• Docker and Docker Compose (for Redis and mock workers)
• PostgreSQL 15+ with pgvector extension

Repository Structure

This is a monorepo-style workspace with independent projects:

API (api.faculytics)

cd api.faculytics
cp .env.sample .env        # Configure environment variables
docker compose up -d        # Start Redis + mock worker
npm install
npx mikro-orm migration:up  # Apply database migrations
npm run start:dev            # Start dev server (port 5200)

Key environment variables: DATABASE_URL, MOODLE_BASE_URL, MOODLE_MASTER_KEY, JWT_SECRET, REFRESH_SECRET, REDIS_URL.

Frontend (app.faculytics)

cd app.faculytics
bun install
bun run dev                  # Start dev server (port 3000)

Set NEXT_PUBLIC_API_BASE_URL to point to the API (defaults to http://localhost:3000).

Embedding Worker (embedding.worker.faculytics)

cd embedding.worker.faculytics
uv sync
uv run uvicorn src.main:app --reload

Moodle Course Builder

cd scripts/moodle_course_builder
cargo build --release
cargo run -- --help

Running Tests

# API
cd api.faculytics && npm run test
 
# Embedding worker
cd embedding.worker.faculytics && uv run pytest
 
# Frontend type check
cd app.faculytics && npx tsc --noEmit

Commit Conventions

All commits follow Conventional Commits:

• feat: — New feature
• fix: — Bug fix
• refactor: — Code restructuring
• chore: — Maintenance tasks
• docs: — Documentation changes

Branching

• develop — Integration branch
• staging — Pre-production validation (receives cherry-picks from develop)