Jira progress: loading…

The Code Folder

ZAYAZ Documentation Examples & Associated Folder Structure

A curated library of example documents, patterns, and templates used across the ZAYAZ documentation ecosystem.

Purpose

These folders provide canonical examples of how to structure, format, and implement documentation within the ZAYAZ knowledge system.

It acts as a shared reference for engineers, product teams, module owners, and technical writers working on:

• Micro-engine specifications
• Module specifications
• Compliance schemas
• Data tables & signals
• Integration guides
• Developer onboarding materials

The collection ensures uniformity, quality, and reusability across all documentation artifacts.

⸻

Folder Structure — Associated Files

The associated-files directory mirrors the structure of the ZAYAZ Manual (the MDX files in /content). Its purpose is to ensure that every chapter, micro-engine, module, calculation, or guide has a clean home for its supporting materials:

• Example code
• JSON schemas
• Excel input/output models
• Reference datasets
• Simulation scripts
• Images & diagrams
• Notebook-style explorations
• Any engine-specific artifacts

This allows developers, reviewers, and AI systems (e.g., Ask ZARA) to reliably locate all files belonging to a specific manual chapter.

⸻

How the Mapping Works

A manual page such as:

/workspaces/zayaz-docs/content/computation-hub-calcs/micro-engines/carbon-price-engine.mdx

…will have its supporting files stored in the parallel path:

/workspaces/zayaz-docs/code/associated-files/computation-hub-calcs/micro-engines/carbon-price-engine/

This 1:1 structural reflection ensures clarity and enables future automation:

• Documentation linting & validation
• Indexer ingestion of examples
• Automatic example linking in MDX
• Retrieval for Ask ZARA’s tool features

Note: Excel files are stored in a flat shared directory and linked directly from MDX pages. This avoids deep directory nesting for binary assets while keeping reference integrity.

⸻

Example Structure Excerpt

Below is an illustrative subset of the folder structure (real content varies depending on development progress):

docs-examples/
│
├── ...
│
├── computation-hub-calcs/
│   ├── monte-carlo-sims/
│   ├── bayesian-model/
│   ├── emission-intel/
│   ├── netzero-modeling/
│   └── zara-autonomous-asst/
│       ├── zara-completion-engine/
│       ├── zara-memory-flow/
│       └── zara-reasoning-engine/
│ 
├── reports-hub-dashboards/
│   ├── pratibha-esg-wisdom/
│   ├── source-metric-area/
│   ├── telemetry-dash/
│   └── operational-duty-frame/
│       ├── duty-shift-log-table/
│       ├── daily-checklist/
│       ├── executive-dashboard/
│       └── operational-kpis/
│
└── ...

⸻

Notes on Variability

• Some folders may be empty placeholders — this is intentional and signals upcoming content or structures reserved for future modules.
• Others may contain substantial datasets, modeling scripts, or multi-file engines.
• This structure is dynamic and evolves with the ZAYAZ Platform architecture.

⸻

Why This Matters

This mirrored structure enables:

• Predictable file discovery
• Lightweight onboarding for new engineers
• Rapid retrieval for Ask ZARA’s RAG tools
• Cleaner PRs with isolated example regions
• Automatable link-generation between manual ↔ examples

Over time, this folder becomes one of the backbone components of the ZAYAZ documentation ecosystem.

⸻

Folder Structure - Docs Examples

Below is the intended high-level structure included in this folder (your actual structure may differ slightly based on ongoing evolution):

docs-examples/
│
├── examples/
│   ├── micro-engines/
│   ├── modules/
│   ├── data-tables/
│   ├── signals/
│   ├── integration-guides/
│   └── ux-patterns/
│
├── templates/
│   ├── SPEC_TEMPLATE.mdx
│   ├── ENGINE_TEMPLATE.mdx
│   ├── MODULE_TEMPLATE.mdx
│   ├── CHANGELOG_TEMPLATE.mdx
│   └── TABLE_SCHEMA_TEMPLATE.json
│
└── snippets/
    ├── api/
    ├── mdx/
    ├── schema/
    └── diagrams/
 
 

Each directory contains realistic but decoupled samples you can reuse when creating new ZAYAZ documentation.

⸻

How to Use

1. When creating a new spec

Choose the closest template from /zayaz-tech-spec-templates/:

• Micro-engine spec → MICE_TEMPLATE.mdx
• Module spec → MODULE_TEMPLATE.mdx
• System-level or computation spec → SPEC_TEMPLATE.mdx

Copy it into the correct location under:

/workspaces/zayaz-docs/content/computation-hub/(...)
/workspaces/zayaz-docs/content/system-info/(...)

Then adapt it to your actual content.

⸻

2. When building new tables, schemas, signals

Use:

• TABLE_SCHEMA_TEMPLATE.json for data schemas
• /examples/data-tables/ for formatting and structuring inspiration
• /examples/signals/ for signal & telemetry patterns

This ensures consistency across the COSE / RIF / FIRM / ZHIF modules.

⸻

3. When writing micro-engine specifications

The examples under /examples/micro-engines/ showcase:

• Standardized metadata header
• Required sections (Scope, Purpose, Inputs, Outputs, API, Notes)
• <NodeMeta> integration
• MDX styling and callouts
• Diagrams and FER/LER references

All new specs must follow these conventions to remain indexable and searchable by SEEL and the Search API.

⸻

4. For internal developer education

The /integration-guides/ folder contains short, clear examples demonstrating:

• How to call engines
• How to use templates
• How to reference schemas
• Best practice MDX patterns

These are meant to speed onboarding and reduce friction.

⸻

Contribution Guidelines

To add new examples:

1. Keep items small, focused, and readable.
2. Prefer general patterns over project-specific implementations.
3. Include comments (<!-- comment -->) explaining why the pattern exists.
4. Avoid embedding secrets, proprietary assets, or production data.
5. Use MDX whenever interactive components or callouts are helpful.

After adding content, run:

npm run lint:docs
npm run build

to ensure Docusaurus validates the formatting and Search Indexing does not break.

⸻

Search & ZARA Compatibility

All examples are automatically indexed by the ZAYAZ Search Indexer and therefore accessible via:

• Search (semantic retrieval)
• Ask ZARA (retrieval-augmented answers with citations)

This makes the examples part of the internal knowledge graph.

⸻

Future Enhancements

Planned expansions for /docs-examples/:

• Additional engine spec exemplars (PEF-ME, SEM-ME style references)
• JSON schema showcase library
• Diagramming guide (Mermaid, GraphViz, and JSX-based diagrams)
• Best practices for changelogs & versioning
• “Anti-patterns” folder to show what not to do

⸻

NOTE

When a new MDX file is created in the Content folder, the associated folder is created automatically by running the following script. It does not overwrite excisting files, but it will create a new forlder for every new MDX file.

cd /workspaces/zayaz-docs
npm run zayaz-doc-linker