High-Level Architecture

Sentry is organized into three plugin layers (Sources, Core, Actions) on top of a persistence layer. Every plugin implements a common trait, allowing new sources and actions to be added without recompiling the core.

Design principles

1. Source trait: every plugin implements fn stream_events(&self) -> impl Stream<Item = RawEvent>. Adding nginx = implementing the trait.
2. Action trait: fn execute(&self, decision: &Decision) -> Result<()>. Block, Challenge, Alert, etc.
3. Normalized Event: a single struct Event regardless of source. The core never knows whether it came from nginx or TCP.
4. Asynchronous pipeline: tokio + channels. Each stage is an actor/fan-out.
5. Declarative configuration: sentry.toml defines active sources, active actions, thresholds.

Tech stack

Layer	Crate / Technology	Rationale
Async runtime	tokio	De facto standard, cross-platform
CLI	clap (derive) + ratatui for live TUI	Ergonomics, subcommands, live panel
Config	serde + toml + figment (env+file merge)	Env-var override in prod
Logs/Tracing	tracing + tracing-subscriber	Structured logging, per-request spans
nginx parser	nom or regex + serde	Custom access_log line format
HTTP client	reqwest (rustls)	Cloudflare API, webhooks, geolookup
Local ML/AI	ort (ONNX Runtime) + candle fallback	Local inference without external API dependency
LLM (optional)	LlmProvider trait + adapters: OpenRouter (routes to any model), async-openai, ollama-rs	Complex payload analysis on demand, provider-agnostic
Storage	sqlx with Postgres default (sqlx migrations), optional SQLite via feature flag	Same schema, switch via feature flag; Postgres supports HA and multiple nodes from day one
Geolookup	maxminddb (local DB)	No external call per event
IPC/Embeddable	core as a lib crate (sentry-core)	Future dashboard consumes the same lib
Serialization	serde + serde_json	Events, export, future API
Errors	thiserror (lib) + color-eyre (bin)	Ergonomics + readable backtraces
Tests	proptest + insta (snapshots) + wiremock	Malicious payloads, log fixtures
Build/Release	cargo-dist or cross	Multi-OS binaries

Crate structure (workspace)

sentry/
├── Cargo.toml                    # workspace
├── crates/
│   ├── sentry-core/              # lib: Event, traits, pipeline, scoring
│   ├── sentry-source-nginx/      # plugin Source: nginx log tail
│   ├── sentry-source-http/       # plugin Source: proxy middleware (future)
│   ├── sentry-source-tcp/        # plugin Source: pcap (future)
│   ├── sentry-source-cloudflare/ # plugin Source: pull CF logs
│   ├── sentry-ai/                # ONNX + LLM provider trait
│   ├── sentry-action-cloudflare/ # plugin Action
│   ├── sentry-action-webhook/    # plugin Action
│   ├── sentry-action-blocklist/  # plugin Action
│   ├── sentry-storage/           # sqlx SQLite/Postgres
│   ├── sentry-geo/               # maxminddb wrapper
│   └── sentry-cli/               # binary: clap + ratatui + entrypoint
├── models/                       # versioned ONNX models
├── config/sentry.example.toml
├── tests/                        # integration tests
└── docs/