Oculus

Value Monitoring • Single Binary • Zero Dependencies

Oculus is an out-of-the-box value monitoring software designed for individuals and small teams. Written in Rust, single binary, zero external dependencies.

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

Features

• 🚀 Zero Dependencies - Single binary, runs anywhere
• 📊 Unified Value Monitoring - Crypto, stocks, prediction markets, network metrics 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
• 🔔 Rule Engine - Calculate derived values, trigger alerts with YAML configs and raw SQL
• 📬 Multi-Channel Notifications - Log, Email, Telegram, Discord, Slack, Webhook
• 🎯 Actions - HTTP POST triggers for automation

📖 See PRD for detailed functional requirements.

Supported Value Types

Architecture

Collectors  →  MPSC Channel  →  DuckDB  →  Rule Engine  →  Notifications/Actions
    │                              │              │                    │
    ├─ Crypto Prices               └─ Single      ├─ Simple Rules      ├─ Log
    ├─ Stock Prices                    Writer        (YAML/TOML)       ├─ Email
    ├─ Prediction Markets                         ├─ Complex Rules     ├─ Telegram
    ├─ Market Indicators                             (Raw SQL)         ├─ Discord
    ├─ Network Probes (HTTP/TCP/Ping)                                  ├─ Slack
    └─ Generic API Collector                                           ├─ Webhook
                                                                       └─ HTTP POST Action

📖 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:
  # Crypto price collector
  - type: crypto
    asset: btc_usd
    source: coingecko
    interval: 60s

  # Stock price collector
  - type: stock
    symbol: TSLA
    source: yahoo
    interval: 5m

  # Polymarket collector
  - type: polymarket
    market_id: some-market-id
    interval: 30s

  # Network probe
  - type: network.http
    target: https://api.example.com/health
    interval: 30s

  # Generic API collector (RESTful)
  - type: api
    name: custom_metric
    url: https://api.example.com/v1/data
    method: GET
    json_path: $.data.value
    interval: 60s

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

  - name: api_slow_response
    condition: "network.http.api_example.rtt > 1000"
    severity: warn
    channels: [slack, webhook]
    action:
      type: http_post
      url: https://automation.example.com/trigger

notifications:
  telegram:
    bot_token: ${TELEGRAM_BOT_TOKEN}
    chat_id: ${TELEGRAM_CHAT_ID}

  webhook:
    url: https://hooks.example.com/notify

  slack:
    webhook_url: ${SLACK_WEBHOOK_URL}

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
• Crypto Market: Asset price (BTC, ETH), Fear & Greed Index, MVRV
• Stock Market: Stock price, index data (SPY, QQQ)
• Prediction Market: Polymarket integration
• Network Probe: HTTP RTT and status code checks
• Generic API Collector: RESTful API with JSON path extraction

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
• Derived value calculation
• 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
• Generic webhook support

Action Layer

• HTTP POST action trigger

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 - Monitor any value, miss nothing.