caishen

Data Schemas

RISE Framework Specification

Spec ID: 10
Version: 1.0
Document ID: caishen-rise-schemas-v1.0
Last Updated: 2025-01-31

Creative Intent

What Data Schemas Enable:

Consistent data representation across all services
Database persistence with proper relationships
JSON serialization for API communication
Data validation and integrity

Desired Outcomes:

All services share common entity definitions
Data can be persisted and retrieved reliably
Relationships between entities are well-defined
Migration to new platforms is straightforward

Core Entities

Price Data Entities

PriceBar (IQuote)

PriceBar:
  - Date: DateTime           # Bar timestamp (UTC)
  - Open: decimal            # Opening price
  - High: decimal            # Highest price
  - Low: decimal             # Lowest price
  - Close: decimal           # Closing price
  - Volume: long             # Trade volume

QuoteSide

QuoteSide:
  - O: decimal               # Open
  - H: decimal               # High
  - L: decimal               # Low
  - C: decimal               # Close

PriceHistoryBase

PriceHistoryBase:
  - Instrument: string       # "EUR/USD"
  - Timeframe: string        # "H4"
  - Bars: List<PriceBar>
  - StartDate: DateTime
  - EndDate: DateTime
  - Source: string

Instrument Entities

InstrumentProperty

InstrumentProperty:
  - Symbol: string           # "EUR/USD"
  - Name: string             # "Euro vs US Dollar"
  - BaseCurrency: string     # "EUR"
  - QuoteCurrency: string    # "USD"
  - PipSize: decimal         # 0.0001
  - PointSize: decimal       # 0.00001
  - ContractSize: int        # 100000
  
  # Margin Requirements
  - mar: MarginInfo
    - MMR: decimal           # Maintenance margin rate
    - LMR: decimal           # Leverage margin rate
  
  # Trading Specifications
  - pre: int                 # Precision (decimal places)
  - pips: decimal            # Pip value
  - cm: decimal              # Contract multiplier
  - tsmi: decimal            # Trade size minimum
  - tsmx: decimal            # Trade size maximum
  - subs: int                # Subscription type
  - bu: string               # Base unit
  - qtmi: decimal            # Quote minimum
  - qtmx: decimal            # Quote maximum
  - cc: string               # Currency code

Chaos Data Entities

BarChaosItem

BarChaosItem:
  # Identification
  - Id: Guid
  - Tlid: string             # Timeline ID (yyMMddHHmm)
  - CorrelationId: Guid
  
  # Price Data
  - Dt: DateTime
  - Ask: QuoteSide
  - Bid: QuoteSide
  - V: long                  # Volume
  
  # Alligator
  - Lips: double             # Green (5/3)
  - Teeth: double            # Red (8/5)
  - Jaw: double              # Blue (13/8)
  
  # Oscillators
  - AO: double               # Awesome Oscillator
  - SAO: double              # Smoothed AO
  - AC: double               # Accelerator
  - ACD: double              # AC direction
  - AOF: double              # AO fast
  
  # Fractals
  - Fractal: double
  - FractalBuy: double
  - FractalSell: double
  - FractalDimension: double
  
  # Fibonacci
  - F2: double
  - F3: double
  - F5: double
  - F8: double
  - F13: double
  - F21: double
  - F34: double
  - F55: double
  - F89: double
  
  # Trading Indicators
  - Zone: int                # 0=Gray, 1=Green, 2=Red
  - ZLC: bool                # Zero line cross
  - MFI: int                 # Market Facilitation Index
  - Squat: bool              # Squat bar
  - BDB: int                 # Bar divergence (-1, 0, 1)
  - FDB: int                 # Full divergence bar
  
  # Gator
  - GatorUpper: double
  - GatorLower: double
  - GatorSupreme: double
  
  # State
  - IsAOPeak: int            # -1=min, 0=no, 1=max
  - IsIncompleted: bool
  - BarType: int

ChaosDataBuilder

ChaosDataBuilder:
  # Identification
  - Instrument: string
  - Timeframe: string
  - PovTlid: string
  - CorrelationId: Guid
  
  # Price Data
  - ChartBars: List<BarChaosItem>
  - PipSize: double
  - PriceHighestValue: double
  - PriceLowestValue: double
  
  # Indicator Extremes
  - AOHighestValue: double
  - AOLowestValue: double
  - ACHighestValue: double
  - ACLowestValue: double
  
  # Trend
  - TrendLastWave: string    # "UP" or "DOWN"
  - TrendLastBar: string
  
  # Gator Analysis
  - NbBarMouthIsOpen: int
  - GatorMouthMaxOpenessMaxDistGLRL: double
  - GatorMouthMaxOpenessMaxDistRLBL: double
  - GatorMouthMaxOpenessMaxDistGLBL: double
  
  # Angle Data
  - AngleGatorDatadistGLRL: double
  - AngleGatorDatadistRLBL: double
  - AngleGatorDatadistGLBL: double
  - AngleGatorDatadistGLPrice: double
  - AngleGatorDatadistRLPrice: double
  - AngleGatorDatadistBLPrice: double
  - AngleGatorDatadistPriceMaxPrice: double
  
  # Market Overview
  - MarketOverViewerNodeCurrentIsDiverging: bool
  - MarketOverViewerNodeCurrentBdb: int
  - MarketOverViewerNodeCurrentDivA: double
  - MarketOverViewerNodeCurrentDivAPeakDt: DateTime
  - MarketOverViewerNodeCurrentDivB: double
  - MarketOverViewerNodeCurrentDivBPeakDt: DateTime
  - MarketOverViewerNodeCurrentTrendLastWave: string
  - MarketOverViewerNodeCurrentDivergenceIndicator: int
  - MarketOverViewerNodeCurrentStrengthOrder: int
  
  # Instrument Reference
  - InstrumentProperty: InstrumentProperty

Strategy Entities

BDBOStrategy

BDBOStrategy:
  # Identification
  - Idug: Guid               # Unique ID
  - CorrelationId: Guid      # Related data group
  
  # Core Properties
  - Instrument: string       # "EUR/USD"
  - Timeframe: string        # "H4"
  - BreakoutPrice: double    # Entry trigger price
  - BuySell: string          # "B" or "S"
  - Active: bool             # Monitoring enabled
  
  # State
  - StateName: string        # Current state name
  - StateId: int             # State enum value
  - Status: int              # Numeric status
  
  # Timestamps
  - Dt: DateTime             # Creation time
  - DtModified: DateTime     # Last modification
  - DtFirstAction: DateTime  # First state change
  
  # Risk Management
  - MPR: int                 # Max pip risk (120)
  - MaxPUI: int              # Max periods until invalid (1000)
  - DP: double               # Deactivation price
  
  # Order Tracking
  - CEOC: int                # Entry orders canceled
  - MaxEOC: int              # Max cancellations (5)
  - CTC: int                 # Trades created
  - MaxTC: int               # Max trades (3)
  - CFT: int                 # Failed trades
  
  # Validation
  - DiValid: int             # Divergence validation
  - VCP: int                 # Validation pattern
  
  # Twin Trade
  - TT: bool                 # Twin trade enabled
  - TTO: int                 # Twin trade option
  - K: int                   # Multiplier (1)
  
  # Exit Strategy
  - ExitStrategyTargetPrice: double
  - ExitStrategyType: int    # 1 = default
  
  # Metadata
  - Meta: string             # JSON metadata
  - Note: string             # User notes
  - IsNew: bool              # Unsaved flag

BDBOStrategyStateEnum

BDBOStrategyStateEnum:
  - Created = 0
  - Placed = 1
  - EntryOrderCanceled = 2
  - Filled = 3
  - Closed = 4
  - PriceBrokeOut = 5
  - Deactivated = 6

BDBOOrder

BDBOOrder:
  - Idug: Guid
  - StrategyIdug: Guid
  - OrderId: string          # External broker order ID
  - OrderType: string        # "Entry", "Exit", "StopLoss"
  - Side: string             # "Buy" or "Sell"
  - Price: double
  - Quantity: double
  - Status: string           # "Pending", "Filled", "Canceled"
  - Dt: DateTime
  - DtFilled: DateTime?
  - FilledPrice: double?
  - Message: string

BDBOTrade

BDBOTrade:
  - Idug: Guid
  - StrategyIdug: Guid
  - TradeId: string          # External trade ID
  - EntryOrderId: string
  - Side: string
  - EntryPrice: double
  - ExitPrice: double?
  - Quantity: double
  - PnL: double?
  - DtOpen: DateTime
  - DtClose: DateTime?
  - Status: string           # "Open", "Closed"

vBDBOStrategyOrderingHistory

vBDBOStrategyOrderingHistory:
  - Idug: Guid
  - StrategyIdug: Guid
  - Instrument: string
  - Timeframe: string
  - OrderId: string
  - EventType: string
  - EventDt: DateTime
  - Price: double
  - Message: string

Timeline Entities

TimelineItem

TimelineItem:
  - Id: Guid
  - Pov: string              # "EUR-USD_H4"
  - Tlid: string             # Timeline ID
  - Dt: DateTime
  - CdbCorrelationId: Guid
  - Note: string
  - Tags: List<string>

StrategyTimelineItem

StrategyTimelineItem:
  - Idug: Guid
  - StrategyIdug: Guid
  - Tlid: string
  - Dt: DateTime
  - EventType: string
  - PreviousState: string
  - NewState: string
  - BreakoutPrice: double
  - CurrentPrice: double
  - AO: double
  - AC: double
  - Zone: int
  - CdbSnapshotPath: string

CRSI Entities

CRSIGroup

CRSIGroup:
  - BaseCurrency: string     # "USD"
  - Timeframe: string        # "H4"
  - CrsiElements: List<CRSIElement>
  - CalculatedAt: DateTime

CRSIElement

CRSIElement:
  - IndexName: string        # "USD-EUR", "USD-GBP"
  - LineValue: List<IBasicDt> # CRSI values by date
  - MomentumValues: List<double> # AO on CRSI
  - Direction: int           # -1, 0, 1
  - Strength: double

Database Schema (SQL)

Tables

BDBOStrategies

CREATE TABLE BDBOStrategies (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    CorrelationId UNIQUEIDENTIFIER,
    Instrument NVARCHAR(50) NOT NULL,
    Timeframe NVARCHAR(10) NOT NULL,
    BreakoutPrice FLOAT NOT NULL,
    BuySell NVARCHAR(1) NOT NULL,
    Active BIT NOT NULL DEFAULT 1,
    StateName NVARCHAR(50) NOT NULL,
    StateId INT NOT NULL DEFAULT 0,
    Status INT NOT NULL DEFAULT 0,
    Dt DATETIME NOT NULL,
    DtModified DATETIME NOT NULL,
    DtFirstAction DATETIME,
    MPR INT DEFAULT 120,
    MaxPUI INT DEFAULT 1000,
    DP FLOAT,
    CEOC INT DEFAULT 0,
    MaxEOC INT DEFAULT 5,
    CTC INT DEFAULT 0,
    MaxTC INT DEFAULT 3,
    CFT INT DEFAULT 0,
    DiValid INT DEFAULT 0,
    VCP INT DEFAULT 0,
    TT BIT DEFAULT 0,
    TTO INT DEFAULT -1,
    K INT DEFAULT 1,
    ExitStrategyTargetPrice FLOAT,
    ExitStrategyType INT DEFAULT 1,
    Meta NVARCHAR(MAX),
    Note NVARCHAR(MAX),
    IsNew BIT DEFAULT 1
);

CREATE INDEX IX_BDBOStrategies_Active ON BDBOStrategies(Active);
CREATE INDEX IX_BDBOStrategies_POV ON BDBOStrategies(Instrument, Timeframe);

BDBOOrders

CREATE TABLE BDBOOrders (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    OrderId NVARCHAR(100),
    OrderType NVARCHAR(20) NOT NULL,
    Side NVARCHAR(10) NOT NULL,
    Price FLOAT NOT NULL,
    Quantity FLOAT NOT NULL,
    Status NVARCHAR(20) NOT NULL,
    Dt DATETIME NOT NULL,
    DtFilled DATETIME,
    FilledPrice FLOAT,
    Message NVARCHAR(MAX),
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug)
);

BDBOTrades

CREATE TABLE BDBOTrades (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    TradeId NVARCHAR(100),
    EntryOrderId NVARCHAR(100),
    Side NVARCHAR(10) NOT NULL,
    EntryPrice FLOAT NOT NULL,
    ExitPrice FLOAT,
    Quantity FLOAT NOT NULL,
    PnL FLOAT,
    DtOpen DATETIME NOT NULL,
    DtClose DATETIME,
    Status NVARCHAR(20) NOT NULL,
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug)
);

TimelineItems

CREATE TABLE TimelineItems (
    Id UNIQUEIDENTIFIER PRIMARY KEY,
    Pov NVARCHAR(50) NOT NULL,
    Tlid NVARCHAR(20) NOT NULL,
    Dt DATETIME NOT NULL,
    CdbCorrelationId UNIQUEIDENTIFIER,
    Note NVARCHAR(MAX),
    Tags NVARCHAR(MAX)
);

CREATE INDEX IX_TimelineItems_Pov ON TimelineItems(Pov, Tlid);

JSON Serialization

ChaosDataBuilder JSON Structure

{
  "Instrument": "EUR/USD",
  "Timeframe": "H4",
  "PovTlid": "2501311430",
  "ChartBars": [
    {
      "dt": "2025-01-31T10:00:00Z",
      "a": { "o": 1.0850, "h": 1.0860, "l": 1.0845, "c": 1.0855 },
      "b": { "o": 1.0849, "h": 1.0859, "l": 1.0844, "c": 1.0854 },
      "v": 1234,
      "l": 1.0823,
      "t": 1.0815,
      "j": 1.0810,
      "ao": 0.0012,
      "ac": 0.0003,
      "fb": null,
      "fs": 1.0860,
      "z": 1,
      "bdb": 0
    }
  ],
  "PipSize": 0.0001,
  "TrendLastWave": "UP",
  "InstrumentProperty": {
    "Symbol": "EUR/USD",
    "PipSize": 0.0001,
    "mar": { "MMR": 0.02, "LMR": 0.01 }
  }
}

Abbreviations in JSON

To minimize file size, BarChaosItem uses abbreviated keys:

dt = Date
a = Ask
b = Bid
v = Volume
l = Lips
t = Teeth
j = Jaw
ao = Awesome Oscillator
ac = Accelerator
fb = FractalBuy
fs = FractalSell
z = Zone
bdb = Bar Divergence Bar

Implementation Notes

Python ORM (SQLAlchemy)

from sqlalchemy import Column, String, Float, Boolean, DateTime, Integer, ForeignKey
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import relationship
import uuid

class BDBOStrategy(Base):
    __tablename__ = 'bdbo_strategies'
    
    idug = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    correlation_id = Column(UUID(as_uuid=True))
    instrument = Column(String(50), nullable=False)
    timeframe = Column(String(10), nullable=False)
    breakout_price = Column(Float, nullable=False)
    buy_sell = Column(String(1), nullable=False)
    active = Column(Boolean, default=True)
    state_name = Column(String(50), nullable=False)
    state_id = Column(Integer, default=0)
    dt = Column(DateTime, nullable=False)
    dt_modified = Column(DateTime, nullable=False)
    
    orders = relationship("BDBOOrder", back_populates="strategy")
    trades = relationship("BDBOTrade", back_populates="strategy")

TypeScript (Prisma Schema)

model BDBOStrategy {
  idug             String   @id @default(uuid())
  correlationId    String?
  instrument       String
  timeframe        String
  breakoutPrice    Float
  buySell          String
  active           Boolean  @default(true)
  stateName        String
  stateId          Int      @default(0)
  dt               DateTime
  dtModified       DateTime
  mpr              Int      @default(120)
  maxPui           Int      @default(1000)
  
  orders           BDBOOrder[]
  trades           BDBOTrade[]
}

model BDBOOrder {
  idug          String       @id @default(uuid())
  strategyIdug  String
  strategy      BDBOStrategy @relation(fields: [strategyIdug], references: [idug])
  orderId       String?
  orderType     String
  side          String
  price         Float
  quantity      Float
  status        String
  dt            DateTime
}