Architecture Overview
How the OASIS kernel, provider layer, ONODE, STAR runtime, and HyperDrive compose into a decentralised Web4/Web5 platform.
The Four Layers
OASIS is structured as four cooperating layers, each independently replaceable:
| Layer | What it does |
|---|---|
| OASIS Kernel | Core business logic: avatar management, karma, holons, quests, missions. Lives in NextGenSoftware.OASIS.API.Core. |
| Provider Layer | Pluggable storage and network backends. Each provider implements the IOASISProvider interface. Holochain, Ethereum, IPFS, MongoDB, SQLite, and more ship by default. |
| ONODE / WebAPI | ASP.NET Core host that exposes the kernel via REST. Manages provider registration, DID auth, JWT issuance, and HyperDrive failover. |
| STAR Runtime | OApp lifecycle engine — compile, deploy, version, and run OApps against a live ONODE. |
Provider Model
The provider model is the key architectural idea. The kernel never calls a storage technology directly — it calls an IOASISProvider. This means:
- Avatar data written via the Holochain provider can be read back via the MongoDB provider (via HyperDrive sync).
- OApps can specify their preferred provider per call, or let ONODE choose via the configured default and failover chain.
- New blockchains, databases, or distributed systems can be added without touching the kernel.
Pass providerType in any REST request body to override the ONODE default for that call. Example: "providerType": "HoloOASIS" to force Holochain storage.
HyperDrive
HyperDrive is OASIS's distributed data replication and failover engine. It sits between the kernel and the provider layer and:
- Replicates writes across multiple providers simultaneously (configurable write quorum).
- Automatically fails over reads to the next healthy provider if the primary is unavailable.
- Tracks provider health scores and routes traffic away from degraded nodes.
- Handles data migration between providers without downtime.
See the HyperDrive guide for configuration details.
ONODE
An ONODE is a self-contained OASIS node — it runs the WebAPI, manages a set of providers, and optionally participates in the ONET peer-to-peer network. You can run an ONODE:
- Locally — for development against
http://localhost:4000 - Self-hosted — for a community or organisation's dedicated OASIS node
- On ONET — joining the decentralised node network with DID-based authentication
See ONODE Setup for installation and configuration.
STAR Runtime
STAR (Systematic Technological Automated Runtime) is the OApp deployment and lifecycle engine. It provides:
- OApp compilation from source into a deployable OAPP package
- Version management and rollback
- Binding OApp identity to the avatar that created it (creator karma rewards)
- Runtime sandboxing and resource limits per OApp
Web4 vs Web5
OASIS ships two API surface levels that correspond to capability tiers:
| WEB4 | WEB5 | |
|---|---|---|
| Focus | Avatar, karma, data, NFT, quests, missions, maps | WEB4 + Celestial Spaces, GeoNFTs, Cosmic layer, holonic memory |
| JS package | @oasisomniverse/web4-api | @oasisomniverse/web5-api |
| Use when | Building standard OApps and games | Building spatial / AR / cosmic-scale experiences |