# Архитектура BalanceServer

## Роль сервера

BalanceServer — backend для синхронизации личных финансов между устройствами.

Поток данных:

```text
iOS/macOS/watchOS ─┐
                   ├── HTTPS/JSON API ──> BalanceServer ──> Database
Android ───────────┘
```

Сервер отвечает за:
- регистрацию и авторизацию;
- пользовательские сессии;
- хранение финансовых изменений;
- push/pull synchronization;
- глобальную последовательность изменений;
- удаление через tombstones;
- выдачу изменений начиная с cursor.

## Исходный код

Текущая кодовая база содержит 9 Go-файлов.

Пути:

```text
- internal/auth
- internal/config
- internal/database
- internal/httpapi
```

Конкретные границы package/handler/service/repository нужно сохранять при рефакторинге: перенос кода между слоями не должен менять внешний API.

## HTTP layer

HTTP layer принимает JSON requests от мобильных клиентов.

Каждый handler должен:
1. проверить method/content type;
2. аутентифицировать пользователя, если endpoint защищён;
3. валидировать input;
4. вызвать domain/storage logic;
5. вернуть стабильный JSON response.

## Domain / sync layer

Sync layer является наиболее критичной частью backend.

Он должен разделять:
- изменения, созданные текущим клиентом;
- изменения, которые нужно вернуть клиенту;
- удалённые записи;
- cursor/sequence.

Ключевая модель:

```text
client cursor
      │
      ▼
server change log
      │
      ├── sequence 101
      ├── sequence 102
      ├── sequence 103
      └── ...
```

Клиент может запросить изменения после своего cursor и затем сохранить новый cursor.

## Persistence

Хранилище должно сохранять как минимум:
- user/account identity;
- credentials/session metadata;
- financial records;
- change metadata;
- deletion/tombstone metadata;
- monotonically increasing sequence, если оно является частью текущего sync protocol.

Конкретные entities и schema документированы в `docs/DATA_MODEL.md`.

## Security boundaries

```text
Internet
   │
   ▼
HTTP server
   │
   ├── authentication
   ├── authorization
   ├── input validation
   │
   ▼
domain/sync
   │
   ▼
database
```

Нельзя позволять клиенту выбирать произвольный `user_id` для чужих records.

## Совместимость клиентов

Apple и Android реализации должны видеть одну и ту же семантику данных.

Особенно важно, чтобы:
- enum values были стабильными;
- даты имели единый формат;
- UUID/string IDs не менялись;
- `deleted` semantics были одинаковыми;
- cursor/sequence были монотонными;
- conflict resolution совпадал с клиентской логикой.