Aura/docs/project-layout.md

How aura is used — engine, projects, and a day in the life

This document describes the outside of aura: how you sit in front of it and what a research session looks like. The inside (the engine's contracts) is the design ledger (docs/design/INDEX.md).

Engine vs. project (the game-engine split)

aura is a game engine for traders, and like any game engine it is separate from the things built with it:

• This repo (aura) is the engine: aura-core (the shared contract), aura-std (universal standard nodes), aura-engine (the deterministic sim runtime), aura-cli (the aura binary), and later the egui playground. It ships at most examples/ fixture nodes for its own tests — never your real signals.
• A research project is its own external repo (e.g. ~/dev/ger40-lab/), with its own git history, its own Gitea repo (its own forward-queue), and a cargo dependency on aura. This is where you and Claude author signals and where the runs live. (See contract C16.)

The aura CLI is a tool you run inside a project directory — it finds the project root by walking up to an Aura.toml, the way cargo finds Cargo.toml.

A project repo

ger40-lab/                 # your research project — a separate repo
├── Aura.toml              # project config: symbols in scope, default data
│                          # window, broker profile, runs dir  (schema TBD)
├── Cargo.toml             # depends on aura-core (+ shared node crates)
├── CLAUDE.md              # the project's own skills wiring (authoring discipline)
├── .claude/dev-cycle-profile.yml
├── nodes/                 # project-local, experimental nodes (cdylib)
│   └── third-candle-long/
├── runs/                  # the run registry: manifest + metrics per run
└── (frozen bots, results, …)

Where reusable nodes live (three tiers)

Everything that plugs into the engine is fractally a Node. Reuse is plain cargo, layered by maturity (contract C16):

1. aura-std — universal blocks shipped with the engine (SMA/ATR/RSI, resamplers, the SessionNode, standard combinators, broker profiles).
2. Shared node crates — cross-project-reusable blocks in their own repos (e.g. Brummel/aura-nodes-fx), pulled in as cargo git dependencies.
3. Project-local nodes/ — experimental, project-specific blocks.

Promotion is the ordinary Rust gradient: a node proves itself project-local → gets extracted into a shared crate → if it turns universal, into aura-std. Shared nodes are rlib dependencies; the hot-reload unit stays the project-side cdylib that composes them, so editing a shared node still rebuilds and reloads the dependent.

Authoring happens in Claude Code (contract C17)

aura has no built-in coding-LLM. You author by talking to Claude Code, which writes the node crate, builds it, runs it, and reports back. IONOS LLMs appear only as a runtime data source (e.g. a news-agent node emitting a bias), recorded before it enters a backtest, and only with your per-session consent.

A day in the life

1. You (in Claude Code, inside ger40-lab/): "I suspect the 3rd 15m candle after GER40 open is long-biased when the first two close bullish — build it as a signal."
2. Claude (via the skills pipeline) writes nodes/third-candle-long/, implements schema + eval against aura-core.
3. Backtest: aura backtest nodes/third-candle-long --symbol GER40 --from 2020 --to 2024 → the strategy produces a broker-independent position table (open/close events); the default sim-optimal broker projects it into a synthetic pip-equity, yielding a metrics table (trades, hit-rate, pip-P&L, max-DD, Sharpe) + a run record (manifest + metrics) under runs/. Add --broker pepperstone to project the same table through a realistic broker (currency, friction) for viability. (Contract C10.)
4. Sweep + Monte-Carlo: aura sweep … --grid lookback=5..50,thresh=0.5..0.9 --mc-seeds 1000 → a distribution of metrics, best params, robustness bands.
5. Compose: "combine it with momentum-filter as a weighted sum" → Claude writes a composite node (fractal, C9).
6. Walk-forward: aura walkforward … → an out-of-sample verdict.
7. Freeze: aura freeze nodes/strategy-y --broker pepperstone --out bots/strategy-y → a standalone, statically-linked bot (C13).
8. (Later) Look: aura play opens the egui playground — equity curve, trade overlays on the chart, sweep heatmaps. For looking, not authoring (C14).

CLI command names and Aura.toml are illustrative; the concrete surface is designed with the relevant milestone (see the open threads in the design ledger). The forward-queue — what to try next — lives in the project's Gitea tracker, not in code (contract C18).