This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
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.
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
# 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'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).
package_format_version: 1— required, always 1id— reverse-domain style, e.g.io.timeplus.market-datadb_name— database created for all resources; pattern^[a-z][a-z0-9_]{0,31}$resources— list of DDL files withfile,type, andname; executed in listed orderconfig— optional user-supplied parameters withkey,type,required,default
Resource types: stream, external_stream, mutable_stream, materialized_view, view, external_table, udf, task, system.
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}}).
- One SQL statement per file — multi-statements fail at install time.
IF NOT EXISTSon everyCREATE— 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_startandwindow_endare generated bytumble/hop; don't use them as stream column names; alias them in the MV SELECT instead.
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.
| 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 |