Oculus

Unified Telemetry • Single Binary • No-Build Web

Oculus is a lightweight, high-performance monitoring and observability system that bridges the gap between traditional infrastructure monitoring (like Prometheus) and financial market tracking (like TradingView).

⚠️ Status: v0.1.0 (Genesis / MVP) - Under active development
🛑 Scope Note: v0.1.0 is single-user; no user/account/role management.

Features

• 🚀 Single Binary - Zero external dependencies, runs anywhere
• 📊 Unified Metrics - Network probes, crypto, stocks, and prediction markets in one place
• ⚡ High Performance - Rust + DuckDB for low latency and minimal resource usage
• 🌐 No-Build Web UI - HTMX-powered dashboard, no JavaScript build step
• 🔔 Smart Alerts - Rule engine with simple YAML configs and raw SQL support
• 📬 Multi-Channel Notifications - Log, Email, Telegram, Discord, Slack

📖 See PRD for detailed functional requirements.

Architecture

Collectors  →  MPSC Channel  →  DuckDB  →  Rule Engine  →  Presentation/Notifications
    │                              │              │                    │
    ├─ Network Probes              └─ Single      ├─ Simple Rules      ├─ Web UI (HTMX)
    ├─ Crypto Markets                  Writer        (YAML/TOML)       ├─ REST API
    ├─ Stock Markets                              ├─ Complex Rules     ├─ Telegram
    ├─ Prediction Markets                            (Raw SQL)         ├─ Discord
    └─ Custom Collectors                                               └─ Slack

📖 See PRD for detailed logical architecture and component overview.

Tech Stack

Quick Start

Prerequisites

• Rust toolchain (Edition 2024)
• Optional: Tailwind CSS CLI for style customization

Build & Run

# Clone the repository
git clone https://github.com/telepair/oculus.git
cd oculus

# Build full distribution (CSS + release binary)
make release

# Run with default config
./target/release/oculus

# Run with custom options
./target/release/oculus --config configs/config.yaml --server-port 9090

📖 See Getting Started for detailed configuration options.

Development

# Full CI pipeline: format → lint → check → test → build
make all

# Individual commands
make fmt        # Format code
make lint       # Run clippy + markdownlint
make test       # Run tests
make doc-open   # Build and view documentation

Configuration

Oculus uses a YAML configuration file for collectors and rules:

# Example: configs/config.yaml
collectors:
  - type: network
    probe: ping
    target: 8.8.8.8
    interval: 30s

  - type: crypto
    asset: btc_usd
    source: coingecko
    interval: 60s

rules:
  - name: btc_price_alert
    condition: "crypto.price.btc_usd > 100000"
    severity: info
    channels: [telegram, log]

API Endpoints

Project Structure

oculus/
├── src/
│   ├── lib.rs           # Library: shared core functionality
│   └── main.rs          # Binary: runs complete system
├── templates/           # Askama templates (compiled into binary)
│   ├── dashboard.html
│   └── static/css/
├── configs/             # Configuration examples
├── docs/
│   ├── PRD.md           # Product Requirements Document
│   ├── getting-started.md # Build & Run Guide
│   ├── lib.md           # Library Integration Guide
│   └── schema.md        # Database Schema Reference
├── Cargo.toml           # Rust dependencies
├── Makefile             # Build automation
└── LICENSE              # MIT License

Library vs Binary

Use as a library:

use oculus::{Collector, Storage, RuleEngine};

Run as a binary:

cargo run --bin oculus

Performance Targets

TODO

v0.1.0 MVP milestone tasks based on PRD

Collector Layer

• Core collector trait and MPSC channel pipeline
• Network Probe: Ping, TCP, HTTP health checks
• Crypto Market: Asset price, Fear & Greed Index, MVRV
• Stock Market: Stock price, index data
• Prediction Market: Polymarket integration
• Custom collector plugin interface

Storage Layer

• DuckDB integration with single-writer actor model
• metrics table schema and migrations
• events table for alerts/audit
• Data retention and cleanup policy (7-day window)

Rule Engine

• Simple rules: YAML/TOML-based threshold alerts
• Complex rules: Raw SQL with scheduled execution
• Event emitter for rule triggers

Presentation Layer

• Axum web server setup
• HTMX dashboard homepage (GET /)
• Real-time metrics partial (GET /partials/metrics)
• REST API endpoints (/api/metrics, /api/query, etc.)
• Askama templates with Tailwind CSS (bundled)

Notification Layer

• Log output via tracing crate
• Email notifications (SMTP)
• Telegram bot integration
• Discord webhook support
• Slack webhook support

Infrastructure

• Configuration file parsing (YAML)
• CLI argument handling
• Health probes (/healthz, /readyz)
• Performance validation (startup < 100ms, memory < 50MB)

Contributing

Contributions are welcome! Please read the PRD in docs/PRD.md for architectural context before submitting changes.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -s -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Oculus - See everything, miss nothing.