improve: fix README

README.md

@@ -0,0 +1,187 @@
+# 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