Obsrvr Intelligence Console

A contract-centric block explorer and developer terminal for Stellar and Soroban networks. Built with Go, HTMX, and a tiered storage architecture for cost-effective access to full blockchain history.

Features

• Multi-column drill-down interface inspired by Bloomberg Terminal
• Tiered storage architecture (Hot PostgreSQL + Cold S3 Parquet)
• Contract-first exploration with dedicated Soroban tools
• Intelligence console with natural language commands
• Agent/LLM friendly APIs with semantic markup
• Real-time monitoring with WebSocket updates
• Cost-effective - 92% cheaper than traditional full-database approaches

Quick Start

Prerequisites

Choose one of the following development approaches:

Option 1: Nix (Recommended)

• Nix with flakes enabled
• direnv (optional, for automatic environment loading)

Option 2: Traditional

• Go 1.24+
• PostgreSQL 15+
• Docker & Docker Compose

Nix Development Environment

The project includes a comprehensive Nix flake for reproducible development:

1. Clone and enter environment:

git clone <repository-url>
cd obsrvr-intelligence-console

# With direnv (automatically loads environment)
direnv allow

# Or manually with Nix flakes
nix develop

# Or legacy nix-shell
nix-shell

2. Setup and run:

# Initialize project structure
nix run .#setup

# Start PostgreSQL with Docker
make docker-up

# Start development server with hot reload
nix run .#dev
# or: make dev

3. Open browser:

http://localhost:8080

Nix Flake Features

The flake provides:

• Complete development environment with Go, PostgreSQL, and all tools
• Automatic environment variables and Go workspace setup
• Hot reload development with Air
• Docker image building: nix build .#docker
• NixOS service module for production deployment
• Reproducible builds across different systems

Available Nix Commands

nix develop          # Enter development shell
nix run .#dev        # Start development server
nix run .#build      # Build the application
nix run .#setup      # Setup development directories
nix build            # Build the Go application
nix build .#docker   # Build Docker image

Traditional Development

1. Clone and setup:

git clone <repository-url>
cd obsrvr-intelligence-console
make setup

2. Start dependencies:

make docker-up

3. Initialize database:

make init-db

4. Run the application:

# Development with hot reload
make dev

# Or build and run
make run

5. Open browser:

http://localhost:8080

Docker Compose

# Start everything
docker-compose up -d

# View logs
docker-compose logs -f console

Architecture

Tiered Storage Strategy

Hot Database (PostgreSQL):

• Recent 6 months of data
• Sub-100ms query performance
• Real-time transaction streaming
• Cost: ~$500/month

Cold Storage (S3 Parquet + DuckDB):

• Full historical blockchain data
• 1-5 second analytics queries
• 90% storage cost reduction
• Cost: ~$300/month

Console Commands

# Hot database queries (recent data)
obsrvr> follow ledger latest
obsrvr> filter transactions where created_at > '2024-12-01'

# Cold storage queries (historical data)  
obsrvr> analyze contract CABC...DEF --full-history
obsrvr> filter transactions where date > '2020-01-01'

# Utility commands
obsrvr> explain transaction f2a4...b912
obsrvr> help

Configuration

Copy .env.example to .env and configure:

# PostgreSQL for hot data
POSTGRES_URL=postgres://user:password@localhost/obsrvr_hot?sslmode=disable

# DuckDB for cold data queries
DUCKDB_PATH=./data/obsrvr_cold.duckdb

# S3 for parquet storage
S3_BUCKET=obsrvr-historical-data
S3_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# Application settings
HOT_DATA_MONTHS=6
PORT=8080

API Endpoints

Console API

• POST /cli - Execute console commands
• GET /console - Console interface

Explorer API

• GET /explorer/ledger/{sequence} - Ledger details
• GET /explorer/transaction/{hash} - Transaction details
• GET /explorer/contract/{id} - Contract details

Agent/LLM API

• GET /api/v1/ledgers - List ledgers (JSON)
• GET /api/v1/transactions - List transactions (JSON)
• GET /api/v1/contracts/{id}/events - Contract events (JSON)
• POST /api/v1/query - Arbitrary queries (JSON)

Development

Project Structure

.
├── main.go              # Main application entry point
├── sql/                 # Database schema and migrations
├── templates/           # HTML templates
├── static/              # Static assets (CSS, JS, images)
├── data/                # Local DuckDB files
├── docker-compose.yml   # Development environment
└── Makefile            # Build and development commands

Building

# Build binary
make build

# Run tests
make test

# Clean build artifacts
make clean

Hot Reload Development

Install Air for hot reload:

go install github.com/cosmtrek/air@latest
make dev

Deployment

Nix Deployment

Single Binary (Nix)

# Build with Nix (reproducible)
nix build

# The binary will be in result/bin/obsrvr-console
./result/bin/obsrvr-console

Docker Image (Nix)

# Build optimized Docker image with Nix
nix build .#docker

# Load and run the image
docker load < result
docker run -p 8080:8080 \
  -e POSTGRES_URL=postgres://... \
  -e S3_BUCKET=your-bucket \
  obsrvr-console:latest

NixOS Service

Add to your NixOS configuration:

{
  imports = [ ./path/to/obsrvr-console/flake.nix.nixosModules.default ];
  
  services.obsrvr-console = {
    enable = true;
    port = 8080;
    postgresUrl = "postgres://user:pass@localhost/obsrvr_hot";
    s3Bucket = "your-bucket";
    s3Region = "us-east-1";
  };
}

Traditional Deployment

Single Binary

# Build for production
CGO_ENABLED=1 GOOS=linux go build -o obsrvr-console .

# Run
./obsrvr-console

Docker

# Build image
docker build -t obsrvr-console .

# Run container
docker run -p 8080:8080 \
  -e POSTGRES_URL=postgres://... \
  -e S3_BUCKET=your-bucket \
  obsrvr-console

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details