diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b4d92fd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,60 @@
+# rest-api.ir
+
+## Introduction
+This project is a small web service developed primarily for learning and experimentation, and is still evolving. The goal is to provide a simple executable that can launch a local REST API with minimal setup. If you have ideas or suggestions, I'd be happy to receive pull requests.
+
+## Features
+- **Single Binary Execution**: Simply run `cargo run` or execute the output binary to start all Axum routes with default configurations—no additional tools required. The application listens on `APP_HOST:APP_PORT` and displays the configured domain in the output if set.
+- **Automatic Configuration Generation**: If no `.env` file exists, the application automatically creates one with default values including network settings and SQLite database configuration, allowing you to run immediately without hassle.
+- **Ready-to-Use Utility Routes**: A collection of `/api/v1` endpoints including time, IP detection, and country lists with flags, alongside a health check endpoint—suitable for testing or building widgets.
+- **Structured Responses**: All responses follow the `ApiResponse` structure, providing JSON data with predictable error messages.
+- **Request Statistics**: An in-memory counter tracks requests and persists them to the database every 60 seconds, showing usage metrics for each route.
+
+## Prerequisites
+- Rust installation (recent stable version recommended)
+- SQLite, used through the SeaORM driver—no separate installation needed unless you require command-line tools
+
+## Quick Start
+1. Clone the repository and navigate into it
+2. For first-time execution, the following command is sufficient to install dependencies and automatically create the database:
+   ```bash
+   cargo run
+   ```
+3. The service will be available at `http://127.0.0.1:8080` (or values specified in `.env`)
+
+On first run, a `.env` file is created with the following default values, which you can modify as needed:
+```env
+APP_DOMAIN=localhost
+APP_FINAL_DOMAIN=localhost
+APP_HOST=127.0.0.1
+APP_PORT=80
+APP_HTTPS=false
+DATABASE_URL=sqlite://stats.db?mode=rwc
+```
+
+## Configuration
+- `APP_HOST` and `APP_PORT`: Specify the address and port for the service to listen on
+- `APP_DOMAIN`: If present, displayed in startup logs to indicate if the service is behind a proxy or specific domain
+- `DATABASE_URL`: SeaORM connection string; defaults to creating a local SQLite file
+
+## Main Routes
+| Route | Description | Example |
+| --- | --- | --- |
+| `/health` | Service status, uptime, and usage statistics | `GET /health` |
+| `/api/v1/time` | Current UTC time | `GET /api/v1/time` |
+| `/api/v1/time/{region}/{city}` | Local time with custom timezone | `GET /api/v1/time/asia/tehran` |
+| `/api/v1/ip` | Client IP detection from common headers | `GET /api/v1/ip` |
+| `/api/v1/country` | List of country codes and names | `GET /api/v1/country` |
+| `/api/v1/country/full` | Complete country information including currency, language, and flag | `GET /api/v1/country/full` |
+| `/api/v1/flags/{code}` | Retrieve flag SVG file by two-letter country code | `GET /api/v1/flags/ir.svg` |
+
+## Build and Deployment
+- To build a production-ready release:
+  ```bash
+  cargo build --release
+  ```
+  The executable will be located at `target/release/rest-api.ir` and can be run on any Linux server with appropriate environment variables configured.
+- Database migrations are managed through the `migration` subproject. They run via `cargo run` in the main directory and are automatically applied during application startup.
+
+## Contributing
+This project is a work in progress focused on learning and growth. If you encounter bugs, have ideas, or want to propose new routes, please open an issue or submit a pull request. I welcome constructive feedback and suggestions.