HyperSpot Server

HyperSpot Server is a modular, high-performance platform for building modern enterprise-grade SaaS services in Rust. It provides a comprehensive framework for building scalable AI-powered applications with automatic REST API generation, comprehensive OpenAPI documentation, and a extremely flexible modular architecture.

Key Philosophy:

• Modular by Design: Everything is a Module - composable, independent units with gateway patterns for pluggable workers
• Extensible at Every Level: GTS-powered extension points for custom data types, business logic, and third-party integrations
• SaaS Ready: Multi-tenancy, granular access control, usage tracking, and tenant customization built-in
• Cloud Operations Excellence: Production-grade observability, database agnostic design, API best practices, and resilience patterns via ModKit
• Quality First: 90%+ test coverage target with unit, integration, E2E, performance, and security testing
• Universal Deployment: Single codebase runs on cloud, on-prem Windows/Linux workstation, or mobile
• Developer Friendly: AI-assisted code generation, automatic OpenAPI docs, DDD-light structure, and type-safe APIs
• Written in Rust: Optimize recurring engineering work with compile-time safety and deep static analysis (including project-specific lints) so more issues are prevented before review/runtime.
• Keep Monorepo while possible: Keep core modules and contracts in one place to enable atomic refactors, consistent tooling/CI, and realistic local build + end-to-end testing; split only when scale forces it.

See the full architecture MANIFEST for more details, including rationales behind Rust and Monorepo choice.

Quick Start

Prerequisites

• Rust stable with Cargo
• MariaDB/PostgreSQL/SQLite or in-memory database

CI/Development Commands

# Clone the repository
git clone <repository-url>
cd hyperspot

make ci         # Run full CI pipeline
make fmt        # Check formatting (no changes). Use 'make dev-fmt' to auto-format
make clippy     # Lint (deny warnings). Use 'make dev-clippy' to attempt auto-fix
make test       # Run tests
make example    # Run modkit example module
make check      # Full check suite
make safety     # Extended safety checks (includes dylint/kani)
make deny       # License and dependency checks

Running the Server

# Quick helper
make quickstart

# Option 1: Run with SQLite database (recommended for development)
cargo run --bin hyperspot-server -- --config config/quickstart.yaml run

# Option 2: Run without database (no-db mode)
cargo run --bin hyperspot-server -- --config config/no-db.yaml run

# Option 3: Run with mock in-memory database for testing
cargo run --bin hyperspot-server -- --config config/quickstart.yaml --mock run

# Check if server is ready (detailed JSON response)
curl http://127.0.0.1:8087/health

# Kubernetes-style liveness probe (simple "ok" response)
curl http://127.0.0.1:8087/healthz

# See API documentation:
# $ make quickstart
# visit: http://127.0.0.1:8087/docs

Example Configuration (config/quickstart.yaml)

# HyperSpot Server Configuration

# Core server configuration (global section)
server:
  home_dir: "~/.hyperspot"

# Database configuration (global section)
database:
  url: "sqlite://database/database.db"
  max_conns: 10
  busy_timeout_ms: 5000

# Logging configuration (global section)
logging:
  default:
    console_level: info
    file: "logs/hyperspot.log"
    file_level: warn
    max_age_days: 28
    max_backups: 3
    max_size_mb: 1000

# Per-module configurations moved under modules section
modules:
  api_gateway:
    bind_addr: "127.0.0.1:8087"
    enable_docs: true
    cors_enabled: false

Creating Your First Module

See NEW_MODULE.md, but also MODKIT_UNIFIED_SYSTEM.md and MODKIT_PLUGINS.md for more details.

Documentation

• Architecture manifest - High-level overview of the architecture
• Components - List of all components and their roles
• NEW_MODULE.md, MODKIT_UNIFIED_SYSTEM.md and MODKIT_PLUGINS.md - how to add new modules.
• Contributing - Development workflow and coding standards

Configuration

YAML Configuration Structure

# config/server.yaml

# Global server configuration
server:
  home_dir: "~/.hyperspot"

# Database configuration
database:
  servers:
    sqlite_users:
      params:
        WAL: "true"
        synchronous: "NORMAL"
        busy_timeout: "5000"
      pool:
        max_conns: 5
        acquire_timeout: "30s"

# Logging configuration
logging:
  default:
    console_level: info
    file: "logs/hyperspot.log"
    file_level: warn
    max_age_days: 28
    max_backups: 3
    max_size_mb: 1000

# Per-module configuration
modules:
  api_gateway:
    config:
      bind_addr: "127.0.0.1:8087"
      enable_docs: true
      cors_enabled: true
  users_info:
    database:
      server: "sqlite_users"
      file: "users_info.db"
    config:
      default_page_size: 5
      max_page_size: 100

Environment Variable Overrides

Configuration supports environment variable overrides with HYPERSPOT_ prefix:

export HYPERSPOT_DATABASE_URL="postgres://user:pass@localhost/db"
export HYPERSPOT_MODULES_api_gateway_BIND_ADDR="0.0.0.0:8080"
export HYPERSPOT_LOGGING_DEFAULT_CONSOLE_LEVEL="debug"

Testing

# Run all tests
make test
# or
cargo test

# Run specific module tests
cargo test -p api_gateway
cargo test -p modkit

# Integration tests with database
cargo test --test integration

# Unit tests code coverage
make coverage-unit

CI / Development Commands

HyperSpot uses a unified, cross-platform Python CI script. Ensure you have Python 3.9+ installed.

# Clone the repository
git clone <repository-url>
cd hyperspot

# All code must pass these checks before merging
python scripts/ci.py all          # Build and run all the checks
# Run individual checks
python scripts/ci.py check        # Full CI suite: fmt, clippy, test, audit, deny
python scripts/ci.py fmt          # Check formatting
python scripts/ci.py fmt --fix    # Auto-format code
python scripts/ci.py clippy       # Run linter
python scripts/ci.py clippy --fix # Attempt to fix warnings
python scripts/ci.py dylint       # runs custom project compliance lints on the workspace
python scripts/ci.py audit        # Security audit
python scripts/ci.py deny         # License & dependency checks

On Unix/Linux/macOS, the Makefile provides shortcuts:

# All code must pass these checks before merging
make all    # Build and run all the checks
# Run individual checks
make check  # Full check suite as defined in Makefile
make fmt    # formatting (cargo fmt --all -- --check)
make dev-fmt # auto-format code (cargo fmt --all)
make clippy # linting (cargo clippy --workspace --all-targets --all-features -- -D warnings -D clippy::perf)
make lint   # compilation with warnings denied (RUSTFLAGS="-D warnings" cargo check ...)
make dylint # runs custom project compliance lints on the workspace
make deny   # dependency license and policy checks (cargo deny check)
make kani   # optional deep safety verification (Kani verifier)

E2E Tests

E2E tests require Python dependencies and pytest:

pip install -r testing/requirements.txt

make e2e-local  # Run e2e tests locally against a running server
make e2e-docker # Run e2e tests in a Docker container
make coverage-e2e # Run e2e tests with code coverage
make coverage # Run both unit and e2e tests with code coverage

Contributing

See CONTRIBUTING.md for detailed guidelines.

License

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