Balance/docs/ARCHITECTURE.md

Архитектура Balance (обзор всей системы)

Этот документ описывает, как связаны между собой три подпроекта. Детальная архитектура каждой платформы — в docs/ARCHITECTURE.md соответствующего подпроекта.

Общая схема

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  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.

Компоненты Apple-клиента

• Models — SwiftData @Model сущности.
• Utilities/FinanceCalculations — единый источник правил расчёта баланса и аналитики.
• Shared/ServerSync — HTTP-клиент, авторизация, sync orchestration, Keychain.
• Views — общий SwiftUI UI; BalanceMac/ и BalanceWatch/ — платформенно-специфичные точки входа и экраны.

Подробнее — 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.

Принцип согласованности между платформами

Три клиента реализуют одну и ту же доменную модель и один и тот же sync-протокол независимо друг от друга, на разных стеках. Это осознанный компромисс (нативный UX на каждой платформе) с обратной стороной: любое изменение общего контракта нужно вносить согласованно в трёх местах. См. docs/SYNC_PROTOCOL.md и docs/DATA_MODEL.md.