chore: Описание технических требований в README

README.md

@@ -1,9 +1,72 @@
-<div align="center">
-    <h1>
-        p1ctos4ve
-    </h1>
-    <p>
-        selfhosted image preservation service
-    </p>
-</div>
+# p1ctos4ve
+Проект в рамках дисциплины «Конструирование программного обеспечения»: сервис сохранения и организации медиа со внешних ресурсов
 
+## Участники
+- Железняков Марк Викторович - `5130904/30105`
+- Михеев Егор Романович - `5130904/30105`
+- Михальченко Владислав Сергеевич - `5130904/30105`
+- Ботыгин Иван Алексеевич - `5130904/30105`
+
+## Определение проблемы
+Пользователи, сохраняющие большое количество медиафайлов (фотографий, видео, GIF) из разных источников (социальные сети, мессенджеры и другие специализированные платформы), сталкиваются с трудностями их систематизации и последующего поиска. Файлы скапливаются в беспорядке, отсутствует единая система тегов и категорий, что делает быстрый поиск нужного материала практически невозможным и требует значительных ручных усилий по организации. При этом всегда присутствует риск удаления материалов из первоисточника.
+
+## Выработка требований
+
+### Пользовательские истории
+1. Как пользователь, я хочу добавлять медиафайлы (фото, видео, GIF) в свою библиотеку из различных источников (прямая загрузка, по ссылке, через интеграцию с Tenor/Pinterest), чтобы централизованно хранить все материалы.
+2. Как пользователь, я хочу иметь мощную систему поиска по библиотеке с фильтрацией по типу файла, тегам, категориям и дате добавления, чтобы быстро находить конкретные материалы.
+3. Как пользователь, я хочу иметь возможность просматривать свою медиатеку в удобном интерфейсе (галерея, список) с предпросмотром, чтобы легко ориентироваться в содержимом.
+
+## Разработка архитектуры и детальное проектирование
+
+### Оценка масштаба
+> Оценка масштаба производится при условии нагрузки на сервис в размере 10 000 активных пользователей в сутки. При этом сервис подазумевает опцию селфхостинга, что может снизить требования к ресурсам центрального экземпляра (инстанса) сервиса.
+
+#### Характер нагрузки
+
+##### Соотношение R/W нагрузки
+**70% на чтение и 30% на запись.** Обосновать это можно тем, что запись метаданных и загрузка файлов будет занимать большую долю операций в сервисе с пиками во время массовых импортов из Tenor/Pinterest. При этом чтение данных будет производится сильно реже
+
+##### Трафик
+Для входящего трафика предположим, что один пользователь в среднем будем генерировать 10 МБ данных. Так, 10 000 пользователей * 10 МБ = 100 ГБ/день.
+
+##### Объемы дисковой системы
+При начальном размере файла ~5 МБ и 10 загрузках на пользователя в день: 10 000 * 10 * 5 МБ = 500 ГБ/день. Поэтому может потребоваться дешевое S3-хранилище.
+
+### Диаграммы C4 Model
+
+#### Контекст
+![[assets/С4-1context.jpg]]
+
+#### Контейнеры
+![[assets/С4-2containers.jpg]]
+
+#### Компоненты
+![[С4-3components.jpg]]
+
+#### Код
+> WIP
+
+### Контракты API
+Краткая информация о методах API доступна в [assets/API.md](API.md), а полная документация - в [Scalar](https://scalar.com/) на эндпоинте `/openapi`.
+
+### Схема БД и оправдание с точки зрения нефункциональных требований
+> WIP
+
+### Схема масштабирования сервиса при росте нагрузки в 10 раз
+Для возможности масштабирования можно использовать следующие подходы:
+- Размещение бекенда за балансировщиком нагрузки (например, Nginx, Traefik или Caddy): трафик будет распределяться равномерно между двумя или более экземплярами API
+- Репликация БД - основная база принимает запись, а одна или несколько реплик получают изменения по журналу (WAL) и обслуживают преимущественно чтение.
+- Кеширование частозапрашиваемых данных через Redis: результаты чтения (например, списки, карточки по ID, агрегации, результаты поиска с популярными фильтрами) складываются в KV хранилище с некоторым TTL, что позволяет сократить время ответа на повторяющиеся запросы
+
+## Кодирование и отладка
+> WIP
+
+## Unit-тестирование
+> WIP
+
+## Интеграционное тестирование
+> WIP
+
+## Сборка и запуск
+> WIP