Getting started with Spring authoring

The recorded screenshots may show an earlier menu layout. Current navigation uses Project, Sources and Audit log; see Getting started.

Use an LLM as your design partner and the analyser as the window you share. Agree what the application should do, inspect its Spring XML, then compare actual results with your expectations. The LLM edits and runs the project through its own tools; the analyser displays design and evidence.

Guided means a conversation following the project's runbooks. It is optional, with no special runtime mode or separate “guided” project type. You can follow the same steps yourself.

Spring authoring in starter 1.0.74

New standalone and hosted Spring AOT downloads include the local authoring record and setup.sh, validate.sh and generate.sh. Setup and XML validation need no compilation key; generation needs the backend prerequisites below. The hosted launcher is run-server.sh; the standalone launcher is run.sh.

Keep the starter and BOM versions together when upgrading an existing project. Update starterVersion in fluxtion-authoring.json and fluxtion.bom.version in the POM to 1.0.74, keep your source and ownership history, and run ./setup.sh again. An older hosted download missing the authoring scripts needs a fresh download; changing its POM alone does not add them.

Choose your starting point

You want to…	Start here
Learn the analyser without building anything	Guided analyser tour, using its included demo log.
Run an existing example and examine its evidence without a compilation key	Playground to analyser, using the Audit analyser bundle.
Design and change an application in Spring XML	This guide, using Fluxtion Spring XML.
Host a Spring design in Mongoose	Use Fluxtion Spring in Mongoose and its hosting/build runbooks. Starter 1.0.74 downloads include the local authoring workflow below; use run-server.sh for the host.

For the Spring path, use JDK 21, network access for provisioning, and analyser 1.16.0 or later. Your local LLM needs access to the downloaded project and a terminal. Generation through RapidAPI also needs a configured, subscribed compilation key; an installed local generator is a different route. XML validation itself is keyless.

1. Download a project

In the analyser, choose Project ▸ New project from template… (or From template, under Create, on the start page). Choose Fluxtion Spring XML, read its prerequisites, and download into an empty directory. A shipped profile opens automatically. The analyser does not build it for you.

Alternatively, open the website starter, choose the template through Templates, and leave Analyser support enabled. To download directly:

curl --fail --location \
  'https://fluxtion-playground.dev/start/scaffold?template=fluxtion-spring&artifact=spring-first-project&group=com.acme&basePackage=com.acme.springdemo' \
  --output spring-first-project.zip
unzip -l spring-first-project.zip
unzip spring-first-project.zip
cd spring-first-project

The website and local LLM can acquire the project before an analyser is running. There is no need to run a local playground or docs server. Analyser support is on by default, including older shared configurations; an explicit opt-out removes its profile/integration files.

Read PROJECT.md, then RUNBOOK.md. Check that these files exist:

File	Purpose
src/main/fluxtion/designer/application-context.xml	The declared graph.
src/main/java/	Node behaviour, event types and application code.
fluxtion-authoring.json	Pinned starter version and source ownership history; keep it in version control.
PROJECT.md, RUNBOOK.md, runbooks/	The project's entry point and task instructions.
.analyser/project.fluxtion-settings	Source roots, processor declarations and runbook pointers.

The sample names a market-data node, volatility and sentiment calculations, a risk engine and an order gate. These are starter scaffolding, not implemented trading rules. Agree and test the behaviour before treating a class name as a capability.

2. Open the shared canvas and connect your LLM

Start the released analyser. If you downloaded outside the analyser, choose Project ▸ Open project… and select .analyser/project.fluxtion-settings directly.

Checkpoint: the project name and runbooks appear, while the page honestly says No log loaded and No graph. A declared processor and a source shell are not proof of a successful build.

Choose where your LLM runs:

• In your terminal or IDE. Open your LLM client in the same project directory. In the analyser, use AI ▸ Set up AI… ▸ Your own AI client and follow the steps for that client. See Connect your client. The download does not contain a machine-specific MCP endpoint: configure the actual running analyser, then have the client call analyser_context.
• In the analyser. Claude Code can run in the assistant panel, working in the open project's folder. Building needs Full Claude Code, because Safe analysis cannot edit files or run commands (Claude Code in the analyser).

Model choice

Which model to run your LLM client with, for the task family that has been measured: authoring with the Fluxtion Spring XML starter (this guide) and with the Audit analyser bundle (Playground to analyser). Each row rests on committed run evidence, and a test reads that evidence on every build: each row's status must agree with the runs' PASS (per rung) or chart result. The cost figures below are taken from the same runs but are not checked by that test.

model	status	evidence folder	field	the test checks
Claude Haiku 5.5 (claude-haiku-5-5)	default — meets acceptance on rungs 3–5; open on rung 2 (the chart step: 1 of 3 runs passed)	docs/handoff/evidence/authoring-ladder-baseline-2026-10-13	PASS per rung	rungs 3–5 at least 2 of 3; rung 2 below 2 of 3
Claude Sonnet 5 (claude-sonnet-5)	advisory: not recommended — on the first ladder, no rung where it passed and the default did not, at 16.5–30× the cost per run	docs/handoff/evidence/authoring-ladder-2026-10-12	PASS per rung, both models	no rung where Sonnet 5 passed and Haiku 5.5 is below 2 of 3
Claude Haiku 4.5 (claude-haiku-4-5-20251001)	negative: not for the chart step	docs/handoff/evidence/g14-model-grid-2026-10-11	checks.S5	checks.S5 false in every run
Others (Opus-class, …)	unmeasured	—	—	—

• Rungs are the authoring ladder's tasks: rungs 2 and 4 on the Spring starter, rungs 3 and 5 on the analyser bundle. A run passes only when its oracle, the design validation and its chart in the analyser all pass.
• Cost: on the first ladder, where both models ran, the default's median was $0.19 per run and Sonnet 5's $3.43, about 18 times more; on the baseline the default's median was $0.13.
• When a step fails, re-run that step with the default before paying for a larger model. This is advice, not a measured result: no failure has yet been re-run with a larger model under the same conditions.
• This choice is for your own LLM client (Claude Code, Codex and similar). It does not cover the analyser's in-app assistant, whose provider and model are set on the Settings ▸ LLM tab; nothing there was measured.
• The measured runs drove Claude Code from a test harness, outside the analyser. Claude Code in the analyser, whose model is set under Settings ▸ Assistant, was not measured separately.

Paste this prompt once the client can access the project and analyser:

Give me a guided first session with this Spring authoring project.
Read PROJECT.md, RUNBOOK.md, fluxtion-authoring.json and the declared runbooks.
Call analyser_context and confirm which project and files the window is showing.

Start by showing the XML design and explaining the nodes and dependency directions.
Ask what behaviour I want before editing anything. Agree one small input sequence
and expected outputs with me before writing the implementation.

Use the project's tools for validation, generation and execution. Check prerequisites
first; stop at provisioning or key failures and show the actual error. Keep the
download's dependency coordinates. The analyser is our canvas, not our build runner.

After each stage, tell me what to look at in the analyser and verify its context.
Keep XML validity, a successful build, and observed application behaviour separate.
End with one question answered from actual evidence and the next step written down.

3. Inspect the design before running it

In Sources ▸ Source roots…, keep the existing Java root and add the project's src/main/fluxtion/designer directory. Add target once it exists to authorise producer reports. Opening a project alone does not authorise every file beneath it.

Choose Sources ▸ Open design…, select application-context.xml, then select riskEngine in the Source tab's bean index. A connected LLM can make the same selection with analyser_source {"bean":"riskEngine"} after opening the design.

Checkpoint: you can read the declaration before any compilation or run. Follow design refreshes it after edits. “Relationship to this run unverified” is not an error: the working XML has not been proven to describe a loaded execution.

Ask the LLM: “What feeds this node? Which references should trigger it, and which should only supply data?” The capability guide explains DATA, TRIGGER, events, services and lifecycle declarations.

Keep supplier classes in their dependency jar

Prefer referencing the supplier root from your own node. Tools through 1.0.73 could write a shell over a dependency-only nodeBeans class; the build stayed green while the intended component disappeared. The dependency-shadowing issue records that failure. Starter 1.0.74 local reconciliation checks the classpath written by setup before emitting a shell. Refresh setup after changing dependencies. The browser generator cannot inspect your local dependency jars, so do not use its fresh-class skeletons as replacements for supplier classes. Check the generated graph and actual results.

The website also previews imported XML as a graph. This separate two-node example shows its declaration view; its arrow points from child to its dependency rootNode:

This is not the runtime graph for the five-node sample above. Use generated GraphML and a matching audit log when investigating execution.

4. Validate and read a real finding

Run the shipped project commands:

./setup.sh
./validate.sh --summary-detail

setup.sh fetches the pinned tool and resolves the classpath. Stop if it fails; do not treat an incomplete setup as successful validation. Validation checks XML declarations without loading your node classes. It writes target/fluxtion-validation.json.

In the analyser, choose Sources ▸ Open producer diagnostics… and open that JSON file. The result appears under Reports ▸ Producer findings.

For a small learning exercise, save the original XML, change only the orderGate value inside nodeBeans to missingNode, and validate. The command should fail. Open its new result:

Checkpoint: the analyser shows the missing declaration and a suggested correction. It also says that matching XML is not a successful build. Show navigates to the reported location; approximate locations are labelled.

Restore orderGate, validate again, and reopen the result:

“No findings” here means this XML validation produced none. It does not prove Java compilation or correct business calculations. Reopen diagnostics after each producer run; do not rely on an older displayed result.

5. Implement, generate and run after setup succeeds

Continue only after provisioning works and the project's generation route is available. Have the LLM implement the agreed behaviour in the node classes, with assertions for your expected outputs. Then follow RUNBOOK.md:

./generate.sh
./run.sh

Reconciliation plans source changes first, preserves implemented bodies where ownership permits, and refuses conflicts. Read the refusal rather than deleting ownership records to get past it.

Generated callback facts, authored business values

Starter 1.0.74 adds INFO audit scaffolding to newly generated handlers, triggers and lifecycle methods. A handler logs the handled event and relevant filter, a trigger logs that it fired, and a lifecycle method logs its phase. Fresh classes receive EventLogNode; reconciliation preserves an existing superclass and uses the logger callback interface when needed. Conflicting developer logger setup is refused.

You still implement and log the state behind your decisions, such as a count, price or threshold. Callback facts establish execution; they do not establish business correctness. Existing implemented bodies are preserved, not rewritten to add logging. Filter strings are altered for safe display, not retained losslessly; see the callback contract.

On older tools through 1.0.73, new nodes need manual audit scaffolding; see the original issue and the reviewed workaround. That case preserved a manually added EventLogNode superclass and audit-writing body across later reconciliation. Always check the emitted audit values after a real run.

The build receipt is target/fluxtion-run.json; compilation diagnostics belong to the latest attempt only when that receipt says the compiler ran and its input checks still hold.

The default remote route requires a compilation key. Configure it using the project's preflight instructions or AI ▸ Fluxtion API key…, never by committing it. An installed local provider can be keyless; a custom HTTP host is not automatically a local provider.

The screenshots show download, design rendering and XML validation. The separate 1.0.73 release check verifies the standalone setup, changed-design generation and sample run. Starter 1.0.74 adds the hosted authoring record and scripts. For a Mongoose template, use its emitted run-server.sh and host runbook; do not substitute the standalone run.sh commands.

6. Answer one question from evidence

Once you have an actual successful run, open its audit log and generated GraphML in the analyser. Use the project runbook to locate them; an expected filename is not evidence the file exists. An XML preview, generated topology and runtime audit each answer a different question.

For the scenario we agreed, compare expected and observed outputs independently.
Show the relevant audit cycles, topology and source in the analyser. Plot only
values that actually exist in the log. Point at the evidence before explaining it.
Create a report that separates observations, interpretation and untested cases.

The LLM can drive the same window you inspect. Challenge its answer by opening the selected records and source. An unlogged node is not proof of non-execution, and unchanged existing outputs alone do not prove a newly added calculation is correct.

Come back tomorrow

Keep XML, source, fluxtion-authoring.json and project runbooks in version control. Preserve the logs and outputs needed to reproduce your conclusions. On project reopen or analyser relaunch, choose Restore last session explicitly; changed or missing inputs may be withheld.

A restored canvas does not restore an LLM conversation. Start the new client in the project, ask it to reread PROJECT.md and current results, then call analyser_context before continuing. For examples of the conversation, see Design and “what if?” questions.

If open {design: ...} refuses an existing file outside the configured source roots, the refusal includes the exact source_root {"add": ["..."]} call for its real parent directory. Review that directory before granting access, then retry the design open; the refusal itself changes no roots.