CreatmanCEO · CreatmanCEO · May 6, 2026 · May 5, 2026
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -0,0 +1,38 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Required meta files exist
+        run: |
+          test -f LICENSE
+          test -f README.md
+          test -f README.ru.md
+          test -f CHANGELOG.md
+          test -f CONTRIBUTING.md
+          test -f docs/architecture.svg
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Syntax-check any Python in app/
+        run: |
+          if [ -d app ]; then
+            python - <<'PY'
+          import compileall, sys
+          ok = compileall.compile_dir('app', quiet=1, force=True)
+          sys.exit(0 if ok else 1)
+          PY
+          else
+            echo "no app/ dir, skipping"
+          fi
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this repository will be documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Note: this is the public surface of a commercial product. Versioning here tracks public docs and scaffolding, not the proprietary runtime.
+
+## [Unreleased]
+
+### Added
+- Commercial LICENSE (replaces empty file).
+- README rewrite (EN + RU), CHANGELOG, CONTRIBUTING, validate CI workflow, architecture diagram.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,20 @@
+# Contributing
+
+Thanks for your interest. This is a small project — keep contributions focused.
+
+## Workflow
+
+1. Open an issue describing the change before sending a PR for anything non-trivial.
+2. Fork, branch from `main`, keep commits small and message-clear.
+3. Run the project's lint/test commands locally before pushing.
+4. PRs should target `main` and explain the *why*, not just the *what*.
+
+## Style
+
+- No drive-by formatting changes mixed with logic changes.
+- Add or update tests for behavior changes.
+- Prefer clarity over cleverness.
+
+## Reporting bugs
+
+Include reproduction steps, expected vs actual behavior, environment (OS, runtime version), and logs if relevant.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,35 @@
+COMMERCIAL LICENSE
+
+Copyright (c) 2026 Nick Podolyak (CreatmanCEO)
+
+All rights reserved.
+
+This repository contains documentation, configuration scaffolding, and
+showcase materials for RentScout — a commercial rental-data aggregation
+API. The runnable production codebase, parser internals, anti-detection
+logic, and deployment configuration are proprietary.
+
+TERMS AND CONDITIONS
+
+1. This repository is provided for evaluation, demonstration, and
+   portfolio purposes only.
+
+2. No license is granted, expressed or implied, to use, copy, modify,
+   distribute, sublicense, or create derivative works from any portion
+   of RentScout, including its source code, schemas, parser logic,
+   filter definitions, or operational configuration.
+
+3. Documentation and examples in this repository may be viewed and
+   referenced by prospective clients and collaborators. They may not
+   be reproduced for commercial use.
+
+4. RentScout was developed as commissioned and independent commercial
+   work and remains the intellectual property of its rightful owner(s).
+
+5. No warranty is provided. The materials are made available "AS IS".
+
+For commercial inquiries, licensing, or similar projects, contact:
+
+  Email:    creatmanick@gmail.com
+  Site:     https://creatman.site
+  Telegram: @Creatman_it
diff --git a/README.md b/README.md
@@ -1,118 +1,67 @@
-# RentScout: Your Reliable Rental Data Aggregator 🌍🏠
+# RentScout
 
-![RentScout Logo](https://img.shields.io/badge/RentScout-API-blue?style=for-the-badge&logo=appveyor)
+[![License](https://img.shields.io/badge/license-Commercial-orange.svg)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/CreatmanCEO/rentscout?style=flat)](https://github.com/CreatmanCEO/rentscout/stargazers)
+[![Validate](https://github.com/CreatmanCEO/rentscout/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/rentscout/actions/workflows/validate.yml)
+![Status](https://img.shields.io/badge/status-commercial-orange)
+![Platform](https://img.shields.io/badge/platform-Python%20%7C%20FastAPI-009688?logo=fastapi&logoColor=white)
 
-Welcome to **RentScout**, a high-performance API designed for aggregating rental data from leading platforms. Whether you're a developer looking to integrate rental data into your application or a researcher seeking insights into housing trends, RentScout provides the tools you need.
+[Русская версия](README.ru.md)
 
-## Table of Contents
+> **Commercial product. This repository hosts the public surface — README, API docs, configuration scaffolding. Parser internals and operational pieces are proprietary.**
 
-- [Features](#features)
-- [Getting Started](#getting-started)
-- [Installation](#installation)
-- [Usage](#usage)
-- [API Endpoints](#api-endpoints)
-- [Contributing](#contributing)
-- [License](#license)
-- [Contact](#contact)
-- [Releases](#releases)
+RentScout is a FastAPI service that aggregates Russian rental and short-term-stay listings from Avito, Cian, Yandex Travel, Sutochno, Ostrovok, Otello, and Tvil into a single normalized API. It is built for back-office tooling, market research, and client-facing rental dashboards that need one schema across many sources.
 
-## Features
+## Why this exists
 
-- **Data Aggregation**: Collects rental data from multiple sources including Avito, Cian, and Yandex.
-- **FastAPI**: Built on FastAPI for high performance and ease of use.
-- **Docker Support**: Easily deploy with Docker and Docker Compose.
-- **Real-time Data**: Get the latest rental listings as they become available.
-- **Redis Caching**: Fast access to frequently requested data.
-- **SQL Database**: Store and query data efficiently.
+Each rental platform exposes a different schema, different filter vocabulary, and different anti-bot posture. Stitching them together inside a downstream app means writing seven adapters, seven cache strategies, and seven bug surfaces. RentScout collapses that into one HTTP API: same query, same response shape, same SLA assumptions.
 
-## Getting Started
+## How it works
 
-To start using RentScout, follow the instructions below. Make sure you have the necessary tools installed, including Docker and Docker Compose.
+1. **API** — FastAPI receives a search query (geo, dates, price band, room count, source filter).
+2. **Search service** plans which parsers to run in parallel and merges their results.
+3. **Parsers** — per-source modules (`app/parsers/<source>`) for Avito, Cian, Yandex Travel, Sutochno, Ostrovok, Otello, Tvil.
+4. **Cache** — Redis-backed layer keyed by query fingerprint to absorb repeat traffic.
+5. **Filter** service applies post-fetch normalization and dedupes near-identical listings.
+6. **Storage** — SQLAlchemy + Alembic schema for persistent listings, run history, and audit.
+7. **Telegram bot** (optional) exposes the same data to operators for alerts and ad-hoc queries.
 
-### Prerequisites
+See [`docs/architecture.svg`](docs/architecture.svg) and [`docs/API.md`](docs/API.md).
 
-- Docker
-- Docker Compose
-- Python 3.7 or higher
+## Tech stack
 
-## Installation
+| Layer | Tools |
+|---|---|
+| API | FastAPI, Uvicorn |
+| Async parsing | httpx, asyncio |
+| HTML | lxml / BeautifulSoup |
+| DB | PostgreSQL + SQLAlchemy + Alembic |
+| Cache | Redis |
+| Tasks | APScheduler / background tasks |
+| Bot | aiogram (operator interface) |
+| Deploy | Docker, docker-compose |
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/Soasu/rentscout.git
-   cd rentscout
-   ```
+## API surface (excerpt)
 
-2. Build and run the Docker containers:
-   ```bash
-   docker-compose up --build
-   ```
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | liveness |
+| `GET` | `/v1/search` | unified search across configured sources |
+| `GET` | `/v1/sources` | enabled parsers and their capabilities |
+| `GET` | `/v1/listing/{id}` | single normalized listing |
 
-3. Access the API at `http://localhost:8000`.
+Full reference: [`docs/API.md`](docs/API.md).
 
-## Usage
+## Limitations
 
-After starting the API, you can use it to access rental data. Below are examples of how to make requests.
+- Public repo is **not a runnable product**. Some directories (`app/`, `docker/`, `scripts/`) hold scaffolding; production parsers and ops live elsewhere.
+- Source platforms change HTML and anti-bot defenses frequently — production maintenance is a paid service, not a community one.
+- Geo coverage is Russia-centric; international rentals are not in scope.
+- Rate, freshness, and uptime targets are negotiated per deployment; no public SLA.
+- Some parsers depend on residential-quality proxies; without them, request success drops sharply.
 
-### Example Request
+## Inquiries
 
-To get rental listings, send a GET request to the following endpoint:
+Commercial inquiries, integrations, custom parsers: **creatmanick@gmail.com** · [creatman.site](https://creatman.site).
 
-```http
-GET /api/rentals
-```
-
-### Example Response
-
-You will receive a JSON response containing rental listings:
-
-```json
-{
-  "listings": [
-    {
-      "id": 1,
-      "title": "2-bedroom apartment in the city center",
-      "price": 1500,
-      "source": "Avito"
-    },
-    ...
-  ]
-}
-```
-
-## API Endpoints
-
-Here are some key API endpoints you can use:
-
-- **Get all rentals**: `GET /api/rentals`
-- **Get rental by ID**: `GET /api/rentals/{id}`
-- **Search rentals**: `GET /api/rentals/search?query={search_term}`
-
-## Contributing
-
-We welcome contributions to RentScout! If you have ideas for improvements or new features, feel free to submit a pull request. 
-
-1. Fork the repository.
-2. Create a new branch.
-3. Make your changes.
-4. Submit a pull request.
-
-## License
-
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
-
-## Contact
-
-For any questions or feedback, please reach out to us via GitHub issues or directly through our contact page.
-
-## Releases
-
-You can find the latest releases of RentScout [here](https://github.com/Soasu/rentscout/releases). Download the latest version and execute it to get started with the API.
-
-![Releases Button](https://img.shields.io/badge/Latest_Releases-orange?style=for-the-badge)
-
-Visit the [Releases](https://github.com/Soasu/rentscout/releases) section for more information.
-
----
-
-Thank you for choosing RentScout! We hope you find it useful for your rental data needs.
+EOF
diff --git a/README.ru.md b/README.ru.md
@@ -0,0 +1,74 @@
+# RentScout
+
+[![License](https://img.shields.io/badge/license-Commercial-orange.svg)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/CreatmanCEO/rentscout?style=flat)](https://github.com/CreatmanCEO/rentscout/stargazers)
+[![Validate](https://github.com/CreatmanCEO/rentscout/actions/workflows/validate.yml/badge.svg)](https://github.com/CreatmanCEO/rentscout/actions/workflows/validate.yml)
+![Status](https://img.shields.io/badge/status-commercial-orange)
+![Platform](https://img.shields.io/badge/platform-Python%20%7C%20FastAPI-009688?logo=fastapi&logoColor=white)
+
+[English version](README.md)
+
+> **Коммерческий продукт. В этом репозитории — публичная витрина: README, документация API, каркас конфигурации. Внутренности парсеров и эксплуатационные части проприетарны.**
+
+RentScout — сервис на FastAPI, который агрегирует объявления аренды и краткосрочного проживания с Avito, Cian, Яндекс Путешествий, Суточно, Ostrovok, Otello и Tvil в единый нормализованный API. Делается под бэк-офис, маркет-рисёрч и клиентские дашборды, которым нужна одна схема для многих источников.
+
+## Зачем
+
+У каждой площадки своя схема, свой словарь фильтров и свой анти-бот. Собирать всё это внутри даунстрим-приложения — значит писать семь адаптеров, семь стратегий кеша и семь источников багов. RentScout сворачивает это в один HTTP API: один запрос, один формат ответа, одни допущения по SLA.
+
+## Как устроено
+
+1. **API** — FastAPI принимает запрос (гео, даты, цена, комнаты, фильтр по источникам).
+2. **Search service** планирует параллельный запуск парсеров и сливает результаты.
+3. **Парсеры** — модули `app/parsers/<source>` для Avito, Cian, Яндекс Путешествий, Суточно, Ostrovok, Otello, Tvil.
+4. **Кеш** — Redis по отпечатку запроса для повторного трафика.
+5. **Фильтрация** — нормализация и дедуп близких дублей после выдачи.
+6. **Хранилище** — SQLAlchemy + Alembic для объявлений, истории, аудита.
+7. **Telegram-бот** (опционально) даёт оператору тот же доступ для алертов и ad-hoc запросов.
+
+См. [`docs/architecture.svg`](docs/architecture.svg) и [`docs/API.md`](docs/API.md).
+
+## Стек
+
+| Слой | Инструменты |
+|---|---|
+| API | FastAPI, Uvicorn |
+| Async парсинг | httpx, asyncio |
+| HTML | lxml / BeautifulSoup |
+| БД | PostgreSQL + SQLAlchemy + Alembic |
+| Кеш | Redis |
+| Задачи | APScheduler / background tasks |
+| Бот | aiogram (операторский интерфейс) |
+| Деплой | Docker, docker-compose |
+
+## API (фрагмент)
+
+| Метод | Путь | Описание |
+|---|---|---|
+| `GET` | `/health` | liveness |
+| `GET` | `/v1/search` | единый поиск по подключённым источникам |
+| `GET` | `/v1/sources` | подключённые парсеры и их возможности |
+| `GET` | `/v1/listing/{id}` | нормализованное объявление |
+
+Полная справка: [`docs/API.md`](docs/API.md).
+
+## Ограничения
+
+- Публичный репозиторий **не рабочий продукт целиком**. Часть директорий (`app/`, `docker/`, `scripts/`) — каркас; продовые парсеры и ops живут отдельно.
+- HTML и анти-бот площадок меняются часто — поддержка платная, не комьюнити.
+- Гео — Россия; зарубежная аренда вне рамок.
+- Свежесть, аптайм и rate согласуются по контракту, публичного SLA нет.
+- Некоторые парсеры требуют резидентных прокси; без них success rate резко падает.
+
+## Связаться
+
+Коммерческие запросы, интеграции, кастомные парсеры: **creatmanick@gmail.com** · [creatman.site](https://creatman.site).
+
+## Автор
+
+**Николай Подоляк** — независимый разработчик, автоматизация и интеграция AI.
+
+- GitHub: [@CreatmanCEO](https://github.com/CreatmanCEO)
+- Habr: [creatman](https://habr.com/ru/users/creatman/)
+- Telegram: [@Creatman_it](https://t.me/Creatman_it)
+- Сайт: [creatman.site](https://creatman.site)