diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2e3d952
--- /dev/null
+++ b/README.md
@@ -0,0 +1,133 @@
+# 📂 S3 Lists Manager
+
+[![Build Status](https://gitea.example.com/api/v1/repos/user/repo/actions/runs/badge.svg)](https://gitea.example.com/user/repo/actions)
+
+Веб-интерфейс для удобного управления текстовыми файлами (`domains.txt`, `asns.txt`) в S3-совместимом хранилище Yandex Cloud. Приложение позволяет в реальном времени просматривать, добавлять, редактировать, удалять и массово изменять записи в этих файлах.
+
+## ✨ Возможности
+
+- **Два режима работы:** Управление списками доменов и AS-номеров через вкладки.
+- **CRUD операции:** Полный набор действий: создание, чтение, обновление и удаление записей.
+- **Поиск в реальном времени:** Мгновенная фильтрация списков по мере ввода.
+- **Массовая замена:** Быстрое обновление шлюзов для сотен записей в один клик.
+- **Сохранение в S3:** Все изменения сохраняются непосредственно в файлах в бакете Yandex Cloud.
+- **Docker-контейнеризация:** Готовый `Dockerfile` для сборки и запуска приложения в изолированном окружении.
+- **CI/CD с Gitea Actions:** Автоматическая сборка и публикация Docker-образа в Gitea Registry при пуше в `main`.
+
+## 🛠️ Технологический стек
+
+| Область      | Технология                                                                                                |
+|--------------|-----------------------------------------------------------------------------------------------------------|
+| **Фронтенд** | [**React**](https://reactjs.org/) + [**Vite**](https://vitejs.dev/)                                         |
+|              | [**React-Bootstrap**](https://react-bootstrap.github.io/) (UI-компоненты)                                 |
+|              | [**Axios**](https://axios-http.com/) (HTTP-клиент)                                                        |
+| **Бэкенд**   | [**Node.js**](https://nodejs.org/) + [**Express**](https://expressjs.com/)                                 |
+|              | [**AWS SDK for JS**](https://aws.amazon.com/sdk-for-javascript/) (для работы с Yandex Cloud S3)           |
+| **CI/CD**    | [**Docker**](https://www.docker.com/), [**Gitea Actions**](https://gitea.com/blog/2022/10/01/gitea-actions/) |
+
+## 🏗️ Архитектура
+
+Приложение состоит из двух основных частей: фронтенд на React и бэкенд на Node.js/Express, которые взаимодействуют через REST API.
+
+```mermaid
+graph TD
+    subgraph Browser
+        A[React Frontend]
+    end
+
+    subgraph Server
+        B(Node.js/Express API)
+    end
+
+    subgraph Yandex Cloud
+        C{S3 Bucket}
+        D1[domains.txt]
+        D2[asns.txt]
+    end
+
+    A -- HTTP Requests --> B
+    B -- AWS SDK --> C
+    C --- D1
+    C --- D2
+```
+
+## 🚀 Установка и запуск
+
+### Предварительные требования
+
+- [Node.js](https://nodejs.org/) (v18.x или выше)
+- [npm](https://www.npmjs.com/) или [yarn](https://yarnpkg.com/)
+- Доступ к бакету Yandex Cloud S3 и сервисный аккаунт с правами на чтение и запись.
+
+### 1. Настройка бэкенда
+
+1.  Перейдите в директорию `backend`:
+    ```bash
+    cd backend
+    ```
+2.  Создайте файл `.env` на основе примера `.env.example`. Заполните его вашими учетными данными от Yandex Cloud S3:
+    ```env
+    # .env
+    S3_ACCESS_KEY_ID=ВАШ_КЛЮЧ_ДОСТУПА
+    S3_SECRET_ACCESS_KEY=ВАШ_СЕКРЕТНЫЙ_КЛЮЧ
+    S3_BUCKET_NAME=ИМЯ_ВАШЕГО_БАКЕТА
+    ```
+3.  Установите зависимости:
+    ```bash
+    npm install
+    ```
+
+### 2. Настройка фронтенда
+
+1.  Перейдите в директорию `frontend`:
+    ```bash
+    cd ../frontend
+    ```
+2.  Установите зависимости:
+    ```bash
+    npm install
+    ```
+
+### 3. Запуск приложения
+
+1.  **Запустите бэкенд-сервер.** В директории `backend` выполните:
+    ```bash
+    npm start
+    ```
+    Сервер запустится на `http://localhost:3001`.
+
+2.  **Запустите фронтенд.** В новой вкладке терминала, в директории `frontend`, выполните:
+    ```bash
+    npm run dev
+    ```
+    Приложение будет доступно по адресу `http://localhost:5173` и будет автоматически проксировать API-запросы на бэкенд.
+
+## 🐳 Docker
+
+Приложение полностью готово к запуску в Docker.
+
+### Сборка образа
+
+Для сборки образа выполните команду в корневой директории проекта:
+```bash
+docker build -t s3-lists-manager .
+```
+
+### Запуск контейнера
+
+Для запуска контейнера необходимо передать переменные окружения. Это можно сделать с помощью флага `-e` или через `--env-file`.
+
+```bash
+docker run --rm -p 3001:3001 --env-file ./backend/.env s3-lists-manager
+```
+
+После этого приложение будет доступно по адресу `http://localhost:3001`.
+
+## ⚙️ API Endpoints
+
+| Метод  | Путь          | Описание                         |
+|--------|---------------|----------------------------------|
+| `GET`  | `/api/domains`| Получить список всех доменов.    |
+| `POST` | `/api/domains`| Сохранить изменения в `domains.txt`. |
+| `GET`  | `/api/asns`   | Получить список всех AS.         |
+| `POST` | `/api/asns`   | Сохранить изменения в `asns.txt`.   | 
\ No newline at end of file