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.3 - Under active development
• 🛑 Scope Note: v0.1.x 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
• 🌐 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  →  SQLite/PostgreSQL →  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 server, database, and collectors:

# Example: configs/config.yaml
server:
  bind: 0.0.0.0
  port: 8080

database:
  driver: sqlite
  dsn: data/oculus.db
  channel_capacity: 10000

collectors:
  tcp:
    - name: google-dns
      host: 8.8.8.8
      port: 53
      enabled: true
      group: production
      interval: 5s
      timeout: 5s
      tags:
        env: production

  ping:
    - name: cloudflare-ping
      host: 1.1.1.1
      enabled: true
      group: production
      interval: 30s
      timeout: 3s

  http:
    - name: api-health
      url: https://api.example.com/health
      enabled: true
      group: production
      method: GET
      expected_status: 200
      interval: 30s
      timeout: 10s
      headers:
        Authorization: "Bearer ${API_TOKEN:-default}"
      success_conditions:
        status_codes: [200, 201]
        body_jsonpath: "$.status"

📖 See configs/config.example.yaml for complete configuration options.

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.3 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: TCP port probe
• Network Probe: ICMP ping probe
• Network Probe: HTTP RTT and status code checks
• Generic API Collector: RESTful API with JSON path extraction

Storage Layer

• SQLite for single-node support
• PostgreSQL for multi-node support
• metrics table schema and migrations
• events table for alerts/audit
• collectors table for collector configuration
• Data retention and cleanup policy (configurable 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 /api/metrics)
• Real-time events partial (GET /api/events)
• Metrics stats endpoint (GET /api/metrics/stats)
• Raw SQL query endpoint (POST /api/query)
• 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.