acaua/docs/architecture.md

Architecture

English · Português

Acauã is a single Rust product: one daemon/CLI, one shared core, one embedded web UI and one Tauri shell. The shipped runtime has no Python and no external database. This document records the structural decisions and the six corrections applied to the original blueprint.

Stack

Layer	Choice	Why
Core, CLI and daemon	Rust 2021	One toolchain, memory safety, no runtime dependency
HTTP API	Axum + Tokio + Tower HTTP	Small async surface, easy to embed
UI	Vanilla HTML/CSS/JS	No frontend build step, assets embedded in the binary
Desktop	Tauri 2	Native window over the same UI
Analytical store	DuckDB + Parquet (optional duckdb feature)	Embedded, columnar, local-first
Scientific validation	Python in research/ only	astropy/scipy/networkx for fixtures, never shipped

The workspace has two crates: acaua-core and acaua-cli. The GUI lives in apps/gui, outside the Cargo workspace, as in Guará and Sabiá. The spec mentioned version.workspace = true for the desktop manifest; keeping the GUI outside the workspace makes that impossible, so check.sh enforces SemVer equality across Cargo.toml, acaua-cli/Cargo.toml, the desktop manifest and tauri.conf.json instead. This is a deliberate deviation, not an oversight.

Components

Zeek logs ──► acaua-core::zeek ──► normalized events ──► storage
                                      │
                                      ├──► pillar1 (beaconing)
                                      ├──► pillar2 (persistent sessions)
                                      ├──► pillar3 (protocol anomalies)
                                      └──► pillar4 (fusion) ──► alerts + evidence
                                                                    │
acaua-cli ──► axum API ──► embedded UI ◄── Tauri shell ─────────────┘

• zeek: bounded parser and path confinement. It must never follow a symlink outside the dataset root.
• storage: DuckDB/Parquet writer with a seven-day TTL. Disabled by default so the skeleton does not require a C++ build.
• pillar1–pillar4: pure functions over normalized events. They return scores plus evidence, never only a float.
• fusion: fixed-order, bounded combination. It must be symmetric and reproducible.
• doctor: local environment checks; no network calls except an explicit update check.
• update: Gitea Releases client for the CLI only.

The six corrections

1. Rayleigh/Schuster, not pure Lomb–Scargle

Event timestamps are a one-dimensional point process: there is no y value to fit. The primary periodogram is therefore Rayleigh/Schuster:

P(f) = |sum_k exp(2*pi*i*f*t_k)|^2 / N

Generalized Lomb–Scargle is used only when a real y exists (for example bytes per bucket). This avoids inventing a dependent variable and keeps the null distribution honest.

2. Bowley skew with an explicit sentinel

The Bowley coefficient uses quartiles. When Q3 == Q1, the denominator is zero; the implementation returns a documented sentinel (0.0 with an degenerate_quartiles evidence flag) instead of NaN, infinity or a panic. The sentinel is part of the alert record, not a silent fallback.

3. Jensen–Shannon, not raw KL

KL diverges when the reference distribution has a zero where the observed distribution does not. Fusion uses Jensen–Shannon, which is symmetric, bounded and defined for zero-probability bins with a small documented smoothing floor. This makes the score comparable across pillars and safe for sparse protocol histograms.

4. Persistent sessions get their own detector

A connection that stays open for hours never produces a short inter-arrival time, so a beaconing detector can miss it entirely. Pillar 2 scores duration, idle gaps and repeated long-lived flows directly. The two pillars may both fire; fusion treats that as separate evidence, not double counting of the same signal.

5. JA4 license caution

The client TLS JA4 fingerprint is usable. JA4S, JA4H, JA4X, JA4SSH and JA4L carry a non-OSI license and are not enabled by default. Any future use needs an explicit licensing decision and a documented opt-in. The default feature set must remain redistributable under MIT/Apache-2.0.

6. Determinism and per-alert JSON evidence

Every alert carries a JSON record: dataset hash, code version, pillar, inputs, intermediate values, sentinels, weights and final score. Reductions run in a fixed order; no hash-map iteration or thread scheduling may change a score. Given the same input and version, the evidence must be byte-identical.

Data flow

1. acaua analyze <dir> validates the directory, reads supported logs and normalizes events. In this skeleton it validates and returns a stub report.
2. Normalized events are written to the local store (when the duckdb feature is enabled) with a seven-day TTL.
3. Each pillar runs over a deterministic window and returns candidate scores with evidence.
4. Fusion combines candidates, applies thresholds and writes alerts.
5. serve exposes the API and the embedded UI; the Tauri shell can open the same UI against a local or remote daemon.

API

Method	Path	Purpose
GET	/api/health	Liveness and version
GET	/api/status	Uptime, data directory, pillar state
GET	/api/alerts	Paginated alerts with evidence
POST	/api/analyze	Analyze a dataset path
POST	/api/update	Check for a CLI update
GET	/logo.png	Embedded brand asset
GET	/*	Embedded UI fallback

serve binds to 127.0.0.1:8787 by default. There is no authentication layer in the skeleton; exposing it on a network interface requires an authenticating reverse proxy.

Storage

DuckDB is an optional dependency (features = ["duckdb"], bundled). The default skeleton does not compile the C++ backend. When enabled, the schema is append-only normalized events plus an alerts table, with Parquet export and a seven-day retention job. The database file lives under the configured data directory and never outside it.

Updates

update.rs queries the Gitea Releases API for the acaua repository, selects the asset for the current platform, downloads over HTTPS with curl, verifies SHA-256 and replaces the CLI binary. It refuses to update a running GUI automatically; the desktop only reports that a new version exists. This mirrors the Sabiá updater and avoids a second update mechanism.

The Tauri updater plugin, its latest.json manifest, updater.pubkey and createUpdaterArtifacts are intentionally not used: they would add a second signing and distribution path, and the desktop must not self-update. The single CLI path is easier to audit and keeps release assets to tarballs plus SHA-256.

Rejected alternatives

An earlier blueprint proposed a Python service with FastAPI and ClickHouse. Both are rejected. A Python service would add a second runtime, packaging burden and a network boundary inside a local-first tool; ClickHouse would add an external server and operational cost for datasets that fit an embedded columnar store. The product is 100% Rust, with Python confined to research/.

Deployment

• Native: cargo build --release -p acaua-cli, then acaua serve.
• Desktop: Tauri bundles for Linux and Windows, built in CI.
• Docker: a slim runtime image for lab use; see docker.md.

Failure behavior

Malformed input is skipped with a counted, bounded diagnostic. A missing log is not fatal. A corrupt store is reported by doctor and never silently recreated over existing data. A failed update leaves the current binary in place.

Versioning and compatibility

SemVer 2.0.0. Evidence JSON carries a schema version. Any change to a score or to the evidence shape is a breaking change for 0.x minor versions and must be recorded in the changelog.