Skip to content

Latest commit

 

History

History
126 lines (93 loc) · 5.4 KB

CLAUDE.md

File metadata and controls

126 lines (93 loc) · 5.4 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

A collection of Timeplus apps (.tpapp packages). Each app is a zip archive bundling a streaming data pipeline — DDL SQL files and dashboard JSON — installable into a Timeplus instance via REST API.

There is also a skill/ directory containing a Claude Code skill (SKILL.md) for creating Timeplus apps.

Repository Layout

apps/
├── apps/
│   └── market-data/       # each app lives here; add new apps as siblings
│       ├── Makefile
│       ├── manifest.yaml
│       ├── ddl/
│       └── dashboards/
├── skill/                 # Claude Code skill for creating Timeplus apps
├── Makefile               # root delegate — use APP=<name> to target an app
└── CLAUDE.md

Commands

# Build a .tpapp package (default: market-data)
make build

# Build and install (requires Timeplus running at localhost:8000)
make install

# Target a different app
make build APP=my-other-app

# Override Timeplus endpoint
make install APP=market-data NEUTRON_URL=http://my-host:8000 TENANT=my-tenant

# Build/install from within the app directory directly
cd apps/market-data && make build

# Install manually
curl -X POST http://localhost:8000/default/api/v1beta2/apps/install \
  -F "file=@apps/market-data/market-data.tpapp"

# Check Python package install status after SYSTEM INSTALL
# (run inside Timeplus SQL console)
SELECT * FROM system.python_packages WHERE name = 'websocket-client'

App Package Structure

Each app directory follows this layout:

apps/my-app/
├── Makefile               # builds my-app.tpapp in the same directory
├── manifest.yaml          # package metadata, resource list, config schema
├── ddl/
│   ├── 001_*.sql          # executed in filename sort order
│   └── ...
└── dashboards/
    └── main.json          # array of panel objects

The built .tpapp file is output to the app's own directory (apps/my-app/my-app.tpapp).

manifest.yaml

  • package_format_version: 1 — required, always 1
  • id — reverse-domain style, e.g. io.timeplus.market-data
  • db_name — database created for all resources; pattern ^[a-z][a-z0-9_]{0,31}$
  • resources — list of DDL files with file, type, and name; executed in listed order
  • config — optional user-supplied parameters with key, type, required, default

Resource types: stream, external_stream, mutable_stream, materialized_view, view, external_table, udf, task, system.

DDL Template Variables

DDL files use Go text/template with {{ }} delimiters:

Expression Value
{{ .DB }} resolved db_name
{{ .Config.key_name }} config value (always use dot notation — never use index syntax)

Dashboard JSON uses [[ ]] delimiters (to avoid collision with frontend filter variables like {{filter_product}}).

DDL Authoring Rules

  • One SQL statement per file — multi-statements fail at install time.
  • IF NOT EXISTS on every CREATE — makes installs idempotent and safe on re-install.
  • SYSTEM INSTALL PYTHON PACKAGE — omit the trailing semicolon; one package per file; installation is async, so dependent external streams may fail if created immediately after.
  • Numeric filename prefix — controls execution order; dependencies must appear earlier in the sequence.
  • Reserved column names — window_start and window_end are generated by tumble/hop; don't use them as stream column names; alias them in the MV SELECT instead.

Architecture: market-data App

The market-data app is a real-time crypto pipeline from the Coinbase WebSocket feed:

SYSTEM INSTALL python packages (json5, websocket-client)
  └── coinbase_websocket_read_connector  (external stream, Python streaming function)
        └── mv_coinbase_tickers_extracted  (MV that parses JSON → coinbase_tickers)
              ├── coinbase_tickers  (raw ticker stream, 24h TTL)
              │     ├── v_coinbase_btc_ohlc_1m → v_coinbase_btc_1m_ret → v_coinbase_btc_1m_rsi
              │     ├── coinbase_ohlc_1m_vkv (mutable stream, PK: time+symbol)
              │     │     └── mv_ohlc_by_symbol (MV populating the mutable stream)
              │     └── coinbase_1s (1-second OHLC stream)
              │           └── mv_coinbase_1s (MV populating coinbase_1s)
              │                 └── v_alpha_* (10 individual alpha signal views)
              │                       └── v_alpha_composite (combines 4 signals)

Alpha signals (all views over coinbase_1s, partitioned by product_id): momentum, mean reversion, spread pressure, MA crossover, price acceleration, Bollinger position, VWAP deviation, trade flow, spread regime, volume spike, and composite.

Common Install Errors

Error message Cause Fix
Multi-statements are not allowed Multiple SQL statements in one file One statement per file
Column window_start is reserved Using window_start as a stream column Rename to time; alias in MV
No module named 'X' Python package not yet installed Wait for status = 'installed' in system.python_packages
provision <name>: ... DDL failed for named resource The prefix identifies which file failed