---

sparc_phase: A project: <project-slug> created: <YYYY-MM-DD> author: <name> status: draft | review | approved spec_link: ./01-specification.md pseudocode_link: ./02-pseudocode.md

Architecture — Архітектура: стек, файли, інтерфейси — <Project / Feature Name>

Стек

Компонент	Технологія	Чому
Backend	Python 3.11 + FastAPI	вже у стеку, async для …
Storage	sqlite	overkill уникаємо, локальні дані …
Auth	mTLS / API key	…
Hosting	systemd unit на VPS	…

Файлова структура

/srv/projects/<slug>/
├── README.md
├── pyproject.toml
├── src/
│   ├── api.py          # HTTP endpoint(s)
│   ├── models.py       # data structures
│   ├── service.py      # бізнес-логіка
│   └── integrations/
│       └── external.py
├── tests/
│   ├── test_service.py
│   └── test_integrations.py
└── ops/
    ├── systemd-unit.service
    └── deploy.sh

Компоненти і відповідальності

• api.py — HTTP-шар. Тільки маршрутизація + валідація вхідних даних. НЕ містить бізнес-логіки.
• service.py — ядро. Pure functions де це можливо. Винятки → custom exceptions.
• integrations/external.py — обгортки навколо сторонніх API. Винятки → mapped to internal.
• models.py — pydantic / dataclass моделі. Без логіки.

Ключові інтерфейси

# service.py
class Service:
    def process(self, input: InputModel) -> ResultModel: ...
    def validate(self, x: InputModel) -> None: ...   # raises
    def persist(self, result: ResultModel) -> None: ...

Потоки даних (Data flow)

[Client] ─POST /endpoint─> [api.py validate]
                                │
                                ▼
                        [service.process]
                          │           │
                          ▼           ▼
                 [external API]  [storage]
                          │           │
                          └─────┬─────┘
                                ▼
                         [response 200]

Безпека

• Authentication: …
• Authorization: …
• Secrets management: /srv/passepartout/<area>/<name>.key
• Логування: НЕ логуємо PII / секрети. Логуємо: timestamps, request_id, status.

Деплой і інфраструктура

• systemd unit: /etc/systemd/system/<slug>.service
• Reverse proxy: Caddy /etc/caddy/conf.d/<slug>.caddy → 127.0.0.1:<port>
• Logs: journalctl -u <slug>
• Healthcheck: GET /health → 200 з версією
• Rollback стратегія: backup файлу <file>.bak-<timestamp>, swap при потребі

Спостережуваність

• Метрики (якщо релевантно): які, де читаємо
• Алерти: на які події → куди (Telegram / email)

Відкриті питання

1. …

Sign-off

• [ ] Сергій schválив архітектуру
• [ ] Дата approval: <YYYY-MM-DD>
• [ ] Перехід на наступну фазу: R (Refinement)