# Mathē backend

This is the backend application for the `Mathē` system,. It handles the core logic, data management, and communication with external services, and exposes a REST API to interact with.

---

## Features

Mathē is a tutoring-oriented application developed as a research tool to investigate how large language models (LLMs) can support students' academic achievements and to what extent they are capable of providing pedagogically correct guidance and interactive dialogue.  

### Task Generation

Refs: `generate-assignment.usecase.ts`, `task-prompt.service.ts`, `task-formattings.service.ts`, `task-generation.service.ts`

The task generation pipeline connects the LLM with the Wolfram Alpha engine to produce mathematics tasks formatted in LaTeX. It currently supports single-choice and true-false question types. Tasks can be generated in both Czech and English.

### Tutoring Chat

Refs: `send-task-chat-message.usecase.ts`, `task-prompt.service.ts`

The tutoring chat offers a way for students to engage in a Socratic-style dialogue with the LLM. Messages can combine plain text with LaTeX formatting to represent mathematical formulas, allowing students to receive explanations and guidance.

---

## Project Structure

The `mathe-backend` is organized into several main folders, each responsible for a specific layer of the application.

### Application
The `application` folder contains the application models, dtos, which handle the data within the application layer. It also includes use-cases, which are units of logical operations responsible for the core business functionality, such as generating tasks or processing user interactions.

### Infrastructure
The `infrastructure` folder manages communication with external services, such as the Google Gemini API and the Wolfram|Alpha API. It is also responsible for handling access to the system database, ensuring that the backend can reliably store and retrieve data.

### Presentation
The `presentation` folder handles the REST API routes exposed to the client application. It includes route versioning, middlewares, and validation logic for incoming requests. This folder also contains contracts  used for structured communication with the API.

### Configuration
The `configuration` folder contains environment setup and dependency injection configuration, including the setup of the Inversify container. This ensures that services and components are properly initialized and connected throughout the backend.

### Assets
The `assets` folder stores prompts used for communication with the LLM. These prompts are structured markdown templates that guide the model.

---

## Local Development

This section describes how to set up the backend for local development. The following prerequisites are required:

- **Node.js** version `v22.1.0`  
- **Docker**

### Setup

1. **Environment Configuration**  
    Create a local environment file by copying the example:
    ```bash
    cp .env.example .env
    ```
2. **Installing Dependencies and Building**
    Install project dependencies and build the application:
    ```bash
    npm install
    npm run build
    ```
3. **Running with Docker**
    Start the required services using Docker:
    ```bash
    # Option 1: using Makefile
    make up
    
    # Option 2: using Docker Compose
    docker compose up --detach --remove-orphans
    ```
4. **Database Schema and Seeding**
    Push the database schema and populate initial data:
    ```bash
    npm run main-db:push
    npm run main-db:seed
    ```

At this point, the backend should be fully set up and ready for development or testing.

### Default Accounts

After seeding, two user accounts are available for testing purposes:

- Tutor account:
    ```
    username: tutor
    password: tutor
    ```
- Student account:
    ```
    username: student
    password: student
    ```
