Skip to main content
Jira progress: loading…

ASK-ZARA-UI

Ask ZARA Interaction Model - UX & Navigation

This section describes how users interact with Ask ZARA inside the ZAYAZ documentation environment and how contextual information is passed from the UI to the Ask API.

Ask ZARA is designed to be accessible from multiple entry points across the documentation platform while preserving architectural context.

1 Navigation Entry Points​

Two primary navigation routes provide access to the assistant.

Search

Route: /search

Purpose:

  • semantic search across documentation
  • schema definitions
  • signal registries
  • table relationships
  • architecture specifications

Search is optimized for document discovery, not conversational reasoning.

Ask ZARA

Route: /ask

Purpose:

  • conversational exploration of the ZAYAZ platform
  • architecture reasoning
  • dependency analysis
  • implementation guidance

Ask ZARA combines semantic retrieval with architecture-aware reasoning to generate answers with citations.

2 Contextual Entry Points​

Ask ZARA can also be launched directly from documentation pages, allowing users to ask questions about the content they are currently viewing.

From a Specification Page

Specification pages may include an “Ask ZARA about this spec” action.

When invoked:

  1. The Ask interface opens.
  2. The current document slug is passed as a contextual hint.
  3. Suggested prompts are displayed.

Example prompts:

  • “Explain this engine to me.”
  • “Summarize the risk model in plain English.”
  • “Which engines depend on this signal?”

Example API hint:

{
  "focusSlug": "/micro-engines/pef-me"
}

This helps the retrieval layer prioritize results related to the active specification.

3. Context Passing Model​

The Ask UI can pass contextual signals to the backend to improve retrieval quality.

Examples include:

Context ParameterPurpose
focusSlugPrioritize results related to the current document
architectureClusterLimit retrieval to a subsystem
engineIdFocus queries on a specific engine

These hints are used only during retrieval and do not constrain the model’s reasoning.

4 Example UX Flow​

Typical interaction:

  1. User reads a micro-engine specification.
  2. User clicks Ask ZARA about this spec.
  3. Ask ZARA opens with contextual hints.
  4. User asks:

“Which tables feed into this engine?”

The API receives:

{
  "question": "...",
  "focusSlug": "/micro-engines/pef-me"
}

The retrieval pipeline then prioritizes architecture nodes related to the PEF-ME engine.

5 Design Principles​

The Ask ZARA UX follows several principles:

Context awareness

Users should be able to ask questions without repeating the current topic.

Low-friction entry

Ask ZARA must be reachable within one click from any architecture page.

Traceable answers

All answers include citations to the relevant documentation sections.

APPENDIX A - Questions Ask ZARA Can Answer​

Ask ZARA is designed to help developers, architects, and auditors explore the ZAYAZ platform by reasoning across documentation, registries, schemas, and system metadata.

The assistant combines semantic search with architecture-aware retrieval to answer questions that normally require reading multiple specifications.

Below are examples of questions Ask ZARA can help answer.

A.1. Architecture Understanding​

Ask ZARA can explain how major parts of the system work.

Examples:

  • “Explain the purpose of the PEF-ME engine.”
  • “How does the SEM module extrapolate missing ESG data?”
  • “What is the role of the Compliance Surveillance Engine (COSE)?”
  • “Describe the architecture of the ZAYAZ Computation Hub.”

These questions typically combine information from:

  • engine specifications
  • system architecture documentation
  • module descriptions

A.2. Dependency & Impact Analysis​

Ask ZARA can trace relationships between signals, engines, tables, and modules.

Examples:

  • “Which engines depend on this signal?”
  • “What modules reference this table?”
  • “What breaks if we modify this API contract?”
  • “Which downstream systems use this schema field?”

These answers rely on indexed metadata such as:

  • used_by_engines
  • table_relationships
  • classification
  • link_group

This allows Ask ZARA to reconstruct architecture paths like:

engine → signal → table → schema → downstream engine

A.3. Implementation Guidance​

Ask ZARA can help developers understand how to implement or extend parts of the platform.

Examples:

  • “Show the API contract for the transition ROI calculator.”
  • “What parameters does the GHG aggregation engine require?”
  • “Where is the schema for signal_registry defined?”
  • “Which files implement this engine?”

These answers often include links to:

  • code snippets
  • API contracts
  • schema definitions
  • engine specifications

A.4. Data & Schema Exploration​

Ask ZARA can help explore data structures and registries used by the platform.

Examples:

  • “What fields exist in the signal registry?”
  • “Which tables reference dim_suppliers?”
  • “Explain the relationship between these tables.”
  • “Which schemas are used by the GHG aggregation engine?”

A.5. Specification Navigation​

Ask ZARA can guide readers through complex documentation.

Examples:

  • “Where is the specification for the Carbon Passport system?”
  • “Show the documentation describing API contracts.”
  • “Which docs explain the ZADIF dispatcher?”
  • “Summarize the purpose of the Global Disclosure Ontology.”

A.6. Compliance & Risk Interpretation​

Because the ZAYAZ platform integrates regulatory frameworks, Ask ZARA can also explain compliance logic.

Examples:

  • “How does the Risk Intelligence Framework validate ESG data?”
  • “Which engines are responsible for regulatory monitoring?”
  • “Explain how ZAYAZ supports CSRD reporting.”

A.7. Tip​

Ask ZARA works best when questions include specific architecture elements, such as:

  • engine names
  • signals
  • tables
  • modules
  • specifications

For example:

Good question:

“Which engines depend on the ghg_scope3_signal?”

Less effective question:

“Tell me about the system.”

APPENDIX B - When Ask ZARA May Be Wrong.​

Ask ZARA is designed to assist developers and architects in exploring the ZAYAZ platform. While it combines semantic retrieval with architecture-aware reasoning, it should be treated as a documentation assistant, not a source of authoritative system state.

Users should verify important conclusions against the underlying specifications and source files.

B.1. Incomplete Retrieval​

Ask ZARA answers questions based on the indexed corpus stored in the search index.

If relevant information is:

  • not indexed,
  • newly added but not yet re-indexed, or
  • located in files outside the documentation corpus,

the answer may omit important details.

Typical symptoms:

  • a dependency appears to be missing
  • only part of a subsystem is described
  • a referenced component is not mentioned

When this happens, consult the underlying documentation or repository files directly.

Note: Ask ZARA is schedules to re-indexed once every 24 hours, which may exclude new documentation from queries.

B.2. Ambiguous Architecture Terms​

Some architecture terms appear in multiple contexts within the platform.

Examples may include:

  • signals with similar names
  • tables reused across modules
  • engines with related responsibilities

If a question does not include enough context, Ask ZARA may retrieve information from the wrong subsystem.

Example:

“Explain the aggregation engine”

The system may return results for several different engines that perform aggregation tasks.


More specific questions improve accuracy:

“Explain the GHG aggregation calculator micro-engine.”

B.3. Partial Dependency Analysis​

Ask ZARA can trace many architecture relationships using indexed metadata such as:

  • used_by_engines
  • table_relationships
  • classification
  • link_group

However, not all dependencies are guaranteed to be captured in these registries.

Dependencies defined only in:

  • application code
  • runtime configuration
  • external services

may not be visible to the retrieval system.

For critical impact analysis, always confirm results with the system specifications.

B.4. Reasoning Errors​

Ask ZARA uses large language models to interpret retrieved information.

Although the model is guided by system prompts and citations, it may occasionally:

  • infer relationships that are not explicitly documented
  • misinterpret technical descriptions
  • over-generalize from similar components

For this reason, answers should be viewed as interpretations of documentation, not guaranteed architectural truth.

B.5. Outdated Information​

The ZAYAZ platform evolves continuously.

If the documentation index is not rebuilt after recent changes, Ask ZARA may return answers based on:

  • outdated specifications
  • previous versions of schemas
  • deprecated engine behavior

Regenerating the search index ensures the assistant reflects the most recent architecture.

Ask ZARA works best when used as a navigation and exploration tool.

Recommended uses include:

  • locating relevant documentation
  • understanding system architecture
  • discovering related engines, tables, or signals
  • summarizing complex specifications

For tasks such as:

  • production configuration decisions
  • compliance verification
  • schema migrations
  • system modifications

the underlying specifications and source files should always be consulted directly.

Appendix B - Summary​

Ask ZARA is designed to accelerate exploration of the ZAYAZ platform by combining semantic search with architecture-aware reasoning.

It should be treated as:

an intelligent guide to the documentation, not a replacement for the specifications themselves.

APPENDIX C - How Ask ZARA Generates Answers​

When a user submits a question, Ask ZARA follows a multi-step pipeline that combines semantic search, architecture metadata, and large language model reasoning.

The goal is to provide answers that are grounded in the ZAYAZ documentation corpus while preserving traceability through citations.

C.1. Question Processing​

The user’s question is first normalized and prepared for search.

This includes:

  • tokenization of important terms
  • lowercasing and normalization
  • optional contextual hints from the UI (for example focusSlug)

Example request:

{
  "question": "Which engines depend on this signal?",
  "focusSlug": "/micro-engines/ghg-aggregation-calculator"
}

These hints help the retrieval layer prioritize relevant parts of the architecture.

C.2. Query Embedding​

The processed question is converted into a vector embedding using an OpenAI embedding model.

Example:

text-embedding-3-small

This vector represents the semantic meaning of the question.

The query embedding is compared against vectors stored in the Ask ZARA index:

index.jsonl

This index contains embedded fragments from:

  • documentation pages
  • engine specifications
  • code snippets
  • signal registries
  • schema definitions
  • table relationship registries

The system retrieves the top matching fragments.

C.4. Architecture-Aware Expansion​

Ask ZARA then expands the retrieved results using indexed metadata.

This step follows relationships such as:

  • engines referencing signals
  • tables linked through relationships
  • documentation linked to code examples
  • schema fields belonging to tables

This expansion allows Ask ZARA to reconstruct architecture paths such as:

engine → signal → table → schema → downstream engine

C.5. Metadata-Aware Reranking​

Retrieved fragments are reranked using a scoring model that combines:

  • semantic similarity
  • token overlap with titles and headings
  • matches in metadata fields

Examples of metadata used for scoring include:

  • slug
  • title
  • heading
  • table_name
  • used_by_engines
  • referenced_by
  • snippet_files

Dependency-related questions receive additional weighting for these fields.

C.6. Context Construction​

The highest-ranked fragments are assembled into a context block that is sent to the reasoning model.

This context includes:

  • extracted documentation text
  • relevant metadata
  • links to source documents

The context is limited to a token budget to ensure efficient processing.

C.7. Model Reasoning​

The context and the original question are then sent to the reasoning model.

Depending on configuration, this may use:

ModeModel
Fastgpt-4.1-mini
Deepgpt-4.1
Architectnext-generation reasoning model

The model synthesizes the retrieved information and produces a structured answer.

C.8. Citation Generation​

Ask ZARA returns:

  • the generated answer
  • a list of source fragments used to construct the response

Each citation contains metadata such as:

  • document slug
  • section heading
  • relevance score
  • source file reference

This ensures that answers remain traceable to the underlying documentation.

Appendix C - Summary​

In simplified form, Ask ZARA operates using the following pipeline:

User Question
      ↓
Embedding Generation
      ↓
Vector Search
      ↓
Architecture Expansion
      ↓
Metadata Reranking
      ↓
Context Construction
      ↓
LLM Reasoning
      ↓
Answer + Citations

This approach allows Ask ZARA to combine semantic retrieval with architecture-aware reasoning, enabling it to answer complex questions about the ZAYAZ platform.



GitHub RepoRequest for Change (RFC)