Tutorial: Your First Build

In this tutorial you will create a tenant, write a signal, build a knowledge store (KLS), and explore the results in the browser. No domain pack needed — you’ll build everything from scratch.

Time: 15 minutes Prerequisites: jinflow installed (Quick Start)

1. Create a tenant

A tenant is your analytical workspace — it holds your data, instruments, and build output.

jinflow init --tenant my_first_analysis --source-system opale

This creates a directory structure:

~/.jinflow/live/default/my_first_analysis/
  afs/        ← your instruments go here
  raw/        ← your source CSVs go here
  build/      ← intermediaries (managed by jinflow)
  store/      ← KLS output (managed by jinflow)

Set it as your default so you don’t have to type --tenant every time:

jinflow us --tenant default.my_first_analysis

2. Add source data

Place CSV files in the raw/ directory. For this tutorial, create a minimal dataset:

# Find your tenant's raw directory
jinflow us
# Look for "Live root" in the output, then navigate to:
# {live_root}/default/my_first_analysis/raw/opale/csv/

Create a file cases.csv:

case_id,case_type,admission_date,discharge_date,cost_center_id,status
CASE_001,inpatient,2025-01-15,2025-01-20,CC_OR1,closed
CASE_002,outpatient,2025-01-16,,CC_ER,open
CASE_003,inpatient,2025-01-17,2025-01-25,CC_OR1,closed
CASE_004,day_case,2025-01-18,2025-01-18,CC_DAY,closed
CASE_005,inpatient,2025-01-19,2025-01-22,CC_OR2,closed

And a file billing_events.csv:

billing_id,case_id,material_id,quantity,unit_price,billing_date,status
BILL_001,CASE_001,MAT_A,2,150.00,2025-01-20,posted
BILL_002,CASE_001,MAT_B,1,500.00,2025-01-20,posted
BILL_003,CASE_003,MAT_A,3,150.00,2025-01-25,posted
BILL_004,CASE_005,MAT_C,1,2000.00,2025-01-22,pending

Notice: CASE_002 and CASE_004 have no billing events. This is the anomaly your signal will detect.

3. Write your first signal

Create a file in your AFS at afs/probes/probe_unbilled_cases.yaml:

probe_id: probe_unbilled_cases
version: "1.0.0"
contract: "gold.v1"
type: mandatory_item
severity: high
description: "Detect cases that have no billing events"

scope:
  entity_type: Case
  group_by: [case_id]
  time:
    entity: Case
    field: admission_date
    bucket: month

qualifying:
  entity: Case
  join_key: case_id

required:
  entity: BillingEvent
  join_key: case_id
  min_count: 1

money_at_risk_fixed: 500

This signal says: “For every case, there should be at least one billing event. Flag the ones that don’t.”

4. Build

jinflow make

jinflow will:

1. Validate your CSVs
2. Compile your signal YAML to SQL
3. Run dbt (Bronze → Silver → Gold → Signals)
4. Stamp the KLS

Watch the output — you should see your signal being compiled and built.

5. Explore

jinflow explore

This opens the Explorer in your browser at localhost:4000. Navigate to:

• Signals — you’ll see probe_unbilled_cases listed
• Findings — you’ll see findings for CASE_002 and CASE_004 (the unbilled cases), each with severity high and money_at_risk 500

6. Iterate

Now try modifying your signal. Open afs/probes/probe_unbilled_cases.yaml and change severity: high to severity: medium. Then:

jinflow make

Refresh the Explorer — the findings now show medium severity. This is the make → explore → evolve cycle that drives all jinflow work.

7. Snapshot

Happy with your analysis? Freeze it:

jinflow make --snapshot first-analysis

This creates an immutable copy of your KLS. You can always come back to it:

jinflow explore --snapshot first-analysis

What you learned

• A tenant is your analytical workspace
• Signals are YAML files that define diagnostic queries
• jinflow make compiles YAML → SQL → DuckDB
• jinflow explore serves the results in a web UI
• Snapshots freeze your work for future reference

Next steps

• Tutorial: From Finding to Verdict — write a thesis and verdict (coming soon)
• Instruments Guide — all instrument types
• YAML Signal Reference — all signal fields and types
• Glossary — every term explained