# Architecture

**English** · [Português](pt-BR/arquitetura.md)

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:

```text
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](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.