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

BDBOStrategyOrderRequest (from EF: pl.BDBOStrategyOrderRequests)

BDBOStrategyOrderRequest:
  - Idug: Guid               # PK
  - StrategyIdug: Guid        # FK → BDBOStrategy
  - DtRequested: DateTime     # When order was requested
  - EntryPrice: double        # Requested entry price
  - ExitPrice: double         # Planned exit/stop price
  - LimitPrice: double        # Limit price if applicable
  - K: int                    # Lot multiplier
  - BuySell: string(1)        # "B" or "S"
  - Meta: string(4096)        # JSON metadata
  - BarJSONData: string(2048) # CDB bar snapshot at request time

BDBOStrategyOrderResponse (from EF: pl.BDBOStrategyOrderResponses)

BDBOStrategyOrderResponse:
  - Idug: Guid               # PK
  - StrategyIdug: Guid        # FK → BDBOStrategy
  - RequestIdug: Guid         # FK → BDBOStrategyOrderRequest
  - DtOrderCreated: DateTime  # When broker confirmed order
  - OrderID: string(32)       # External broker order ID
  - TradeId: string(64)       # External trade ID (if filled)
  - Meta: string(4096)        # JSON metadata (broker response)

BDBOCancelOrderRequest (from EF: pl.BDBOCancelOrderRequests)

BDBOCancelOrderRequest:
  - Idug: Guid               # PK
  - StrategyIdug: Guid        # FK → BDBOStrategy
  - OrderID: string           # Broker order ID to cancel
  - DtRequested: DateTime     # When cancellation requested
  - Reason: string            # Why cancellation was requested

BDBOCancelOrderResponse (from EF: pl.BDBOCancelOrderResponses)

BDBOCancelOrderResponse:
  - Idug: Guid               # PK
  - StrategyIdug: Guid        # FK → BDBOStrategy
  - CancelRequestIdug: Guid   # FK → BDBOCancelOrderRequest
  - OrderID: string           # Broker order ID
  - DtCompleted: DateTime     # When cancellation confirmed
  - Success: bool             # Whether cancellation succeeded
  - Message: string           # Broker response message

BDBOTrade (from EF: pl.BDBOTrades)

BDBOTrade:
  - Idug: Guid
  - StrategyIdug: Guid        # FK → BDBOStrategy
  - TradeId: string           # External trade ID
  - EntryOrderId: string      # Linked order ID
  - Side: string              # "Buy" or "Sell"
  - EntryPrice: double
  - ExitPrice: double?
  - Quantity: double
  - PnL: double?
  - PnLPips: double?          # P&L in pips
  - DtOpen: DateTime
  - DtClose: DateTime?
  - Status: string            # "Open", "Closed"

vBDBOStrategyOrderingHistory (Database View)

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

Campaign Entity (NEW — envisioned)

Campaign:
  - Idug: Guid               # PK
  - Name: string(200)        # "EUR/USD Bearish H4 Feb 2026"
  - Direction: int            # 0=Undefined, 1=Bullish, 2=Bearish
  - Instrument: string(50)   # Primary instrument
  - Status: int               # 0=Active, 1=Paused, 2=Completed, 3=Archived
  - DtCreated: DateTime
  - DtCompleted: DateTime?
  - TotalPnL: double          # Aggregate P&L
  - MaxRiskAllocation: double  # Max capital allocation
  - CurrentRiskExposure: double
  - StrategyCount: int
  - Notes: string
  - Meta: JSON

CampaignStrategy Entity (NEW — join table)

CampaignStrategy:
  - CampaignIdug: Guid       # FK → Campaign
  - StrategyIdug: Guid        # FK → BDBOStrategy
  - Role: string(20)          # "primary", "hedge", "scale-in"
  - DtLinked: DateTime

Entity Relationships (Full)

Campaign ─┬──< CampaignStrategy >──┬── BDBOStrategy
           │                        │
           │                        ├──< BDBOStrategyOrderRequest
           │                        │      └──< BDBOStrategyOrderResponse
           │                        ├──< BDBOCancelOrderRequest
           │                        │      └──< BDBOCancelOrderResponse
           │                        ├──< BDBOTrade
           │                        └──< vBDBOStrategyOrderingHistory (view)
           │
           └── Campaign Notes / Journal

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);

BDBOStrategyOrderRequests (from EF schema: pl.BDBOStrategyOrderRequests)

CREATE TABLE BDBOStrategyOrderRequests (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    DtRequested DATETIME NOT NULL,
    EntryPrice FLOAT,
    ExitPrice FLOAT,
    LimitPrice FLOAT,
    K INT DEFAULT 1,
    BuySell VARCHAR(1) NOT NULL,
    Meta VARCHAR(4096),
    BarJSONData VARCHAR(2048),
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug)
);

BDBOStrategyOrderResponses (from EF schema: pl.BDBOStrategyOrderResponses)

CREATE TABLE BDBOStrategyOrderResponses (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    RequestIdug UNIQUEIDENTIFIER NOT NULL,
    DtOrderCreated DATETIME NOT NULL,
    OrderID VARCHAR(32),
    TradeId VARCHAR(64),
    Meta VARCHAR(4096),
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug),
    FOREIGN KEY (RequestIdug) REFERENCES BDBOStrategyOrderRequests(Idug)
);

BDBOCancelOrderRequests

CREATE TABLE BDBOCancelOrderRequests (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    OrderID VARCHAR(32) NOT NULL,
    DtRequested DATETIME NOT NULL,
    Reason NVARCHAR(500),
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug)
);

BDBOCancelOrderResponses

CREATE TABLE BDBOCancelOrderResponses (
    Idug UNIQUEIDENTIFIER PRIMARY KEY,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    CancelRequestIdug UNIQUEIDENTIFIER NOT NULL,
    OrderID VARCHAR(32),
    DtCompleted DATETIME NOT NULL,
    Success BIT NOT NULL,
    Message NVARCHAR(MAX),
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug),
    FOREIGN KEY (CancelRequestIdug) REFERENCES BDBOCancelOrderRequests(Idug)
);

BDBOTrades (updated from EF schema)

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,
    PnLPips FLOAT,
    DtOpen DATETIME NOT NULL,
    DtClose DATETIME,
    Status NVARCHAR(20) NOT NULL,
    FOREIGN KEY (StrategyIdug) REFERENCES BDBOStrategies(Idug)
);

Campaigns (NEW — envisioned)

CREATE TABLE Campaigns (
    Idug UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
    Name NVARCHAR(200) NOT NULL,
    Direction SMALLINT NOT NULL DEFAULT 0,
    Instrument NVARCHAR(50) NOT NULL,
    Status SMALLINT NOT NULL DEFAULT 0,
    DtCreated DATETIME NOT NULL DEFAULT GETDATE(),
    DtCompleted DATETIME,
    TotalPnL FLOAT DEFAULT 0,
    MaxRiskAllocation FLOAT,
    CurrentRiskExposure FLOAT DEFAULT 0,
    StrategyCount INT DEFAULT 0,
    Notes NVARCHAR(MAX),
    Meta NVARCHAR(MAX)
);

CREATE INDEX IX_Campaigns_Status ON Campaigns(Status);
CREATE INDEX IX_Campaigns_Instrument ON Campaigns(Instrument);

CampaignStrategies (NEW — join table)

CREATE TABLE CampaignStrategies (
    CampaignIdug UNIQUEIDENTIFIER NOT NULL,
    StrategyIdug UNIQUEIDENTIFIER NOT NULL,
    Role NVARCHAR(20) DEFAULT 'primary',
    DtLinked DATETIME NOT NULL DEFAULT GETDATE(),
    PRIMARY KEY (CampaignIdug, StrategyIdug),
    FOREIGN KEY (CampaignIdug) REFERENCES Campaigns(Idug),
    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
}