# HangmanLab Backend

This project provides the backend infrastructure for the HangmanLab application. It is built using Flask, SQLAlchemy, and other supporting libraries.

---

## Table of Contents

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Docker Deployment](#docker-deployment)
- [Usage](#usage)
- [API Endpoints](#api-endpoints)
- [Database Models](#database-models)
- [Logging](#logging)
- [License](#license)

---

## Features

- **Authentication**: JWT-based authentication integrated with Keycloak.
- **Rate Limiting**: Protects endpoints using Flask-Limiter.
- **CRUD Operations**: Manage paths, markdown files, resources, and logs.
- **Database Support**: Uses MySQL with SQLAlchemy ORM.
- **ETag Support**: Optimized response caching with ETags.
- **Modular Design**: Easy-to-extend and maintain.

---

## Requirements

- Python 3.9 or higher
- MySQL 8.0 or higher
- Keycloak for authentication
- Node.js (optional, for frontend integration)

---

## Installation

### 1. Clone the repository

```bash
git clone https://git.hangman-lab.top/hzhang/HangmanLab.Backend.git
cd hangmanlab-backend
```

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

### 3. Set up the database

Ensure you have a MySQL instance running. Update the `.env` file with the database credentials.

```bash
cp .env.example .env
```

Edit the `.env` file to configure your environment variables.

### 4. Initialize the database


## Configuration

The application uses environment variables to manage configuration. These variables are set in the `.env` file. Key variables include:

- **Database Configuration**:
  - `DB_HOST`
  - `DB_PORT`
  - `DB_NAME`
  - `DB_USER`
  - `DB_PASSWORD`
- **Keycloak Configuration**:
  - `KC_HOST`
  - `KC_REALM`
  - `KC_CLIENT_ID`
- **Other Settings**:
  - `SESSION_SECRET_KEY`
  - `FRONTEND_HOST`

---

## Usage

### Running the Application

Run the following command to start the Flask server:

```bash
python app.py
```

The server will start on `http://0.0.0.0:5000`.

### Accessing the API

All endpoints are prefixed with `/api` (e.g., `/api/path`, `/api/log`).

---

## Docker Deployment

### Image
Pull the latest Docker image from the registry
```bash
docker pull git.hangman-lab.top/hzhang/hangmanlab-backend:latest
```

### Running the Docker Container

```bash
docker run -d -p 80:80 --name hangmanlab-backend hangmanlab-backend:latest
```

---

## API Endpoints

### Path Management

- **GET** `/api/path/`: Retrieve root paths.
- **GET** `/api/path/<int:path_id>`: Retrieve a specific path.
- **POST** `/api/path/`: Create a new path.
- **PUT/PATCH** `/api/path/<int:path_id>`: Update an existing path.
- **DELETE** `/api/path/<int:path_id>`: Delete a path.

### Markdown Management

- **GET** `/api/markdown/`: Retrieve all markdown files.
- **GET** `/api/markdown/by_path/<int:path_id>`: Retrieve markdowns by path.
- **POST** `/api/markdown/`: Create a new markdown file.
- **PUT/PATCH** `/api/markdown/<int:markdown_id>`: Update an existing markdown file.
- **DELETE** `/api/markdown/<int:markdown_id>`: Delete a markdown file.

### Resource Management

- **GET** `/api/resource/<identifier>`: Retrieve a resource.
- **POST** `/api/resource/`: Create a new resource.
- **DELETE** `/api/resource/<identifier>`: Delete a resource.

### Logging

- **GET** `/api/log/`: Retrieve logs with filtering options.
- **POST** `/api/log/`: Create a new log entry.

### Configuration Management

- **GET** `/api/config/limits`: Retrieve current rate limits.
- **PUT** `/api/config/limits`: Update rate limits.

---

## Database Models

### Key Models

1. **Path**: Represents a file system path.
2. **Markdown**: Represents markdown files associated with paths.
3. **Resource**: Binary resources (e.g., images, documents).
4. **Log**: Application logs for auditing and debugging.

---

## Logging

The project uses a custom `DatabaseLogHandler` to log messages directly to the database. Logs include the following details:

- Level (e.g., INFO, ERROR)
- Message
- Timestamp
- Application name

---

## License
[MIT][license] © [hzhang][author]

<!-- Definitions -->
[author]: https://hangman-lab.top
[license]: license