added AGENTS.md and docs in root dir

2026-09-08 13:36:43 +07:00
parent 2f891c9503
commit da9e17f45f
7 changed files with 728 additions and 7 deletions
@@ -0,0 +1,85 @@
+# Архитектура Balance (обзор всей системы)
+
+Этот документ описывает, как связаны между собой три подпроекта.
+Детальная архитектура каждой платформы — в `docs/ARCHITECTURE.md`
+соответствующего подпроекта.
+
+## Общая схема
+
+```text
+┌─────────────┐   ┌─────────────┐   ┌─────────────┐
+│  iOS клиент │   │ macOS клиент│   │watchOS клиент│      Apple: SwiftUI + SwiftData
+└──────┬──────┘   └──────┬──────┘   └──────┬──────┘      (Balance/)
+       │                 │                 │
+       └────────┬────────┴────────┬────────┘
+                │                 │
+      HTTPS (или HTTP только для localhost)
+                │                 │
+       ┌────────┴────────┐        │
+       │  Android клиент │        │   Kotlin + Jetpack Compose + Room
+       │ (BalanceAndroid)│        │   (BalanceAndroid/)
+       └────────┬────────┘        │
+                │                 │
+                ▼                 ▼
+        ┌───────────────────────────────┐
+        │         BalanceServer          │   Go 1.25 + SQLite
+        │  ┌───────────┬───────────────┐ │   (BalanceServer/)
+        │  │ HTTP API  │ Web-клиент    │ │
+        │  │ /v1/*     │ (embedded)    │ │
+        │  └───────────┴───────────────┘ │
+        └───────────────────────────────┘
+```
+
+Каждый нативный клиент (iOS/macOS/watchOS/Android) хранит полную копию
+данных локально (SwiftData или Room) и работает офлайн. Сервер —
+единственная точка правды при конфликте между устройствами одного
+аккаунта: он хранит append-only лог изменений с курсором и применяет
+last-write-wins по времени изменения записи (`updatedAt`/`syncUpdatedAt`).
+
+Web-клиент не является отдельным подпроектом — это статические файлы,
+встроенные (embed) в Go-бинарник сервера, использующие тот же HTTP API,
+что и нативные клиенты, но с cookie-based сессией вместо Bearer-токена.
+
+## Компоненты сервера
+
+- **HTTP API** (`internal/httpapi/`) — auth-эндпоинты и `/v1/sync`.
+- **auth** (`internal/auth/`) — пароли (Argon2id), JWT access/refresh
+  токены.
+- **database** (`internal/database/`) — SQLite-хранилище, схема,
+  индексы.
+- **config** (`internal/config/`) — переменные окружения.
+- **web** (`internal/httpapi/web.go`) — раздача встроенного
+  web-приложения.
+
+Подробнее — [`BalanceServer/docs/ARCHITECTURE.md`](../BalanceServer/docs/ARCHITECTURE.md).
+
+## Компоненты Apple-клиента
+
+- **Models** — SwiftData `@Model` сущности.
+- **Utilities/FinanceCalculations** — единый источник правил расчёта
+  баланса и аналитики.
+- **Shared/ServerSync** — HTTP-клиент, авторизация, sync orchestration,
+  Keychain.
+- **Views** — общий SwiftUI UI; `BalanceMac/` и `BalanceWatch/` —
+  платформенно-специфичные точки входа и экраны.
+
+Подробнее — [`Balance/docs/ARCHITECTURE.md`](../Balance/docs/ARCHITECTURE.md).
+
+## Компоненты Android-клиента
+
+- **data/** — Room entities, DAO, `FinanceMath` (та же роль, что и
+  `FinanceCalculations` в Apple-клиенте).
+- **sync/** — `ServerApi` (HTTP/auth), `ServerPreferences` (URL/cursor),
+  `SecureSessionStore` (Android Keystore), `SyncRepository`
+  (orchestration), `SyncWorker` (периодический фон).
+- **ui/** — Jetpack Compose экраны, состояние из `MainViewModel`.
+
+Подробнее — [`BalanceAndroid/docs/ARCHITECTURE.md`](../BalanceAndroid/docs/ARCHITECTURE.md).
+
+## Принцип согласованности между платформами
+
+Три клиента реализуют одну и ту же доменную модель и один и тот же
+sync-протокол независимо друг от друга, на разных стеках. Это
+осознанный компромисс (нативный UX на каждой платформе) с обратной
+стороной: любое изменение общего контракта нужно вносить согласованно
+в трёх местах. См. `docs/SYNC_PROTOCOL.md` и `docs/DATA_MODEL.md`.