# Архитектура Security Alert Center

Дополнение к [TZ.md](TZ.md). Описывает компоненты, границы и модель данных.

---

## 1. Диаграмма компонентов

```mermaid
flowchart TB
  subgraph external [Внешние системы]
    AG_SSH[ssh-monitor]
    AG_RDP[RDP-login-monitor]
    TG[Telegram API]
    SMTP[SMTP]
  end

  subgraph sac_host [Ubuntu 24.04 — хост SAC]
    NGX[nginx TLS]
    API[FastAPI — api]
    WRK[Worker]
    FE[Static SPA]
    PG[(PostgreSQL)]
    RD[(Redis — фаза 1.5+)]
  end

  AG_SSH -->|HTTPS ingest| NGX
  AG_RDP -->|HTTPS ingest| NGX
  NGX --> API
  NGX --> FE
  API --> PG
  API --> RD
  WRK --> PG
  WRK --> RD
  WRK --> TG
  WRK --> SMTP
  FE -->|REST + SSE| NGX
```

---

## 2. Компоненты

| Компонент | Ответственность |
|-----------|-----------------|
| **nginx** | TLS, rate limit, раздача static UI, прокси `/api` → FastAPI |
| **api** | Ingest, REST для UI, auth JWT, health |
| **worker** | Правила Problems, отправка уведомлений, суточные отчёты, retention |
| **frontend** | SPA: Problems, Events, Hosts, Dashboards, Settings |
| **PostgreSQL** | События, хосты, problems, пользователи, правила, audit |
| **Redis** | Очередь задач, pub/sub для SSE (опционально) |

---

## 3. Границы контекстов

### 3.1. Агент (вне SAC)

- Чтение локальных журналов (journalctl, Security.evtx).
- Формирование JSON-события.
- Режим `UseSAC`: маршрутизация «локальные каналы» vs «только SAC».
- Локальный spool при недоступности SAC.

### 3.2. SAC

- Единственный источник доставки оповещений при `UseSAC=exclusive`.
- Дедупликация, корреляция, Problems.
- Долговременное хранение и UI.

---

## 4. Логическая модель данных

### 4.1. Сущности

```
tenants (опционально, фаза 3)
  └── hosts
        └── events (партиции по occurred_at)
  └── problems
        └── problem_events (M:N)
  └── notification_rules
  └── notification_log
  └── users
  └── audit_log
  └── api_keys (hash)
```

### 4.2. Ключевые поля

**hosts**

- `id`, `agent_instance_id` (unique), `hostname`, `display_name`
- `os_family`, `os_version`, `product` (`ssh-monitor` | `rdp-login-monitor`)
- `use_sac_mode`, `last_seen_at`, `tags[]`

**events**

- `id`, `event_id` (UUID от агента, unique), `host_id`
- `occurred_at`, `received_at`
- `category`, `type`, `severity`
- `title`, `summary`, `details` (JSONB), `raw` (JSONB/text)
- `dedup_key`, `correlation_id`

**problems**

- `id`, `title`, `severity`, `status`
- `opened_at`, `acknowledged_at`, `resolved_at`
- `rule_id`, `dedup_key`

---

## 5. API (черновой перечень)

| Метод | Путь | Назначение |
|-------|------|------------|
| POST | `/api/v1/events` | Ingest одного события |
| POST | `/api/v1/events/batch` | Batch (фаза 1.5) |
| GET | `/health` | Healthcheck |
| GET | `/api/v1/events` | Список (UI, auth) |
| GET | `/api/v1/events/{id}` | Карточка |
| GET | `/api/v1/problems` | Список Problems |
| PATCH | `/api/v1/problems/{id}` | ack / resolve |
| GET | `/api/v1/hosts` | Хосты |
| GET | `/api/v1/dashboards/summary` | Агрегаты для виджетов |
| GET | `/api/v1/stream/events` | SSE live |
| POST | `/api/v1/auth/login` | JWT |
| CRUD | `/api/v1/notification-rules` | Правила (admin) |

OpenAPI — генерируется FastAPI при реализации.

---

## 6. Каталоги репозитория (целевая структура)

```
security-alert-center/
  backend/           # FastAPI, models, services
  frontend/          # Vue SPA
  deploy/
    docker-compose.yml
    nginx/
    systemd/
  docs/              # ТЗ, планы (текущая фаза)
  schemas/           # Копия/ссылка JSON Schema
```

На фазе документации каталоги `backend/` и `frontend/` — заглушки (см. README внутри).

---

## 7. Наблюдаемость SAC

- `GET /health` — для агентов и внешнего мониторинга.
- Метрики (фаза 2): Prometheus endpoint или textfile.
- Логирование: каждый ingest (без полного `raw` в info-логах).

---

## 8. См. также

- [TZ.md](TZ.md) — требования
- [deployment.md](deployment.md) — инфраструктура Ubuntu 24.04