Getting Started

Zoris Engine

Enterprise-grade financial intelligence, risk prediction, and autonomous portfolio management engine powering the Zoris Protocol.

Overview

The Zoris Engine is a high-performance financial intelligence substrate that powers the Zoris Protocol infrastructure. It aggregates off-chain market telemetry, calculates implied probabilities, applies risk-weighting permutations, and orchestrates live database states to serve institutional-grade dashboards and B2B API consumers.

The engine operates across a distributed node topology spanning Google Cloud Platform (GCP), DigitalOcean (DO), and a Spring Boot orchestration layer, delivering real-time market sentiment and autonomous portfolio management capabilities.

Architecture

The Zoris Engine is composed of three primary infrastructure nodes:

Telemetry Node (GCP)

The lightweight upstream scraper responsible for chronological data discovery. It connects to the Jamaica Stock Exchange (JSE) at configurable market-close intervals to extract, homogenize, and package end-of-day market statistics.

Runtime: Python 3.10+
Key Module: gcp_scraper_bridge_v2.py
Delivery: Secure scp payload transfer to the Computational Core

Computational Core (DigitalOcean)

The primary brain of the protocol. Runs a FastAPI server containing logic modules for risk prediction, schema orchestration, sentiment analysis, and API gateway validation.

Runtime: Python 3.10+ / Uvicorn ASGI
Key Modules: zoris_api.py, vm_zoris_brain.py, sentiment_engine.py
Port: 8000

Orchestration Layer (Spring Boot)

The client-facing platform that manages user authentication, subscription tiers, and proxies API key generation requests to the Computational Core.

Runtime: Java 17+ / Spring Boot
Key Integration: ZorisNodeClient.java → DO FastAPI

Data Flow

┌─────────────────┐     SCP      ┌──────────────────┐    REST/JSON    ┌──────────────────┐
│  GCP Telemetry  │ ──────────►  │   DO Compute     │ ◄────────────►  │  Spring Boot     │
│  (Scraper)      │              │   (FastAPI)       │                 │  (Platform)      │
│  34.68.76.0     │              │   138.197.63.52   │                 │                  │
└─────────────────┘              └──────────────────┘                 └──────────────────┘
                                        │
                                        ▼
                                 ┌──────────────────┐
                                 │  Frontend Node   │
                                 │  (Next.js)       │
                                 │  159.203.124.190  │
                                 └──────────────────┘

Authentication

All API endpoints are protected by X-API-Key header authentication. The engine supports two classes of credentials:

Master Key: Used for internal platform-to-node administrative communication and key minting operations.
Client Keys: Issued per-user via the POST /api/keys/generate endpoint. Scoped by subscription tier with configurable rate limits.

API Reference

Market Intelligence

`GET /api/market/latest`

Returns the latest normalized market statistics for all tracked JSE instruments.

{
  "HONBUN": { "close": 4.50, "volume": 125000, "change_pct": 2.3 },
  "JMMBGL": { "close": 38.20, "volume": 98400, "change_pct": -0.8 }
}

`GET /api/market/symbol/{symbol}`

Retrieves historical variance and latest normalized statistics for a specific JSE ticker.

`GET /api/market/history/{symbol}`

Returns chronological price and volume history for a given symbol.

AI Portfolio

`GET /api/ai-portfolio/positions`

Retrieves algorithmically generated active positions with intelligence rationales.

[
  {
    "symbol": "HONBUN",
    "direction": "LONG",
    "rationale": "High sentiment, breaking out of volume bands",
    "timestamp": "2026-03-24T12:00:00"
  }
]

`GET /api/ai-portfolio/summary`

Returns aggregate portfolio metrics including total value, PnL, and allocation breakdown.

`GET /api/ai-portfolio/history`

Returns the historical record of all AI-generated positions.

Sentiment & Suggestions

`GET /api/ai/performance`

Returns AI prediction accuracy metrics and performance telemetry.

`GET /api/suggestions`

Returns pending position suggestions generated by the intelligence engine, awaiting user confirmation or rejection.

`POST /api/suggestions/{id}/confirm`

Confirms and executes a pending suggestion.

`POST /api/suggestions/{id}/reject`

Rejects a pending suggestion.

Administrative (Master Key Only)

`POST /api/keys/generate`

Mints a new B2B client API key for institutional access.

Request Body:

{ "client_name": "Acme Capital" }

Response:

{ "api_key": "zk-abc123...", "client_name": "Acme Capital" }

Database Architecture

The engine uses domain-segregated SQLite stores to maintain strict ACID properties and minimize table-locking during high-velocity reads.

Database	Purpose	Key Fields
`zoris_clients.db`	Client API key authentication	`api_key`, `client_name`, `created_at`
`ai_portfolio.db`	AI-generated position intelligence	`symbol`, `direction`, `rationale`, `timestamp`
`portfolio.db`	Physical execution archive	`symbol`, `action`, `quantity`, `price`, `timestamp`

Pipeline Schedule

The automated data pipeline runs on a cron schedule synchronized to JSE market hours:

Time (EST)	Stage	Description
15:55	T0	GCP Telemetry Node wakes to scrape end-of-day data
16:00	T1	Secure payload delivery via `scp` to DO Core
16:05	T2	Risk module parses CSV arrays, scores symbols
16:10	T3	Predictions written to SQLite stores
16:15	T4	API serves fresh intelligence to downstream consumers

Quick Start

Prerequisites

Python 3.10+
Node.js 18+ (for the frontend)

Installation

git clone https://github.com/Javannio/zoris-engine.git
cd zoris-engine
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn pandas

Running the API

uvicorn zoris_api:app --host 0.0.0.0 --port 8000 --reload

Running the Frontend

cd frontend
npm install
npm run dev

Built with Documentation.AI