docs: initial project documentation

- architecture overview and stack
- project structure and development order
- API design (endpoints, models, runtimes)
- infrastructure overview (k8s cluster, S3, registry)
- decisions log with rationale
- progress tracker v1/v2

doc/architecture/overview.md

@@ -0,0 +1,64 @@
+# Архитектура системы
+
+## Общее описание
+
+Managed Serverless Functions Service для облачного провайдера nubes.ru.
+Пользователь загружает код, сервис его собирает и запускает по HTTP-триггеру или расписанию.
+
+## Стек
+
+| Компонент | Технология | Где запущен |
+|-----------|-----------|-------------|
+| API сервер | Go | Kubernetes, namespace `sless` |
+| PostgreSQL | PostgreSQL | Kubernetes, namespace `sless` |
+| Redis | Redis | Kubernetes, namespace `sless` |
+| RabbitMQ | RabbitMQ | Kubernetes, namespace `sless` (позже) |
+| S3 | Ceph (облачный) | `ceph.tst.nubes.ru` |
+| Container Registry | Внутренний registry кластера | namespace `registry` |
+| Функции пользователей | k8s Jobs/Deployments | namespace `sless-fn-{id}` |
+
+## Схема
+
+```
+Пользователь
+    │
+    ▼
+REST API (Go)  ←── Terraform provider
+    │
+    ├── PostgreSQL   — метаданные функций, версии, логи вызовов
+    ├── S3 (Ceph)    — хранение кода (zip архивы)
+    ├── Redis        — кеш, rate limiting
+    │
+    ▼
+Builder         — получает zip из S3, собирает Docker образ, пушит в registry
+    │
+    ▼
+Runner (k8s)    — деплоит функцию как Job/Deployment в k8s
+    │
+    ▼
+RabbitMQ        — async вызовы, cron triggers (v2)
+```
+
+## Аутентификация
+
+Используется токен облака (Bearer token), который пользователь получает в UI облака.
+Terraform provider передаёт его в заголовке `Authorization: Bearer <token>`.
+Keycloak не используется.
+
+## Мониторинг
+
+Метрики функций → Victoria Metrics / Grafana (уже есть в облаке).
+Grafana: https://grafana.ngcloud.ru/dashboards/...
+
+## Kubernetes кластер
+
+Сейчас используется существующий кластер (временно).
+Планируется переезд на новый кластер — манифесты переносятся без изменений.
+
+Ноды существующего кластера:
+- `wheel-control-plane-fm9sr` — control-plane
+- `wheel-workers-tv4qr-r45xs` — worker
+- `wheel-workers-tv4qr-x8xw7` — worker
+
+Ingress: nginx, external IP `5.172.178.182`
+Storage: rawfile CSI (local-path, default)

doc/architecture/project-structure.md

@@ -0,0 +1,49 @@
+# Структура проекта
+
+## Репозиторий
+
+`gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless`
+
+## Директории
+
+```
+sless/
+├── cmd/
+│   └── api/
+│       └── main.go          # точка входа API сервера
+├── internal/
+│   ├── api/
+│   │   ├── handler/         # HTTP хендлеры (functions, versions, triggers)
+│   │   ├── middleware/      # auth, logging, rate limit
+│   │   └── router.go        # регистрация маршрутов
+│   ├── model/               # доменные модели: Function, Version, Trigger, Invocation
+│   ├── storage/
+│   │   ├── postgres/        # CRUD функций, версий, логов вызовов
+│   │   └── s3/              # загрузка/скачивание zip архивов кода
+│   ├── builder/             # сборка Docker образа из кода пользователя
+│   ├── runner/              # запуск функций в k8s (Jobs / Deployments)
+│   └── config/              # конфиг из env переменных
+├── migrations/              # SQL миграции (numbered: 001_, 002_, ...)
+├── deployments/
+│   └── k8s/                 # манифесты: Deployment, Service, Ingress, RBAC
+├── api/
+│   └── openapi.yaml         # OpenAPI 3.0 спецификация
+├── doc/                     # документация проекта (эта папка)
+└── docker-compose.yml       # локальная разработка: postgres, redis, minio
+```
+
+## Go module
+
+```
+module gitea-naeel.giteak8s.services.ngcloud.ru/naeel/sless
+```
+
+## Порядок разработки
+
+1. `internal/config` + `internal/model` — базовые структуры данных
+2. `migrations/` + `internal/storage/postgres` — схема БД и CRUD
+3. `internal/api` — HTTP хендлеры, роутер, middleware
+4. `internal/storage/s3` — загрузка кода функций
+5. `internal/builder` — сборка Docker образов
+6. `internal/runner` — запуск функций в k8s
+7. `deployments/k8s` — манифесты для деплоя