# Architecture

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

Acauã is a single Rust product: one daemon/CLI, one shared core, and one
embedded web dashboard. 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 (MSRV 1.88) | One toolchain, memory safety, no runtime dependency |
| HTTP API | Axum + Tokio + Tower HTTP | Small async surface, easy to embed |
| Web Dashboard | Vanilla HTML/CSS/JS | No frontend build step, assets embedded in the binary via `rust-embed` |
| Analytical store | DuckDB + Parquet | Mandatory embedded columnar store, linked to official prebuilt `libduckdb.so` |
| Deployment | Docker / docker-compose | Collective SOC daemon, unprivileged non-root user, read-only rootfs |
| Scientific validation | Python in `research/` only | astropy/scipy/networkx for fixtures, never shipped |

The workspace has two crates: `acaua-core` and `acaua-cli`. Both use `version.workspace = true`.

## Components

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

- `zeek`: bounded parser and path confinement. It must never follow a symlink
  outside the dataset root.
- `storage`: DuckDB in-memory engine over daily partitioned Parquet files with a
  seven-day TTL.
- `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; reports prebuilt DuckDB linkage and
  containerized Zeek status.
- `update`: checks for updates against the Gitea Releases API.

## 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(T) = (2 / N) * [ (sum cos(2*pi*t_i / T))^2 + (sum sin(2*pi*t_i / T))^2 ]
```

Generalized Lomb–Scargle is reserved for the future extension that evaluates a
real response attribute (such as payload size or duration) against time.

### 2. Guard the zero-dispersion case in MADM

A synthetic or unjittered beacon produces equal intervals. The median absolute
deviation from the median (MADM) is then `0.0`. Dividing by `0.0` or treating it
as a missing value is wrong: zero dispersion is the most suspicious outcome. The
implementation guards this case with an explicit score assignment (`1.0`) and a
documented sentinel.

### 3. Replace Pearson skewness with Bowley skewness

Sample skewness based on the third central moment is sensitive to single
outliers and can diverge. Bowley skewness uses quartiles:

```text
B = (Q3 + Q1 - 2*Q2) / (Q3 - Q1)
```

It is bounded in `[-1.0, 1.0]` by definition and resistant to extreme outliers.
When `Q3 == Q1` (concentrated data), the implementation assigns `0.0` with a
sentinel flag.

### 4. Isolate the Python research workspace

`research/` has its own virtual environment and dependencies. It is excluded
from the Cargo workspace, ignored by Docker builds and CI releases, and tested
only when research validation scripts are invoked directly.

### 5. Documented degraded mode for NetFlow/IPFIX

NetFlow v9 and IPFIX do not carry DNS query names, TLS SNI, certificate chains
or HTTP headers. Any analysis that depends on protocol features is unavailable.
Acauã documents this as a degraded mode and never claims parity between flow
records and full Zeek logs.

### 6. Single HTTP and RPC boundary

The daemon exposes an Axum API on loopback by default. The embedded web UI
communicates with the daemon exclusively via standard HTTP calls.

## API

The HTTP API is served by `acaua serve`:

| Method | Path | Meaning |
|---|---|---|
| GET | `/api/health` | Liveness and version |
| GET | `/api/status` | Uptime, data directory, dataset summary |
| GET | `/api/alerts` | Paginated alerts with evidence |
| POST | `/api/analyze` | Ingest and analyze a dataset directory |
| GET | `/api/update` | Check for newer releases |
| GET | `/logo.png` | Embedded brand asset |
| GET | `/*` | Embedded UI fallback (`rust-embed`) |

`serve` binds to `127.0.0.1:8787` by default. Exposing it on an external network
requires an authenticating reverse proxy.

## Storage

DuckDB is a mandatory dependency linked dynamically to the official prebuilt
`libduckdb.so` (version 1.5.6 pinned with SHA-256 in `scripts/fetch-libduckdb.sh`).
Parquet, JSON and ICU extensions are statically built into the official library.
The schema consists of daily partitioned Parquet files under the configured
data directory, with in-memory DuckDB querying and a seven-day TTL.

## Updates

Updates for Acauã are delivered via container images (`docker compose pull && docker compose up -d`).
The `acaua update` command queries the Gitea Releases API for `ciberfauna/acaua` and
notifies operators when a newer version tag is available. Binary self-overwrite
(`update --apply`) is removed: in a collective SOC daemon running under container
orchestration, updates must be controlled by image pulls rather than self-mutating
processes.

## Rejected alternatives

1. **Python service with FastAPI/ClickHouse:** Rejected. A Python runtime introduces
   heavy container footprints and unnecessary memory boundaries; ClickHouse adds an
   external server operational burden for datasets that fit an embedded columnar store.
   The product is 100% Rust.
2. **Desktop application (Tauri / AppImage / NSIS):** Rejected. Unlike Guará (local
   raw disk forensics) and Sabiá (Wi-Fi monitor-mode hardware), Acauã has no local
   hardware dependencies: it is a multi-user SOC daemon consuming Zeek logs. A desktop
   wrapper adds maintenance and security surface without operational benefits.

## Deployment

- **Docker Compose (Official):** Multi-arch container image (`git.lucasrguerra.dev.br/ciberfauna/acaua`),
  running as unprivileged user `acaua` (UID 10001), read-only root filesystem, dropped capabilities.
- **Native compilation:** `scripts/fetch-libduckdb.sh ~/.cache/acaua/duckdb` followed by `cargo build --release -p acaua-cli`.

## 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.

## 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.