Tutorial: Onboarding a New Tenant

In this tutorial you will onboard a new client from scratch: receive their data, create a tenant instance, run the extraction and build pipeline, explore the results, and freeze a snapshot. This is the workflow a consultant follows when starting with a new client.

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

1. The scenario

A new winery — Domaine Nouveau — wants to use your analytical framework. They’ve sent you an Excel export from their ERP system. You need to turn this into a working analytical environment.

2. Set up the Data Landing Zone

The DLZ is where raw source data arrives, separate from jinflow’s working directories.

# Configure your DLZ root (one-time)
jinflow us --dlz ~/jinflow-datalandingzone

# Create the tenant's DLZ directory
mkdir -p ~/jinflow-datalandingzone/millesime/domaine_nouveau/custom/csv/

Place the client’s CSV files (or XLSX for extraction) in this directory:

jinflow-datalandingzone/
  millesime/
    domaine_nouveau/
      custom/
        csv/
          parcels.csv
          harvests.csv
          wines.csv
          ...

3. Create the tenant

jinflow init --pack millesime --tenant domaine_nouveau \
  --source-system custom \
  --dlzroot ~/jinflow-datalandingzone \
  --display-name "Domaine Nouveau"

This creates a tenant instance in your live root:

~/.jinflow/live/millesime/domaine_nouveau/
  afs/       ← copy of the millesime pack (signals, theses, dbt, etc.)
  raw/       ← empty, waiting for data
  build/     ← empty
  store/     ← empty

Set it as your default:

jinflow us --tenant millesime.domaine_nouveau

4. Sync data from DLZ

If the client sent XLSX files, extract them first:

jinflow make --extract    # XLSX → CSV in DLZ, then sync to raw/

If they sent CSVs directly:

jinflow make --sync       # copy CSVs from DLZ to raw/

Verify the data landed:

jinflow stat

This shows gold layer counts, signal counts, and health checks. On a fresh sync before the first build, it will show the CSV file counts in raw/.

5. Build

jinflow make

The full pipeline runs:

1. Validate and enrich CSVs
2. Compile all instruments from the pack
3. dbt build (Bronze → Silver → Gold → Signals → Theses → Verdicts)
4. Generate reports and pipeline graph
5. Stamp KLS and create SIS

Watch the output — if any CSVs fail validation, the error messages will tell you exactly what’s wrong (missing columns, wrong types, etc.).

6. Explore

jinflow explore

Browse the results at localhost:4000:

• Overview — confirmed theses, total exposure
• Findings — what the signals detected
• Theses — which business questions have evidence
• Dimensions — browse the client’s actual data

This is the moment you show the client: “Here’s what we found in your first dataset.”

7. Snapshot

Happy with the initial analysis? Freeze it:

jinflow make --snapshot onboarding

This creates an immutable snapshot you can always return to:

jinflow explore --snapshot onboarding    # revisit anytime

8. Collaborate

If a colleague needs to work on this tenant:

# You: push the AFS to GitHub
jinflow afs remote https://github.com/org/afs-millesime-domaine_nouveau.git
jinflow afs push -m "Initial onboarding complete"

# Colleague: clone and build
jinflow init --clone https://github.com/org/afs-millesime-domaine_nouveau.git
jinflow make --tenant millesime.domaine_nouveau --sync

9. Keep it current

When the client sends new data:

# Place new CSVs in the DLZ
jinflow make --sync      # sync new data
jinflow make             # rebuild
jinflow make --snapshot  # freeze if significant

When the pack is updated with new signals:

jinflow afs update --do-it    # pull pack changes
jinflow make                  # rebuild with new instruments

What you learned

• DLZ is the intake boundary — raw data arrives here, never in the jinflow live root
• jinflow init --pack copies a domain pack into a new tenant instance
• --sync copies changed CSVs from DLZ to raw/; --extract converts XLSX first
• jinflow stat shows what’s in the KLS before and after builds
• Snapshots freeze your work — clients can see their onboarding state anytime
• AFS push/pull enables team collaboration on the same tenant

Next steps

• Tutorial: Publishing a Domain Pack — package your framework for reuse (coming soon)
• Tenants Guide — multi-tenant architecture
• Collaboration Guide — git workflows
• Glossary — every term explained