-
Notifications
You must be signed in to change notification settings - Fork 2
systems
Magnus Hedemark edited this page Jun 16, 2026
·
2 revisions
The systems lens views SlopSearX as a set of interacting subsystems, each with a well-defined boundary and contract. Each subsystem lives in exactly one file in the slopsearx/ package. This section documents each subsystem's purpose, key abstractions, how it works, and integration points.
| Page | Subsystem | File | Purpose |
|---|---|---|---|
| Adapter interface | Engine adapter interface | slopsearx/adapter.py |
Abstract base classes, data types, circuit breaker, and the @register_engine registry that defines the primary architectural invariant of SlopSearX |
| Audit trail | Query audit trail | slopsearx/audit.py |
Durable audit log of every search query in Valkey streams for operational analysis |
| Merging and ranking | Result merger | slopsearx/merger.py |
URL normalization, deduplication, presence-weighted ranking, and metadata helpers |
| Configuration | Configuration | slopsearx/config.py |
Three-layer configuration model: built-in defaults, YAML file, environment variable overrides |
| Caching | Response cache | slopsearx/cache.py |
Two-level Valkey-backed response cache with negative caching and graceful degradation |
| Rate limiting | Rate limiter | slopsearx/ratelimit.py |
Multi-layer distributed rate limiting with fail-closed mode, per-client limits, and backpressure propagation |
| Observability | Metrics & telemetry | slopsearx/metrics.py |
OpenMetrics instrumentation and per-engine quality telemetry in Valkey |
| API server | HTTP server | slopsearx/server.py |
FastAPI HTTP server with circuit breaker, semaphore-bounded concurrency, and the SearXNG-compatible search API |