hydra-architect

name	hydra-architect
description	Use when designing or evolving Hydra platform architecture across Elixir/Phoenix, SQLite, VictoriaMetrics/VictoriaLogs analytics, native/Rust, and runtime boundaries.

Hydra Architect

When to use

Use this skill for architecture/design work in Hydra:

• new subsystems and major refactors,
• data model and migration strategy,
• OTP lifecycle and process boundaries,
• reliability/operability decisions,
• implementation planning for coding agents.

Hydra-specific defaults

• Primary source of truth: SQLite via Ecto (ecto_sqlite3).
• Analytics sink: external VictoriaMetrics (route stats samples and route events over HTTP :8428) and VictoriaLogs (pipeline logs over HTTP :9428) — not transactional source of truth.
• Control plane: Elixir/Phoenix.
• Media/runtime work may involve native components and GStreamer.
• Prefer incremental evolution over big-bang rewrites.

Non-negotiable principles

1. Persist domain state in SQLite; do not store authoritative entity state in GenServers.
2. Keep side effects at boundaries; business rules stay pure when possible.
3. Use Ecto.Multi or explicit transactions for multi-step writes.
4. Design for crash recovery and idempotency in long-running/runtime workflows.
5. Every architecture change includes test strategy and rollback path.

Decision policy (context over dogma)

• Ash/Oban/Broadway are optional tools, not mandatory defaults.
• TDD is preferred for risky logic and regressions; proportionate rigor for small safe edits.
• Umbrella vs multi-app split is a tradeoff decision; do not force one style.

Architecture workflow

1. Confirm scope and constraints

• Problem, success criteria, latency/reliability targets, migration risk.

2. Map current system touchpoints

• Read impacted modules, schemas, migrations, supervisors, API handlers, and tests.
• Identify SQLite tables and any VictoriaMetrics/VictoriaLogs analytics coupling.

3. Propose 1-2 viable designs

• For each option: data flow, transaction boundaries, failure modes, observability, and cost.

4. Choose and document one design

• Record rationale and explicit tradeoffs.
• List invariants that must remain true.

5. Produce implementation plan

• Small, reversible steps with validation after each step.
• Include feature flag / staged rollout when risk is non-trivial.

SQLite guidance (Hydra)

• Treat SQLite as authoritative operational state.
• Keep migrations backward-compatible when feasible.
• Avoid lock-heavy long transactions in hot paths.
• Validate constraints at DB and changeset layers.
• For backups/restore-sensitive changes, call out integrity implications explicitly.

Victoria analytics guidance (Hydra)

• Use VictoriaMetrics for historical route stats (hydra_srt_stats_sample) and route events (hydra_srt_route_event) via Prometheus remote-write style import and PromQL/Export APIs.
• Use VictoriaLogs for pipeline log history via JSON-line ingest and LogSQL query APIs.
• Analytics writes should be resilient to delay/retry; ingestion failures must not take down control-plane operations unless explicitly required.
• VictoriaLogs retention is governed by server-side -retentionPeriod; there is no per-request delete API — plan resets around data-dir clears or retention changes.

OTP and runtime boundaries

• GenServers are for orchestration, caches, buffering, and lifecycle control.
• Domain truth lives in DB, not process memory.
• Define restart semantics per child and expected recovery behavior.
• Specify how pipeline/runtime restarts reconcile with persisted route/config state.

Required outputs for architecture tasks

For substantial architecture work, produce these artifacts (keep concise):

1. Context: problem, constraints, non-goals.
2. Option A/B: tradeoffs and failure modes.
3. Chosen design: data model, boundaries, supervision impact.
4. Plan: ordered implementation steps.
5. Validation: tests, telemetry checks, and rollback strategy.

Review checklist

• Clear ownership of authoritative state (SQLite vs in-memory vs Victoria analytics stores).
• Transaction boundaries are explicit and safe.
• Failure/retry/idempotency paths are defined.
• Migration and rollback path are realistic.
• Test plan covers regressions and concurrency-sensitive paths.
• Operational signals (logs/metrics) are sufficient for debugging.

Anti-patterns to avoid

• Treating Victoria analytics stores as system-of-record.
• Hiding domain mutations in controllers/web layer.
• Long blocking work in request path when async boundary is appropriate.
• Large refactors without staged verification.
• Architecture docs with no executable plan.