Guidelines For Docusaurus Documentation Structure

Section 1: For Clients — “Plain English” & Visual

• What ZAYAZ does
• How reports are generated
• What validation means
• Why E-C-O™ Numbers matter
• What ZARA & ZAAM “help with”
• How automation removes friction
• How verification works (conceptual)

👉 Simple diagrams. 👉 Lots of examples. 👉 No algorithm detail. URL: manual.zayaz.io

⸻

Section 2: For Verifiers & Officials — “Assurance View”

• End-to-end audit trail concept
• Validation and trust scoring at a high level
• Explanation of how the platform ensures accuracy
• Evidence workflows
• XBRL/iXBRL mapping
• Policy & procedure management
• AI transparency (“every AI-generated suggestion is traceable, tagged, and reviewable”)

👉 Enough detail to prove rigor 👉 Not enough detail to replicate ZAYAZ URL: docs.zayaz.io

⸻

Section 3: For White Label Partners

• End-to-end audit trail concept
• Validation and trust scoring at a high level
• Explanation of how the platform ensures accuracy
• Evidence workflows
• XBRL/iXBRL mapping
• Policy & procedure management
• AI transparency (“every AI-generated suggestion is traceable, tagged, and reviewable”)

👉 Enough detail to prove rigor 👉 Not enough detail to replicate ZAYAZ URL: wl.zayaz.io

⸻

Section 4: Hidden Internal Docs

Tagged internal, developer etc. Access control through Cloudflare.

• Full engine registry
• USO, SSSR, ZAR, MICE, DAL, etc.
• Exact calculation rules
• Prompt templates & agent profiles
• Architecture diagrams
• Orchestration flows
• Engine IDs and schemas URL: specs.zayaz.io

Stored separately (GitHub, internal Notion, etc.).

Recommended Architecture for Dual Docusaurus Documentation

Two Fully Separate Docusaurus Deployments

Not one deployment with hidden pages — two deployments, cleanly separated.

A. Public / External Docusaurus

Purpose: ✔ For clients ✔ For verifiers ✔ For officials ✔ For partners ✔ For the general public

Content level:

• High-level structure
• “Plain English” explanations
• Conceptual diagrams
• Compliance workflows
• Assurance overview
• XBRL/iXBRL instructions
• FAQs
• Tutorials
• Examples
• No internal IDs, logic, or schemas

This layer builds trust, confidence, and ease of use.

⸻

B. Internal / Zero-Trust Docusaurus

URL example: internal-docs.zayaz.io

Protected by:

• Cloudflare Zero Trust
• Device posture policies
• MFA
• User groups
• IP + country restrictions
• Token-based access
• Logged access attempts

Content level: Full v0.3+ documentation, including: ✔ SSSR schema ✔ USO ✔ MICE Micro-Engines ✔ MEID registry ✔ ZADIF routing architecture ✔ ZAAM agent profiles ✔ ZARA orchestration internals ✔ AI governance internal specs ✔ Audit logs (ALTD) architecture ✔ DAL / EAC / FITI frameworks ✔ Database schemas ✔ API contracts ✔ Event buses ✔ Telemetry & trust scoring formulas ✔ All rules, fallback logic, thresholds ✔ Architecture diagrams, sequence flows ✔ SRE runbooks ✔ Deployment plans & IaC diagrams ✔ Internal ontology libraries ✔ AI lifecycle governance docs ✔ Key engine code references ✔ Anything IP-sensitive

This is the “engine room.” Only your team sees it.

⸻

Cloudflare Zero Trust Architecture (Recommended)

Using Cloudflare’s Zero Trust platform, your internal Docusaurus should only be accessible if ALL conditions are true:

Access Requirements

• Logged-in via Cloudflare Access
• Verified email domain (e.g. @viroway.com)
• Device posture OK (e.g. Antivirus, OS version, no jailbreak)
• Country allowed
• IP or ASN allowed (optional but recommended)
• MFA required
• Session expires often
• All access logged to SIEM

For ultra-secure modules:

Build nested protection:

• /architecture/
• /schemas/
• /ai-governance/
• /micro-engines/
• /routing-logic/

Require:

• Hardware key (YubiKey / WebAuthn)
• Cloudflare Access “High-Sensitivity Group”

⸻

Strict Content Separation Policy

Public Documentation MUST NOT contain:

❌ Engine IDs (MEID_CALC02_v1) ❌ Internal flow diagrams ❌ ZADIF routing logic ❌ SSSR schemas ❌ USO ontology tables ❌ Prompt templates or agent profiles ❌ Internal validation thresholds ❌ Code samples for engine logic ❌ SQL or JSON schemas ❌ API internals ❌ Database or event bus architecture ❌ Telemetry scoring rules ❌ Micro-engine composition

These elements are ZAYAZ’s intellectual property and competitive advantage.

Public Documentation may include:

✔ Plain English explanations ✔ Non-technical diagrams ✔ Validation descriptions (high level) ✔ AI governance principle summaries ✔ Example workflows ✔ How-to guides ✔ Field definitions (user-facing only) ✔ Compliance mapping ✔ Reporting steps ✔ Conceptual architecture

ZAYAZ Documentation Strategy: “One Repo, Many Realities”

Audience Tagging Model

ZAYAZ tagging taxonomy:

Audience Tags

Tag	Meaning	Typical Access
client	Companies using ZAYAZ	Broad access to external docs
supplier	Supplier-tier users	Narrow, simplified content
validator	Verifiers, auditors, certification bodies	Extended technical & assurance content
authority	Government entities, EU bodies, regulators	Assurance, compliance notes, governance
partner	White-label partners	API, workflows, integration notes
internal	Viroway staff only	Deep architecture, schemas, engines
restricted	High-security internal (AI governance, routing logic)	Only internal + security leads

Additional tags

Tag	Purpose
sensitive	For pages that may be shown to validators/officials but not clients
conceptual	Safe high-level explanations
technical	Deeper descriptions without internal mechanics
developers	For external development project manager.
api	Integration content for partners
ai-governance	AI auditability, trust scoring, risk register content
schema	Structure definitions (internal only)

Page-Level Audience Control

Each page will include specific frontmatter, for example:

---
id: validation-overview
title: Validation Process Overview
tags: [client, validator, authority]
audience:
  allow: ["client", "validator", "authority"]
  deny: ["supplier"]
---

Meanwhile, an internal architecture page:

---
id: zadif-routing-engine
title: ZADIF Dispatch Routing Logic
tags: [internal, restricted]
audience:
  allow: ["internal"]
---

And a mixed audience page:

---
id: ai-validation
title: AI Validation & Governance
tags: [validator, authority, internal]
audience:
  allow:
    - validator
    - authority
    - internal
---

📌 Validators & authorities see more detail than clients 📌 Internal staff see everything 📌 Clients see nothing tagged validator/authority unless also tagged client 📌 Restricted content is fully locked away

Multi-Audience Content Within the SAME Page

Since we want parts of a page visible to different audiences:

We can implement block-level audience gating with Docusaurus custom MDX components.

Example:

<ClientOnly>
### What Clients See
This section explains the validation process in simple terms.
</ClientOnly>

<ValidatorOnly>
### What Validators See
This section includes deeper auditability, trust scoring explanations, and evidence workflow details.
</ValidatorOnly>

<InternalOnly>
### Internal Architecture Notes
ZADIF integration with DaVE and DICE occurs through event-level routing and semantic metadata.
</InternalOnly>

Or with your own components:

<Audience role="client">
High-level conceptual explanation goes here.
</Audience>

<Audience role="validator">
Validation flow, supported evidence formats, verification workflow mapping...
</Audience>

<Audience role="internal">
SSSR schema, MEID routing, engine registry links, DAL anchoring methods...
</Audience>

This gives us infinite flexibility while maintaining a single canonical source.

Governance Rules for What Each Audience May See

🔵 Clients (Broadest External Access)

Clients should NOT see:

• Micro-engine internals (MICE)
• Routing logic (ZADIF)
• SSSR schemas
• USO ontology
• AI prompt templates
• Data pipeline architecture
• Telemetry scoring logic
• Trust score formulas
• Engine registry entries
• SQL/XML/XBRL technical references
• AI governance risk register
• DAL/DAR deep internals

Clients MAY see:

• High-level diagrams
• Validation process (conceptual)
• AI governance principles
• What trust scores mean, not how computed
• Evidence and verification workflows
• CSRD/ESRS mapping
• Form usage guides
• What a micro-engine is, but not how it works

⸻

🟣 Validators & Authorities

Should see:

• Validation layers: DICE, DaVE, VTE conceptually
• Trust model (but not internal scoring algorithms)
• Audit log concepts (ALTD)
• How evidence flows map to reporting outputs
• Assurance overview
• CSRD/ESRS alignment details
• iXBRL/XBRL mapping methodology
• How policies & procedures are evaluated
• What ZARA does in the reasoning pipeline

Should not see:

• Micro-engine registry
• USO/SSSR schemas
• Engine routing patterns
• MEID identifiers
• Internal fallback logic
• Model embeddings or prompts
• Internal AI governance risk register

Regulators need assurance, not internals.

⸻

🔴 Internal (Viroway staff and hired developers)

Can see everything, including:

• MICE architecture
• MEIDs
• Internal routing
• SSSR + USO schemas
• Audit sequences
• ZADIF + ZAAM + ZARA high-level + internal details
• All technical manuals
• SRE runbooks
• Internal architecture maps
• Database schemas
• Telemetry scoring formulas

⸻

🔒 Restricted Internal

For the safest areas:

• AI risk registers & validation logs (from Appendices)
• DAL, EAC, FITI internals
• Engine orchestration definitions
• Architecture that could be reverse-engineered
• Schema versioning & compatibility policy (CMCB)
• Internal assurance federation logic

Accessible only to technical leadership, external project manager & CTO-level roles.

How to Organize the Repo with Universal Tagging

Structure example:

docs/
  01-introduction/
  02-getting-started/
  03-client-guides/
  04-validator/
  05-authority/
  06-partner-integrations/
  07-ecosystem/
  08-concepts/
  09-architecture/        (tag: internal)
  10-ai-governance/       (tag: internal)
  11-engines/             (tag: internal, restricted)
  12-sssr/                (tag: internal, restricted)
  13-zadif/               (tag: internal, restricted)
  14-sre/
  15-roadmap/             (tag: internal)

Single repo → multiple audiences → one canonical truth.

What Happens When a Page Has Mixed Content?

Use your audience gating components to hide/reveal parts:

Example: “How Validation Works”

• ✔ Client sees a simple workflow
• ✔ Validator sees deeper notes about evidence and trust tagging
• ✔ Internal sees the full computational stack with engine references

All in one file.

Security Model

Even if validators & authorities merely require email-based pre-registration, the real protection comes from:

• Local MDX gating
• Tag blocking
• Role-based routing
• Cloudflare Access (optional)
• Audience conditional rendering

Because even if they view page source — the gated internal content never renders for them.

The Resulting Documentation Philosophy

“ZAYAZ Documentation Should Feel Unified, but Dynamically Reveal Itself Based on Who You Are.”

Clients see:

“This is simple, safe, and intelligent.”

Validators see:

“This is rigorous, auditable, and standards-based.”

Authorities see:

“This is compliant, controlled, and governance-aligned.”

Internal staff see:

“Here’s the code, architecture, and logic.”

Everyone sees what they should — nothing more.

Additional documents:

✔ The “Plain English Style Guide”

• tone, vocabulary, examples, structure

✔ The stakeholder-specific disclosure matrix

• exactly what each user group may/should/must not see

✔ Docusaurus folder structure & naming convention

• so your manual stays clean and scalable

✔ A reusable template for each documentation page

• with a “plain English” section + “tech spec” section side-by-side