128 lines
3.5 KiB
Markdown
128 lines
3.5 KiB
Markdown
# Architecture Decision Records
|
||
|
||
**Версия:** 0.1.0-draft | **Статус:** Draft
|
||
|
||
## Шаблон ADR
|
||
|
||
```markdown
|
||
# ADR-NNN: Краткое название
|
||
|
||
**Статус:** proposed | accepted | deprecated | superseded
|
||
**Дата:** YYYY-MM-DD
|
||
**Владельцы:** @username
|
||
**Связано:** OQ-XXX, FR-XXX, NFR-XXX
|
||
|
||
## Контекст
|
||
|
||
Описание проблемы, требующей архитектурного решения. Какие силы действуют?
|
||
Какие ограничения?
|
||
|
||
## Варианты и анализ
|
||
|
||
### Вариант A: Название
|
||
- **Плюсы:** ...
|
||
- **Минусы:** ...
|
||
- **Риски:** ...
|
||
|
||
### Вариант B: Название
|
||
- **Плюсы:** ...
|
||
- **Минусы:** ...
|
||
|
||
## Решение
|
||
|
||
Выбран **Вариант X** потому что ...
|
||
|
||
## Последствия
|
||
|
||
### Положительные
|
||
- ...
|
||
|
||
### Отрицательные
|
||
- ...
|
||
|
||
### Безопасность и приватность
|
||
- ...
|
||
|
||
### Операционные
|
||
- ...
|
||
|
||
## Миграция и откат
|
||
|
||
Как перейти от текущего состояния к новому? Как откатиться?
|
||
|
||
## Валидация
|
||
|
||
Как проверить, что решение работает?
|
||
```
|
||
|
||
## Каталог ADR
|
||
|
||
| Номер | Название | Статус | Дата |
|
||
|---|---|---|---|
|
||
| ADR-001 | Client stack: React + Tauri + Capacitor | proposed | — |
|
||
| ADR-002 | Auth: OIDC + local bootstrap | proposed | — |
|
||
| ADR-003 | Persistence: PostgreSQL + Object Storage | proposed | — |
|
||
| ADR-004 | WSS transport for Connector | proposed | — |
|
||
| ADR-005 | Adapter pattern: versioned, capability-based | proposed | — |
|
||
| ADR-006 | Handoff format: JSON Schema v1 | proposed | — |
|
||
| ADR-007 | Event Bus: PostgreSQL NOTIFY/LISTEN vs Redis | proposed | — |
|
||
| ADR-008 | Memory embeddings: pgvector vs external | proposed | — |
|
||
| ADR-009 | Connector sandbox: container vs systemd | proposed | — |
|
||
| ADR-010 | API versioning: URL-based (/v1, /v2) | proposed | — |
|
||
|
||
## Sequence Diagrams (текстовые)
|
||
|
||
### Запуск проекта (happy path)
|
||
|
||
```
|
||
User → API: POST /projects (name, workspace)
|
||
API → DB: INSERT project
|
||
API → User: 201 { project_id }
|
||
|
||
User → API: POST /tasks (project_id, title)
|
||
API → Scheduler: enqueue(task)
|
||
Scheduler → Connector: create_run(agent, goal)
|
||
Connector → Agent: run(goal)
|
||
Agent → Connector: stream_events(...)
|
||
Connector → API: stream_events(...)
|
||
API → User: WSS push events
|
||
Agent → Connector: run_completed
|
||
Connector → API: run_completed
|
||
API → User: notification
|
||
```
|
||
|
||
### Handoff
|
||
|
||
```
|
||
Agent_A → Connector_A: handoff(agent_B, bundle)
|
||
Connector_A → API: handoff_request
|
||
API → Scheduler: enqueue(agent_B, bundle)
|
||
Scheduler → Connector_B: create_run(agent_B, bundle)
|
||
Agent_B → Connector_B: run_accepted
|
||
Connector_B → API: handoff_ack
|
||
API → Connector_A: handoff_ack
|
||
```
|
||
|
||
### Approval
|
||
|
||
```
|
||
Agent → Connector: approval_request(action="rm -rf /build", risk=high)
|
||
Connector → API: approval_request
|
||
API → EventBus: approval.requested
|
||
EventBus → User: push notification
|
||
User → API: POST /approvals/{id}/approve
|
||
API → Connector: approval_granted
|
||
Connector → Agent: continue
|
||
Agent → Connector: action_executed
|
||
```
|
||
|
||
### Восстановление после reconnect
|
||
|
||
```
|
||
Connector → API: register (reconnect)
|
||
API → Connector: register_ack + pending_commands[]
|
||
Connector → Agent: resume(run_id)
|
||
Agent → Connector: stream_events (с последнего checkpoint)
|
||
Connector → API: stream_events
|
||
API → User: events replayed
|
||
```
|