RealNet

RealNet is an open-source entity-based CMS that serves as the backend engine for the VirtualSpace ecosystem. It provides JSON schema object feeds and acts as the data/logic layer for digital twin, mixed reality, and content management applications.

Overview

RealNet is built on Flask and SQLAlchemy with PostgreSQL, featuring:

Entity-Based Type System - Types define schemas, instances are data
Multi-Tenancy - Organization and account isolation
OAuth2 Authentication - Secure API access with delegated auth support
Hierarchical Storage - Tree-structured items with spatial support (PostGIS)
Dynamic API - RESTful endpoints registered as database entities
Kubernetes Integration - Full K8s resource management through type system
AI Agents - Distributed agent communication via MQTT
WordPress Integration - Bidirectional content synchronization
Flexible Storage - Local filesystem or AWS S3

Core Features

Entity Type System

Everything in RealNet is data:

Types define structure (like classes)
Instances contain data conforming to types (like objects)
Items provide hierarchical organization with parent/child relationships
Attributes are JSON key-value data on types and instances

Multi-Provider Architecture

RealNet uses a provider pattern for all data operations:

TypeProvider - Type definitions and instances
ItemProvider - Hierarchical item CRUD
DataProvider - File storage (local or S3)
EndpointProvider - Dynamic API routing
Context-scoped providers ensure tenant isolation

Kubernetes Management

Manage Kubernetes resources as RealNet types:

20+ resource types: Pod, Deployment, Service, ConfigMap, Secret, StatefulSet, Job, CronJob, Ingress, and more
Full CRUD operations through RealNet API
In-cluster and kubeconfig support
Automatic manifest generation

AI Agents

MQTT-based distributed agent system:

Create agents with command and status topics
Bidirectional communication
Active/inactive status tracking
Script-based message handling

WordPress Integration

Full WordPress CMS integration:

Bidirectional content synchronization
PHP plugin + Python client
Multisite support
REST API with JWT authentication
Custom template system

Quick Start

Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install from source
python setup.py install

# Or via pip
pip install realnet

Initialize Database

# Initialize database and create admin account
realnet server initialize

# Start the server
realnet server start

Configuration

Create a .env file in the project root:

# Server
REALNET_SERVER_HOST=0.0.0.0
REALNET_SERVER_PORT=8080

# Database
REALNET_DB_TYPE=postgresql
REALNET_DB_HOST=localhost
REALNET_DB_PORT=5432
REALNET_DB_NAME=realnet
REALNET_DB_USER=realnet
REALNET_DB_PASS=realnet

# Storage (defaults to local)
REALNET_STORAGE_TYPE=local
REALNET_STORAGE_PATH=data

# Or use S3
# REALNET_STORAGE_TYPE=s3
# REALNET_STORAGE_S3_BUCKET=my-bucket
# REALNET_STORAGE_S3_KEY=AWS_KEY
# REALNET_STORAGE_S3_SECRET=AWS_SECRET
# REALNET_STORAGE_S3_REGION=us-east-1

# MQTT (optional, for agents and runners)
REALNET_MQTT_HOST=localhost
REALNET_MQTT_PORT=1883

# WordPress Integration (optional)
REALNET_WORDPRESS_URL=http://wordpress:8081
REALNET_WORDPRESS_ADMIN_USER=admin
REALNET_WORDPRESS_ADMIN_PASS=admin
REALNET_WORDPRESS_TOKEN=your-jwt-token

# OAuth
REALNET_APP_SECRET=your-secret-key
REALNET_URI=http://localhost:8080
REALNET_REDIRECT_URI=http://localhost:8080/oauth/callback

Deployment Options

Local Development

# Using SQLite (minimal setup)
REALNET_DB_TYPE=sqlite realnet server start

# Using PostgreSQL
realnet server initialize
realnet server start

Docker

# Build image
./build_docker

# Run container
docker run -p 8080:8080 --env-file .env realnet:latest

Kubernetes

# Deploy full stack (RealNet + PostgreSQL + Mosquitto MQTT)
kubectl apply -k k8s/base

# Or use deployment script
cd k8s
./deploy.sh

# On Windows
.\deploy.ps1

# Access the service
kubectl port-forward -n realnet svc/realnet 8080:8080

The Kubernetes deployment includes:

RealNet service (LoadBalancer on port 8080)
RealNet runner (MQTT message processor)
PostgreSQL database with persistent storage
Mosquitto MQTT broker
RBAC configuration for K8s resource management

Architecture

Request Flow

HTTP Request → Flask app via router_bp blueprint
Authentication → OAuth2 token or session validation
Context Creation → Scoped to (org_id, account_id) with providers
Endpoint Lookup → Dynamic resolution from database
Resource Invocation → Polymorphic dispatch to resource class
Provider Calls → Data access through provider layer
Response → JSON or HTML (Jinja2 templates)

Components

Shell/Command System (realnet/shell/) - CLI interface
Provider Pattern (realnet/core/provider.py) - Abstract data interfaces
Context System (realnet/cmd/server.py) - Per-request provider factory
Resource Modules (realnet/resource/) - HTTP verb handlers
SQL Providers (realnet/provider/sql/) - SQLAlchemy ORM
HTTP Runner (realnet/runner/http/) - Flask application
MQTT Runner (realnet/runner/mqtt/) - Message queue processor
Kubernetes Client (realnet/resource/cluster/) - K8s API integration
WordPress Client (realnet/provider/wordpress/) - WP API integration

Message Flow (WordPress Sync Example)

RealNet API → Create Page
    ↓
Publish MQTT Message → realnet/system topic
    ↓
Runner Pod Receives → Execute sync script
    ↓
WordPress API Call → Create WP page
    ↓
Result Published → realnet/system/result topic

VirtualSpace Ecosystem

RealNet is the backend data layer for the VirtualSpace product stack:

RealNet → RealScape → RealFusion

RealNet (this project): Entity CMS with type/instance system
RealScape: 3D/AR/MR viewer and mixed reality browser
RealFusion: Manufacturing workflow system with SAP Visual Enterprise integration

API Examples

Create a Type

curl -X POST http://localhost:8080/types \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product",
    "attributes": {
      "sku": {"type": "string"},
      "price": {"type": "number"},
      "description": {"type": "string"}
    }
  }'

Create an Instance

curl -X POST http://localhost:8080/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Product",
    "attributes": {
      "sku": "PROD-001",
      "price": 29.99,
      "description": "Example product"
    }
  }'

Query Items

# Get all items of a type
curl http://localhost:8080/items?type=Product \
  -H "Authorization: Bearer $TOKEN"

# Get item with children
curl http://localhost:8080/items/12345?children=true \
  -H "Authorization: Bearer $TOKEN"

Manage Kubernetes Resources

# List all pods
curl http://localhost:8080/cluster/pods \
  -H "Authorization: Bearer $TOKEN"

# Create deployment
curl -X POST http://localhost:8080/cluster/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @deployment.json

Development

Project Structure

realnet/
├── realnet/              # Main package
│   ├── cmd/             # Command implementations
│   ├── core/            # Core abstractions (provider, type system)
│   ├── provider/        # Provider implementations
│   │   ├── sql/        # PostgreSQL providers
│   │   ├── aws/        # S3 data provider
│   │   ├── generic/    # Local data provider
│   │   └── wordpress/  # WordPress client
│   ├── resource/        # Resource handlers (Items, Types, Files, etc.)
│   │   ├── cluster/    # Kubernetes resources
│   │   └── agents/     # AI agent resources
│   ├── runner/          # Background processors
│   │   ├── http/       # Flask application
│   │   └── mqtt/       # MQTT runner
│   ├── shell/          # CLI framework
│   └── static/         # Static files and initialization data
│       └── initialization/  # Type definitions (JSON)
├── k8s/                 # Kubernetes manifests
│   ├── base/           # Base deployment config
│   └── deploy.sh       # Deployment script
├── realnet-wordpress/   # WordPress plugin
├── docs/               # Documentation
└── setup.py            # Package configuration

Adding New Features

New Type (Data-Driven):

Add type definition to static/initialization/*.json
Run realnet server initialize to import
Types are versioned in JSON, not database migrations

New Resource (Code-Driven):

Create resource class extending Items in realnet/resource/
Override HTTP verb methods (get, post, put, delete)
Register resource in context provider

New Provider:

Define interface in realnet/core/provider.py
Implement in realnet/provider/
Wire into StandardContextProvider in cmd/server.py

Testing

Manual testing workflow:

# Initialize test database
realnet server initialize

# Start server
realnet server start

# Test API endpoints
curl http://localhost:8080/types

Automated testing is not currently implemented.

Running Commands

# Get help
realnet -h

# Server commands
realnet server initialize
realnet server start

# Info commands
realnet info types
realnet info items

# MQTT Runner (requires MQTT broker)
realnet runner

Key Files

realnet/realnet.py - Main CLI entry point
realnet/cmd/server.py - Server initialization and start
realnet/runner/http/app.py - Flask application factory
realnet/runner/http/router.py - Request routing and dispatch
realnet/core/config.py - Configuration management
realnet/core/provider.py - Provider interfaces
realnet/core/hierarchy.py - Type system import/export
realnet/provider/sql/models.py - Database schema (SQLAlchemy)
setup.py - Package metadata and dependencies

Documentation

CLAUDE.md - Comprehensive development guide for Claude Code
PROJECT_CONTEXT.md - Project architecture and context
RealNet_Integration_Guide.md - Multi-provider integration patterns
docs/realnet_type_system_guide.md - Type system deep dive

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit with descriptive messages (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Security Considerations

Never commit .env file (in .gitignore)
All secrets must be in environment variables
OAuth2 redirect URIs must be whitelisted per client
Multi-tenancy isolation is enforced at provider level
Use REALNET_ALLOW_HTTP=True only for development (enables OAUTHLIB_INSECURE_TRANSPORT)

License

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

Links

GitHub: https://github.com/virtual-space/realnet
VirtualSpace: https://virtualspace.io
Documentation: See docs/ directory

Name		Name	Last commit message	Last commit date
Latest commit History 393 Commits
.github		.github
.vscode		.vscode
cluster		cluster
docs		docs
examples		examples
k8s		k8s
memory_bank		memory_bank
realnet-wordpress		realnet-wordpress
realnet		realnet
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PROJECT_CONTEXT.md		PROJECT_CONTEXT.md
README.md		README.md
README_legacy.md		README_legacy.md
RealNet_Integration_Guide.md		RealNet_Integration_Guide.md
build_docker		build_docker
build_package		build_package
requirements.txt		requirements.txt
runner		runner
setup.py		setup.py
triangle.gltf		triangle.gltf

License

virtual-space/realnet

Folders and files

Latest commit

History

Repository files navigation

RealNet

Overview

Core Features

Entity Type System

Multi-Provider Architecture

Kubernetes Management

AI Agents

WordPress Integration

Quick Start

Installation

Initialize Database

Configuration

Deployment Options

Local Development

Docker

Kubernetes

Architecture

Request Flow

Components

Message Flow (WordPress Sync Example)

VirtualSpace Ecosystem

API Examples

Create a Type

Create an Instance

Query Items

Manage Kubernetes Resources

Development

Project Structure

Adding New Features

Testing

Running Commands

Key Files

Documentation

Contributing

Security Considerations

License

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Uh oh!

Languages

Packages