Survey Business Flow & Routing India: From Strategy to Runtime in Hercules

questionnaire_sections, branch_blocks, dynamic_lists, rejoin — the strategy you can audit. business_flow is the document you show an insights lead to prove the study design answers the brief. questionnaire_sections orders thematic sections (e.g., Salience → Familiarity → Perception → Emotional → Loyalty for brand tracking; Salience → Usage → Need → Concept → Price for innovation) with intent, objective mapping, business rules and analysis_tags. branch_blocks declare branching declaratively — source_flow_key, member_flow_keys and rejoin_key in flow_key terms — so "if aware of at least one biscuit brand, ask usage block, then rejoin to category total" is explicit, not buried in question JSON. dynamic_lists declare piped or carry-forward lists (SD-025 Carry Forward, SD-023 Piping, SD-024 Loop & Merge) whose membership is resolved at runtime from prior answers (e.g., brands selected in awareness carried into usage).

questionnaire_sections, branch_blocks, dynamic_lists, rejoin — the strategy you can audit. rejoin points mark where divergent paths reunite, preventing dangling branches that never merge. This artefact lives in survey_chats.business_flow and chat_turns snapshots, speaks in flow_keys not qIds so reordering questions does not invalidate it, and is the source for analysis-tag coverage later. Poseidon later reads it directly from PostgreSQL alongside survey_version to reconstruct which respondents saw which path — a lineage that begins here, not in a spreadsheet note. See the taxonomy that feeds these sections at strategic research framework India and the brief that gates them at survey research brief goals India. On Hercules Works in Hyderabad, branch_block_expander compiles these declarations into concrete per-question edges while keeping the audit trail intact.

Why flow_keys stay stable while qIds stay unique. Every question carries two identities: id = preview_question_1 for frontend progress/layout, and qId = globally unique UUID for routing stability via _ensure_question_identity_fields(). The flow_key (e.g., BRAND_AWARENESS_AIDED) is a third, abstract business key on the question that business_flow and routing_logic use. _build_flow_key_map(flow_keys → questions) ensures first occurrence wins and duplicates are reported as validation errors, so compiling BRAND_AWARENESS_AIDED → preview_question_7's qId never collides. This triplet is why Hercules can re-order, insert break cards for 21+/31+/46+ question surveys, or shuffle eligible MCQs (shuffle:true only on multiple_choice/dropdown/image_multiple_choice, never on number_rating/ranking/vertical_ranking/yes_no) without breaking strategy. Targets like audience_payload (NCCS A1–C1, Tier 1/2/3, age 18–55) are never re-asked as demographic questions — the LLM is forbidden — so business_flow focuses on category qualification rather than quota fields. When Poseidon later reconstructs paths, it traverses both business_flow declarations and the compiled qId edges, explaining why "biscuit buyers" denominators reflect actual routing, not full-sample counts.

rules, display_rules, dynamic_filters — still in flow_keys, not qIds. routing_logic is the abstract machine plan that route_builder_agent emits alongside business_flow, also in stable flow_keys. rules declare skip/branch intent (SD-021 Skip Logic/Branching via next), display_rules declare conditional visibility without routing the page structure (SD-022 Display Logic via showIf patterns), and dynamic_filters declare cascading choice carry-forward (filterFrom/filterOut) and piped list bindings. Because they are abstract, a change like moving BRAND_RECALL_UNAIDED from position 2 to 5 does not require rewriting a rule string — the route_compiler resolves the current qId at compile time. This design is documented in survey_and_analytics/build_process.md §5 as the two-layer routing architecture and is the reason Hercules can validate logic without executing it. The abstract layer references 24 scenarios: normal flow, skip/next, complete, multi-branch redirect, filter carry-forward, parallel show, First-Match multi-select, last-always-complete, showIf single/multi AND/OR, multi-select answer check, complex showIf chains, showIfElse terminate/complete, requiredOptions validation, 3-level cascading filters, exclusive "None"→terminate, minCount+routing, and mixed skip/terminate on same question — all as flow_key declarations before compilation.

From abstract display to concrete visibility — showIf family. Display logic deserves clarity because it is distinct from routing. next moves the respondent to a different question; showIf/showIfElse/showIfLogic keep the page structure but toggle visibility of the next item based on prior answers; filterFrom/filterOut keep structure but restrict the option list. In the abstract plan these are expressed as flow_key conditions (e.g., "show NPS_SCORE only if MAIN_BRAND in [0]"), and in the compiled runtime they become top-level showIf: {"qId_MAIN_BRAND": 0}. showIfElse then says what happens when that condition fails: skip (hide and continue), terminate (fail qualification, soft-exit per SD-031), or complete (success end).

From abstract display to concrete visibility — showIf family. showIfLogic is AND by default or OR across multiple sources, with OR-within-question allowed via array values (showIf: {Q:[0,2]} means option 0 OR 2). This abstract→concrete split prevents the common error of writing imperative "if" strings that SuperJ cannot parse — instead the compiler emits declarative maps that survive reordering and are validated deterministically. For compiled shapes, see the next section and live examples at skip logic survey tool and advanced survey analytics. Built by Jupiter Meta Labs in Hyderabad, this layer is why the same survey works in English in Mumbai and Hindi in Lucknow without logic drift. Pricing is Free ₹0, Starter ₹1,119 (₹895 annual), Pro ₹30,000/quarter (₹24,000 annual) with 20% annual off and 100 free first-month responses. Built by Jupiter Meta Labs in Hyderabad, this layer is why the same survey works in English in Mumbai and Hindi in Lucknow without logic drift on the SuperJ app.

The 8 keys the compiler emits — and why they must be top-level. compile_routing_logic() translates abstract flow_keys to concrete qIds and writes the runtime on each question object in questions_json as top-level fields, never nested under a routing key or object. The 8 keys are: next — option-index → qId branch map (e.g., "next":{"0":"qId_aware","1":"qId_unaware"}); terminate — boolean true or option-index array ending as disqualified (opaque to analytics until next stage); complete — boolean/array/"ALWAYS" ending as successful completion (last question is always complete); showIf — source qId → required option index/array (e.g., "showIf":{"qId_brand_owner":0}) meaning show only if that source's answer matches; showIfElse — action when showIf fails: skip, terminate or complete; showIfLogic — AND (default) or OR across multiple showIf sources; requiredOptions — multi-select validation (mustHaveAllOf, minCount, mustNotHave) that gates where next/terminate can fire; filterFrom/filterOut — cascading carry-forward source qId that restricts the current option list to only selected/unselected upstream options (e.g., "filterFrom":"qId_platforms"); and shuffle on eligible MCQs.

24 scenarios, First-Match, and parallel show — the execution details that decide truth. The runtime supports 24 scenarios documented in framework_designs.md and build_process.md: normal flow (no logic), skip/next, complete, multi-branch redirect (next:{A:Q1,B:Q2}), filterFrom/filterOut carry-forward, parallel show (next:{answer:[Q1,Q2]}), multi-select First-Match, last-always-complete, showIf single, terminate, requiredOptions, 3-level cascading, exclusive "None"→terminate, minCount+routing, all required+routing, parallel+terminate, multi-AND, OR array, multi-select check, complex AND+OR, nested 4-level chains, multi-select+complex, showIfElse terminate/complete, mixed skip/terminate. First-Match deserves emphasis: when a multi-select question has two next rules (e.g., Option A → Q5, Option B → Q6) and the respondent picks both, the engine picks the first selected option in ascending index order — PRIORITY maps were explicitly removed — so deterministic behaviour survives any UI reordering; "None of these" is handled via terminate on that option, not a branch. Parallel questions show multiple items together, and filter chains can cascade across 3+ levels (e.g., awareness → usage → loyalty → filterFrom chain). Shuffle via shuffle:true randomises options per respondent on eligible types to control primacy bias (SD-011) but never on ordered scales, preserving scale integrity later scored by compute_survey_quality_scorecard and SD-015→018 analyses. See the quality gates at survey quality rubric linter India.

Deterministic validation — the fail-safe ladder. Before any question is persisted, validate_compiled_routes() blocks broken logic: duplicate/missing qId, unknown question references, invalid option selectors, branch targets missing recommended showIf protection, loop/terminal hazards, filterFrom/filterOut source existence and exact option parity, routing rule coverage against routing_logic, and analysis-tag coverage against business_flow. On mismatch, the ladder is repair → fallback → strip: first strip_filter_mismatch_fields() fixes filterFrom/filterOut mismatches and re-validates; next the legacy routing_agent attempts regeneration; finally strip_invalid_routing() strips ALL routing and saves a linear survey with no skip logic — because a linear survey with correct denominators is better than a branching survey that traps respondents on the SuperJ app where people answer for rewards. This deterministic ladder, not LLM self-checking, is what keeps SuperJ completion at 60-90%+ and Poseidon's downstream null-correlation routing detection honest — if the declared routing says BRAND_AWARENESS_AIDED carries forward into usage, Poseidon expects to see that null-correlation and reports "among aware" with the right base, not the full n.

How flow_key becomes qId — _build_flow_key_map and _ensure_question_identity_fields in practice. The compiler's job is a precise join: for each question in questions_json, read flow_key (UPPER_SNAKE_CASE) and qId (UUID), build map flow_key→qId, then walk routing_logic's abstract declarations and replace flow_key references with the mapped qId while emitting the 8 top-level runtime fields on the target questions. _ensure_question_identity_fields() guarantees every question has both id (preview_question_1…) and qId before mapping; _build_flow_key_map enforces first occurrence wins and reports duplicates as validation errors. branch_block_expander expands declared blocks after this map is built so branch members inherit the correct showIf protections from source conditions (e.g., members of a usage block all showIf aware==true). The result lands in survey_chats.questions_json (survey_version in analytics_process.md parlance) alongside survey_chats.business_flow, routing_logic and formulated_goals — the same PostgreSQL rows Poseidon will read via POST /api/v1/ingest/. Because this is a clean foreign-key style translation, adding a break card at position 7 or reordering preview_question_3 to 5 does not orphan a branch — the qId bridge survives, and SuperJ's MongoDB payload preserves the same top-level fields so execution and analytics share one truth.

Poseidon's 5-context reconstruction — reading the same keys, correctly. When the survey flips to completed, Poseidon POST /api/v1/ingest/ with {chat_id, super_j_survey_id} and X-Secret-Key, then reads five contexts from Postgres: Research Brief (survey_chats.research_brief), Survey Version / Questionnaire (survey_chats.survey_version — full questions_json with those same top-level routing fields), Response Data (data/{chat_id}.parquet — DuickDB columnar), Audience Payload (survey_chats.audience_payload — NCCS/tier/age), and Survey Intelligence (computed routing pairs via null-correlation + goal→question mapping). Reconstruction is explicit: it hydrates the Survey Knowledge Graph with Question→Column maps_to, Column→Formula formula, Question→Question routed_from (using the compiled next/showIf edges), Formula→Demographic slice_by, walks Parquet-acquired routing edges to determine which respondents saw which conditional question, and applies denominator correction — i.e., WHERE clauses derived from the graph so "62% among theatre-goers (n=40)" is not "among all (n=200)." The graph uses confidence tags EXTRACTED/INFERRED/AMBIGUOUS so an analyst knows whether a relationship was declared or fuzzy-matched. This is why two surveys with identical question lists but different showIfElse policies produce different, defensible narratives — the routing is data, not commentary.

5 context paragraphs? The five paragraphs the report earns. In the 18-node report graph, narrative quality depends on those five contexts being present in full: brief gives decisions, version gives scales/options, Parquet gives counts/means, audience gives quotas/bases, intelligence gives routing denominators and goal coverage. The drafting node (report_drafting) chunk-writes each section with those five inputs plus chart tokens, while insight_generation and narrative_synthesis produce per-goal narratives and cross-section synthesis. Section Audit (deterministic claim verification + LLM self-critique) and Safety Check (PII/numeric mismatch/coverage) both re-inject the brief and version to verify that percentages sum to ~100, NPS is in [-100,100], rating means are in declared bounds, and no null leaks into primary columns. When routing-aware denominators shift a base from 200 to 40, the verifier re-computes via fresh DuckDB SQL and the self-critique checks whether the narrative still holds — if not, it triggers NEEDS_REVISION for up to 2 cycles. This 5-context discipline is why a report section on "premium seekers who tolerate +₹1,200 for AMOLED" can cite its MaxDiff source, its price-study wave, and its routing path in the same paragraph.

Write routing for thumbs, not desktops — SuperJ app delivery is the target. Because fielding is on the SuperJ app (mobile and web, 60-90%+ completion, rewards for answers) among 20M+ ZK-verified Indians, routing best practice mirrors device reality: keep skip chains shallow (prefer 2-level branching over 4-level nested showIf chains unless needed), use display logic (showIf) for follow-ups rather than next when visibility is the question not sequence, reserve requiredOptions for genuine multi-select validation (mustHaveAllOf/minCount/mustNotHave) rather than nannying, and use filterFrom for brand repertoire carry-forward so respondents do not re-evaluate brands they never claimed to know — anSD-024 Loop & Merge and SD-025 Carry Forward pattern. Media stimuli (concept card/pack shot SD-036, shelf/planogram SD-037, video SD-038, forced exposure timer SD-039) that are routed to should have a comprehension or recall check triggered automatically by Poseidon downstream, not by a hand-written conditional you might forget. Randomisation discipline follows SD-008→011 (Latin Square for 3+ monadic stimuli, Block/Random rotation, Answer Option Randomization) and is emitted via shuffle:true only on eligible categorical lists, so scale designs (NPS, Likert, ranking via SD-015→018) keep their order and scoring integrity.

Quotas, screeners and attention — platform first, questionnaire second. Hard/Interlocking/Soft/Dynamic quotas (SD-026→029) and screener/panel logic (SD-030→031) are enforced by the audience system before routing, so routing does not duplicate city/NCCS/age checks — it handles category qualification, occasion filters, and path triggers. Attention checks (SD-032) are platform-armed via the quality rubric and run via the SuperJ app checks; Poseidon verification plus Survey Intelligence's null-correlation ensures that if attention-flagged respondents are excluded, downstream denominators update accordingly. Consent, language (8+ languages: Hindi, Tamil, Telugu, Bengali, Marathi, Gujarati, Kannada, Malayalam, Punjabi) and DPDP-ready storage in Google Cloud Mumbai are handled outside routing but affect it: a disqualified Lang-specific path still reports its base correctly rather than vanishing. For data-quality depth, see survey quality rubric linter India and best practices for improving data quality in online surveys — they share SD-032→035,044 lineage with this page.

From flow to live — the operation in one sentence. Author in business_flow and routing_logic using flow_keys in Hyderabad's Hercules, compile with route_compiler to qIds emitting top-level next/showIf/showIfElse/showIfLogic/filterFrom/filterOut/requiredOptions/shuffle, validate deterministically with repair→fallback→strip, register to SuperJ via SUPERJ_CREATE_SURVEY_AI_URL preserving those top-level fields, mark completed, POST {chat_id, super_j_survey_id} to POSEIDON_INGEST_URL/api/v1/ingest/ with X-Secret-Key, land Parquet for DuckDB (10–20× over Pandas) and a Survey Knowledge Graph with EXTRACTED/INFERRED/AMBIGUOUS edges, answer chats in 1.8s median via 5-phase pipeline with semantic cache 78% (<200ms on hit) and three-layer verification at 99.1%, and produce a 20–50 page Markdown/HTML/PDF report via the 18-node graph streamed via SSE with persistence. Pricing stays Free ₹0 / Starter ₹1,119 (₹895 annual) / Pro ₹30,000/quarter (₹24,000 annual) with 20% annual off and 100 free first-month responses, trusted by Unilever and peers. Routing is not metadata. It is the survey's nervous system — and on Hercules, the SuperJ app and Poseidon share it without loss.