ZZ / Gemma4 DSL Intro

# ========================================================================
# PROJECT: User Onboarding Flow
# VERSION: 1.0.0
# DESCRIPTION: Handles user registration, account creation,
#              parallel profile setup, and dashboard entry.
# ========================================================================
# --- GLOBAL STATE DEFINITIONS ---
$user_id = null
$onboarding_status = "not_started"
$account_created = false
# --- MODULE: PROFILE SETUP (The Parallel Block) ---
# This module handles three tasks that can happen in any order.
Module ProfileSetup {
    docs: "docs/profile_setup.md",
    # Start by splitting the flow into three parallel paths
    Profile.Start F-> [Profile.Username, Profile.Photo, Profile.Interests]
    # Individual Node Logic
    Profile.Username /input /save {name} -> Profile.Join
    Profile.Photo    /upload /save {img}  -> Profile.Join
    Profile.Interests /select /save {tags}  -> Profile.Join
    # Synchronize: Wait for ALL three to finish before completing the module
    [Profile.Username, Profile.Photo, Profile.Interests] J-> Profile.Complete
    return {profile_complete: true}
}
# --- MAIN APPLICATION FLOW ---
# 1. Welcome & Email Entry
Welcome.Screen /start /show [doc: "docs/welcome.md"] {email} -> Auth.ValidateEmail
# 2. Email Validation (Branching Logic)
Auth.ValidateEmail /check /verify {email} ? [
    exists -> Welcome.Error {msg: "Email already taken"} -> Welcome.Screen,
    available -> Auth.CreateAccount
]
# 3. Account Creation (External API & Async Wait)
Auth.CreateAccount /execute /call [doc: "docs/account_creation.md"]
    EXT:AuthService.CreateAccount /post /register {$api_key} {email}
    -> WAIT (Account_Created)
    T [5m] -> Auth.Timeout_Handler # If API takes > 5 mins, fail
    -> $user_id = {uid}
    -> $account_created = true
    -> Call ProfileSetup
# 4. Transition to Dashboard
ProfileSetup.Complete -> Dashboard.Welcome /render /show {$user_id}
    -> $onboarding_status = "completed"
    -> Dashboard.Home
# 5. Error Handling (The Dead Letter / Recovery)
Auth.Timeout {
    # If the user abandons the process
    # Redirect to a "Resume Account" page
    Page.Recovery /redirect
}
# --- END OF GRAPH ---

This code appears to be written in a custom Domain Specific Language (DSL) designed to define state machines or workflow orchestrations. It describes a high-level logic map for a User Onboarding process, blending elements of a flowchart, a configuration file, and a programming language.

Here is a detailed breakdown and analysis of the flow described in the snippet:

1. High-Level Workflow Summary

The process follows a linear path that branches for validation, pauses for asynchronous API calls, splits into parallel tasks for profile completion, and finally converges on a dashboard.

The Journey: Welcome $\rightarrow$ Validation $\rightarrow$ Account Creation $\rightarrow$ Profile Setup (Parallel) $\rightarrow$ Dashboard.

2. Technical Logic Breakdown

A. Global State & Initialization

• State Variables: The system tracks $user_id, $onboarding_status, and $account_created. These act as flags to ensure the user cannot skip steps or to allow the system to resume from a specific point.

B. The Authentication Phase (Sequential/Branching)

• Entry: Starts at Welcome.Screen.
• Validation Logic: The Auth.ValidateEmail node acts as a Decision Gate.
  • Path A (Error): If the email exists, the user is looped back to the welcome screen with an error message.
  • Path B (Success): If available, the flow proceeds to account creation.

C. The Provisioning Phase (Async/External)

• External Integration: Auth.CreateAccount triggers an external API call (EXT:AuthService.CreateAccount).
• Async Handling: The system enters a WAIT state, meaning it doesn't block the entire system but waits for a specific event (Account_Created).
• Timeout Safety: There is a TTL (Time to Live) of 5 minutes. If the API doesn't respond, it triggers Auth.Timeout_Handler $\rightarrow$ Page.Recovery.
• State Update: Upon success, it captures the {uid} and updates the global $user_id.

D. The Profile Setup (Parallelism/Fork-Join)

This is the most complex part of the DSL. It uses a Fork-Join pattern:

1. Fork (F->): The flow splits into three concurrent paths:
   • Profile.Username
   • Profile.Photo
   • Profile.Interests
2. Independent Execution: These can be completed in any order. Each node performs a /save operation.
3. Join (J->): The system uses a synchronization barrier. It will not proceed to Profile.Complete until all three parallel paths have reported completion.

E. Finalization (The Happy Path)

• Once ProfileSetup.Complete is reached, the user is transitioned to Dashboard.Welcome.
• The global status is updated to $onboarding_status = "completed".
• The flow ends at Dashboard.Home.

3. Visual Representation (Logic Map)

graph TD
    Start((Start)) --> Welcome[Welcome Screen]
    Welcome --> Val{Validate Email}
    
    Val -- exists --> Welcome
    Val -- available --> CreateAcc[Create Account API]
    
    CreateAcc -- timeout 5m --> Recovery[Recovery Page]
    CreateAcc -- success --> Fork[Fork: Profile Setup]
    
    subgraph Parallel_Profile_Setup
        Fork --> User[Set Username]
        Fork --> Photo[Upload Photo]
        Fork --> Int[Select Interests]
        
        User --> Join
        Photo --> Join
        Int --> Join
    end
    
    Join[Join/Sync] --> DashWelcome[Dashboard Welcome]
    DashWelcome --> DashHome((Dashboard Home))

4. Key DSL Syntax Observations

If you are implementing or extending this language, here are the key operators identified:

• /start, /show, /upload, /save, /execute: Action Operators (define what the node does).
• ->: Transition (defines the next state).
• ? [ ... ]: Conditional Branching.
• F-> and J->: Concurrency Control (Fork and Join).
• EXT:: External Service Bridge.
• T [time]: Timeout Constraint.
• {var}: Data Injection/Extraction.