Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Andr21Da16/UNITRU-ACADEMIC/llms.txt

Use this file to discover all available pages before exploring further.

The fastest way to run Unitru Academic is with Docker Compose, which starts both the Python/FastAPI backend and the Next.js frontend in isolated containers with a single command. The entire setup takes under five minutes on a decent connection — the only caveat is that the first build downloads Chromium and Tesseract (~500 MB), so subsequent builds are nearly instant thanks to Docker layer caching.
The first docker compose up --build fetches the Playwright Chromium binary and installs Tesseract inside the backend image. This is approximately 500 MB of downloads. Subsequent builds reuse the cached layers and complete in seconds.

​
Prerequisites

​
Running with Docker Compose

1

Clone the repository

Clone the Unitru Academic monorepo to your local machine:
git clone https://github.com/Andr21Da16/UNITRU-ACADEMIC.git
cd UNITRU-ACADEMIC
2

Build and start both services

From the repo root, build the images and start both containers:
docker compose up --build
Docker Compose will:
  1. Build the backend image — installs Python dependencies, Chromium via playwright install --with-deps chromium, and Tesseract OCR.
  2. Build the frontend image — runs npm ci, injects NEXT_PUBLIC_BACKEND_WS_URL as a build argument, and produces a Next.js standalone bundle.
  3. Start both containers. The backend listens on :8000 and the frontend on :3000.
You will see both services streaming logs in the same terminal. Wait until you see the Next.js ready message before opening the browser.
3

Open the dashboard

Navigate to http://localhost:3000 in your browser. The Unitru Academic login screen will appear.
4

Enter your SUV credentials and wait for the dashboard

Type your UNT SUV username and password and submit the form. The frontend opens a WebSocket connection to the backend, which:
  1. Launches a headless Chromium browser.
  2. Navigates to the SUV login page.
  3. Downloads and OCR-solves the CAPTCHA (up to 3 retries).
  4. Logs in and selects the “Alumno” profile.
  5. Navigates through all academic modules — Profile → Academic Record → Enrollment → Attendance → Grades.
  6. Emits a dashboard_ready event with the complete structured payload.
The frontend shows real-time progress events as each step completes, so you can follow along during the extraction. The full session typically finishes in 20–40 seconds depending on SUV response times.
Never hardcode your SUV credentials in environment files, shell history, or source code. The backend is designed to receive them only over the live WebSocket connection — they are held in memory and discarded when the session ends.

​
Environment Variables

Both services ship with sensible defaults for local development. Override them in docker-compose.yml or as shell environment variables if needed.

​
Backend

VariableDefaultDescription
ALLOWED_ORIGINShttp://localhost:3000Comma-separated list of allowed CORS origins
PORT8000Server listen port (Railway injects this automatically in production)

​
Frontend

VariableDefaultDescription
NEXT_PUBLIC_BACKEND_WS_URLws://localhost:8000/wsWebSocket URL the browser connects to — baked in at build time
NEXT_PUBLIC_BACKEND_WS_URL is embedded into the JavaScript bundle during next build. Changing it after the image is built has no effect — you must rebuild the frontend image for a new value to take effect.

​
Local Development Without Docker

If you prefer to run the services directly on your machine for faster iteration:

​
Backend

Requirements: Python 3.12+, Tesseract OCR binary 
cd backend
pip install -r requirements.txt
playwright install chromium
Install Tesseract for your OS: 
brew install tesseract
Start the development server: 
uvicorn src.main:app --reload
# WebSocket available at ws://localhost:8000/ws

​
Frontend

Requirements: Node.js 22+ 
cd frontend
npm install
npm run dev
# Dashboard available at http://localhost:3000
Make sure the backend is already running before opening the frontend, or you will see a WebSocket connection error on the login screen.

Build docs developers (and LLMs) love

Get started for freeTalk to us