Pcnaid Documentation Network — Architecture Standard

Version: 1.1 Status: Approved Approved by: Abdul Badran, CEO, Pcnaid Inc. Approval date: 2026-05-20 Primary repository: github.com/PcnaidInc/documentation Mirror (read-only): bitbucket.org/atlasrealty/documentation Custom domain: https://docs.pcnaid.com Docs platform: Mintlify (renders from the GitHub repo)

How to Read This Document

This file is the single authoritative reference for every AI model, LLM agent, workflow, automation, and human contributor that touches the Pcnaid documentation repository. It is written to eliminate ambiguity. If this document does not cover a scenario, the correct action is to stop and ask a human — never invent a convention. Rules for AI/LLM models reading this file:

Do not deviate from naming conventions, folder structures, or frontmatter schemas defined here — even if you believe a deviation would be “better.”
Do not create folders or files that are not explicitly allowed by the hierarchy defined in §3.
When in doubt between two valid interpretations, choose the one that results in fewer folders and fewer files.
Never delete or overwrite a file with review_status: locked in its frontmatter.
Never auto-merge a PR. All PRs require human approval or Reviewer Bot approval (§12).
Always read this entire file before beginning any work on the repository. Do not skim.

1. Core Vocabulary (Locked Terms)

These terms have precise meanings throughout the network. Do not use them loosely or interchangeably.

Network — the entire PcnaidInc/documentation repository. There is exactly one Network. It has one namespace, one search index, one brand identity, and one custom domain (docs.pcnaid.com).
Hub — an industry or ecosystem landing page that groups multiple related Nodes. A Hub does not contain content of its own beyond a short introduction. Its pages are 90% auto-generated from the Nodes that reference it. Example: “Shopify Ecosystem Hub” groups every Pcnaid Shopify app, extension, and theme.
Node — a single product’s complete documentation set. A Node is the atomic unit of the network. Every product gets exactly one Node, and that Node contains everything about that product: merchant docs, developer docs, partner docs, help center, KB, glossary, changelog, and API reference. Example: “Pcnaid Loyalty & Rewards” is a Node.
Track — an audience lens inside a Node. There are exactly three Tracks. No more may be added without a governance review (§15):
- merchant — non-technical end-users. No code blocks longer than 3 lines. Heavy screenshots. Plain language.
- developer — technical integrators, contributors, API consumers. Code-first. Assumes Git and terminal literacy.
- partner — business affiliates, resellers, co-marketing partners. Prose plus tables. Contracts, commissions, revenue examples. No code. Includes downloadable PDF versions of legal documents.
Surface — a functional area inside a Track. Surfaces are the leaf-level containers. The allowed Surfaces per Track are defined in §5 and are a closed set.
Leaf — an individual .mdx content file. The smallest addressable unit in the network.
Edge — a cross-link between Nodes, Hubs, or Leaves, declared in frontmatter. Edges are machine-readable and used by automation to build the link graph, related-content sidebars, and broken-link reports.
scope.json — a machine-readable configuration file at the Hub and Node level that governs: which folders the scoped live chat retrieves from, which LLM model is used for that scope, which llms.txt files are generated, and which parent scope to fall back to.

2. Infrastructure Stack (Simplified)

The entire documentation network runs on three infrastructure components. No external databases, no third-party vector stores, no paid hosting beyond what is already in use.

2a. GitHub Actions (All Automation)

Every automation task — nightly rebuilds, llms.txt generation, Confluence-to-Markdown sync, link checking, freshness monitoring, doc update PRs from code changes — runs as a GitHub Actions workflow inside the PcnaidInc/documentation repository. AI/LLM access for workflows:

GitHub Copilot — available natively in GitHub Actions.
OpenAI Codex — authenticated via OAuth (GitHub’s built-in OpenAI integration). Do NOT use API keys. Do NOT burn startup credits for documentation tasks.
Anthropic Claude — authenticated via OAuth (GitHub’s built-in Anthropic integration). Do NOT use API keys. Do NOT burn startup credits for documentation tasks.

Why this matters: All three LLMs are available to GitHub Actions workflows at zero marginal cost via OAuth integrations. The

2,500 OpenAI credits,

500 Anthropic credits, and all other startup credits listed in §2d are reserved exclusively for Pcnaid’s actual products (Shopify apps, custom web apps, mobile apps, etc.) — never for documentation maintenance.

2b. SQLite (All Data Storage)

Every data storage need in the documentation network is served by SQLite database files committed to the repository (for small, slow-changing data) or stored as GitHub Actions artifacts (for larger, frequently-rebuilt data like vector indexes). Use cases:

Scope indexes for scoped live chat — one .sqlite file per Node/Hub containing the vectorized chunks for that scope.
Link graph — a single graph.sqlite at the network root containing all edges between all Leaves, Nodes, and Hubs.
Metadata lookups — contributor data, sync timestamps, review history, credit burn logs.
Search index supplements — any structured data that Mintlify’s built-in search doesn’t cover.

Rules:

SQLite files larger than 50 MB must be stored as GitHub Actions artifacts, not committed to the repo.
SQLite files smaller than 50 MB may be committed to the repo under the /data/ top-level folder.
Every SQLite file must have a corresponding schema migration file under /data/migrations/.
Never use MySQL, PostgreSQL, MongoDB, Redis, Supabase, or any external database for documentation infrastructure.

2c. GitHub Pages + Mintlify (Rendering)

The documentation site at docs.pcnaid.com is rendered by Mintlify from the GitHub repo. Mintlify handles:

Static site generation from .mdx files.
Built-in search indexing.
Built-in AI chat widget (scoped by page context).
OpenAPI spec rendering for API reference pages.
Custom domain SSL.

GitHub Pages serves as a fallback for any static assets, runbooks, or tools that Mintlify doesn’t render (e.g., the playground proxy, status embeds).

2d. Startup Credits (Reserved for Products, NOT Documentation)

The following credits are available to Pcnaid but are explicitly NOT to be used for documentation infrastructure. They are reserved for actual product development:

Provider	Credits	Reserved For
OpenAI	$2,500	Shopify apps, custom web apps, mobile apps
Anthropic	$500	Shopify apps, custom web apps, mobile apps
Cloudflare	(free tier + credits)	Product hosting, CDN for apps
Chroma (TryChroma)	credits	Product-level RAG if needed
Render	credits	Product app hosting
Sentry	credits	Product error tracking
PostHog	credits	Product analytics
Datadog	credits	Product monitoring (if needed)
MongoDB	credits	Product databases
Redis	credits	Product caching
Auth0	credits	Product authentication
Clerk	credits	Product authentication
ElevenLabs	credits	Product voice features (future)
Make.com	credits	Product-level automation triggers
Modal	credits	Product compute
Linear	credits	Product issue tracking
Amplitude	credits	Product analytics
Mixpanel	credits	Product analytics
Algolia	credits	Product search
Airtable	credits	Product data management
Daytona	credits	Product dev environments
Confluent Cloud	credits	Product event streaming (if needed)
GitLab	credits	Product CI/CD (if needed)
TiDB	credits	Product databases (if needed)
Bubble.io	credits	Product rapid prototyping (if needed)
Asana	credits	Product project management
Cobo.com	credits	Product fintech (if needed)

Enforcement rule: If an AI model or automation attempts to configure an API key or OAuth connection to any of the above services for documentation purposes, it must stop and flag the action for human review. Documentation runs on GitHub Actions + SQLite + Mintlify only.

3. Folder Layout (Complete Reference)

The repository follows a strict hierarchy. This section shows the full depth of the tree with concrete examples so that no AI model needs to guess how deep folders go or what they contain.

3a. Top-Level Structure

/
├── architecture/
│   └── STANDARD.md                           ← THIS FILE (never auto-edited)
├── namespace/
│   ├── index.mdx                             ← global landing page for docs.pcnaid.com
│   ├── llms.txt                              ← auto-generated, slim index of all Hubs/Nodes
│   ├── llms-full.txt                         ← auto-generated, full Markdown export for IDE/agent ingestion
│   └── scope.json                            ← namespace-level chat scope (indexes entire network)
├── hubs/
│   ├── shopify-ecosystem/                    ← example Hub
│   │   ├── index.mdx                         ← Hub landing (90% auto-generated from linked Nodes)
│   │   ├── llms.txt                          ← auto-generated, catalog of this Hub's Nodes
│   │   └── scope.json                        ← Hub-level chat scope
│   ├── small-business-stack/                 ← another example Hub
│   │   ├── index.mdx
│   │   ├── llms.txt
│   │   └── scope.json
│   └── merchant-omnichannel/                 ← another example Hub
│       ├── index.mdx
│       ├── llms.txt
│       └── scope.json
├── nodes/
│   └── (see §3c for full Node structure)
├── shared/
│   ├── brand/                                ← logos, color tokens, typography
│   ├── snippets/                             ← MDX fragments reused across Tracks
│   ├── assets/                               ← images, SVGs, videos
│   ├── legal/                                ← terms, privacy policy, partner agreements
│   └── templates/                            ← MDX page templates for AI to clone
├── data/
│   ├── graph.sqlite                          ← network-wide link graph (auto-rebuilt nightly)
│   ├── analytics.sqlite                      ← page views, search queries, feedback
│   └── migrations/                           ← schema migration files for all SQLite DBs
├── automation/
│   ├── prompts/                              ← system prompts for each automation bot
│   │   ├── sync-bot.md
│   │   ├── reviewer-bot.md
│   │   └── hub-rebuilder.md
│   ├── templates/                            ← Jinja/Mustache templates for auto-generated pages
│   └── scripts/                              ← Python/Node utility scripts called by workflows
├── .github/
│   ├── workflows/                            ← GitHub Actions workflow files (one per automation)
│   │   ├── nightly-sync.yml
│   │   ├── reviewer-bot.yml
│   │   ├── hub-rebuilder.yml
│   │   ├── link-checker.yml
│   │   ├── freshness-monitor.yml
│   │   ├── llms-txt-generator.yml
│   │   └── confluence-sync.yml
│   ├── CODEOWNERS                            ← routes PR reviews by folder
│   └── pull_request_template.md
├── mintlify.json                             ← Mintlify workspace configuration
└── README.md                                 ← repo overview, links to this STANDARD

3b. Top-Level Categories (Closed Set)

Products are organized into exactly these categories under the nodes/ folder. This list is closed. Adding a new category requires a governance review (§15).

nodes/
├── services/                  ← consulting, bookkeeping, strategy, entity formation,
│                                 merchant processing, utilities, telecom, etc.
├── shopify/                   ← every Shopify app, theme, extension, POS integration
├── web-apps/                  ← custom SaaS web applications
├── mobile-apps/               ← iOS, Android, cross-platform
├── browser-extensions/        ← Chrome, Firefox, Edge, Safari
├── desktop-apps/              ← Electron, native Windows/macOS/Linux
├── integrations/              ← middleware, connectors, API gateways between products
└── hardware/                  ← physical products, POS terminals, ATMs (if applicable)

3c. Full Node Structure (6-Level Example)

Below is the complete folder tree for a single Node, expanded to show all six levels. Every Node follows this exact skeleton. When an AI creates a new Node, it clones this structure and populates the manifest files. Example: Shopify Loyalty & Rewards app

nodes/shopify/loyalty-rewards/                              ← LEVEL 1: Category + Node
├── node.json                                               ← machine-readable Node manifest
├── index.mdx                                               ← Node landing page
├── scope.json                                              ← Node-level chat scope config
├── llms.txt                                                ← auto-generated, slim product index
├── llms-full.txt                                           ← auto-generated, full product export
│
├── merchant/                                               ← LEVEL 2: Track
│   ├── _track.json                                         ← Track manifest (display name, icon, description)
│   ├── index.mdx                                           ← Track landing ("Welcome, store owners!")
│   ├── guides/                                             ← LEVEL 3: Surface
│   │   ├── index.mdx                                       ← Surface landing (list of all guides)
│   │   ├── getting-started.mdx                             ← LEVEL 4: Leaf
│   │   ├── setting-up-points.mdx
│   │   ├── customizing-rewards.mdx
│   │   └── importing-existing-customers.mdx
│   ├── tutorials/
│   │   ├── index.mdx
│   │   ├── first-loyalty-campaign.mdx
│   │   └── holiday-promotions.mdx
│   ├── help/                                               ← help center articles
│   │   ├── index.mdx
│   │   ├── troubleshooting-points-not-showing.mdx
│   │   ├── billing-faq.mdx
│   │   └── uninstall-and-data-export.mdx
│   ├── knowledge-base/                                     ← searchable FAQ / KB
│   │   ├── index.mdx
│   │   ├── how-points-expire.mdx
│   │   └── supported-currencies.mdx
│   └── glossary.mdx                                        ← product-specific glossary terms
│
├── developer/                                              ← LEVEL 2: Track
│   ├── _track.json
│   ├── index.mdx
│   ├── quickstart.mdx
│   ├── architecture-overview.mdx
│   ├── api/                                                ← LEVEL 3: Surface
│   │   ├── index.mdx                                       ← API overview + authentication
│   │   ├── openapi.yaml                                    ← OpenAPI 3.x spec (Mintlify renders this)
│   │   ├── customers.mdx                                   ← LEVEL 4: Leaf (per-endpoint page)
│   │   ├── points.mdx
│   │   ├── rewards.mdx
│   │   ├── tiers.mdx
│   │   └── webhooks-reference.mdx
│   ├── sdk/
│   │   ├── index.mdx
│   │   ├── javascript.mdx
│   │   └── react-components.mdx
│   ├── webhooks/
│   │   ├── index.mdx
│   │   ├── events-list.mdx
│   │   └── handling-webhooks.mdx
│   ├── playground.mdx                                      ← embeds the shared playground service
│   ├── guides/
│   │   ├── index.mdx
│   │   ├── authentication-deep-dive.mdx
│   │   ├── rate-limiting.mdx
│   │   └── testing-in-development.mdx
│   ├── tutorials/
│   │   ├── index.mdx
│   │   ├── build-a-custom-rewards-widget.mdx
│   │   └── integrate-with-existing-pos.mdx
│   ├── changelog.mdx
│   └── glossary.mdx
│
├── partner/                                                ← LEVEL 2: Track
│   ├── _track.json
│   ├── index.mdx
│   ├── affiliate-program.mdx
│   ├── commission-structure.mdx
│   ├── co-marketing.mdx
│   ├── reseller-agreement.mdx
│   ├── guides/
│   │   ├── index.mdx
│   │   └── selling-loyalty-to-merchants.mdx
│   └── glossary.mdx
│
└── _shared/                                                ← Node-level shared assets
    ├── snippets/                                           ← MDX fragments reused across Tracks
    │   ├── pricing-table.mdx
    │   └── support-contact-block.mdx
    ├── assets/
    │   ├── loyalty-rewards-logo.svg
    │   ├── loyalty-rewards-screenshot-dashboard.png
    │   └── loyalty-rewards-screenshot-points.png
    └── metadata.json                                       ← contributors, source repos, SLAs

3d. Depth Rules (Hard Caps)

Level	What It Represents	Example Path
1	Category + Node slug	`nodes/shopify/loyalty-rewards/`
2	Track	`nodes/shopify/loyalty-rewards/merchant/`
3	Surface	`nodes/shopify/loyalty-rewards/merchant/guides/`
4	Leaf (content file)	`nodes/shopify/loyalty-rewards/merchant/guides/getting-started.mdx`
5	MAXIMUM for sub-sections	`nodes/shopify/loyalty-rewards/developer/api/v2/customers.mdx`
6	NEVER ALLOWED	If you reach level 6, STOP. The Node must be split.

What to do when you hit the depth cap:

If you have a folder that would be at level 5 and it needs sub-folders, that is a signal the Node is too large.
Split the Node into two Nodes. Example: if the Loyalty app’s API grows to have separate v1 and v2 versions with completely different endpoint sets, create nodes/shopify/loyalty-rewards-v1/ and nodes/shopify/loyalty-rewards-v2/ as separate Nodes.
If the content just needs grouping within a level-4 leaf, use section: frontmatter tags inside the MDX file instead of creating a new folder.

Common mistake to avoid: Do not create folders like nodes/shopify/loyalty-rewards/developer/api/customers/endpoints/create.mdx. The customers.mdx file at level 4 should contain all endpoints for the Customers resource. If the file gets too long (over 500 lines), split by resource, not by action: customers.mdx, points.mdx, rewards.mdx — all at level 4.

4. Hub Rules

4a. What Justifies a Hub

A Hub exists when two or more Nodes meet at least two of these five criteria:

Data flow — products read from or write to each other’s APIs or databases.
Shared industry — both serve the same merchant vertical (Shopify merchants, accountants, restaurants, etc.).
Shared authentication — single sign-on or shared user identity.
Marketed as a bundle — sold together or priced as a package.
Shared support SLA — one support team handles issues across both.

4b. Examples of Valid Hubs

hubs/shopify-ecosystem/ — groups the Loyalty app, any future Shopify apps, theme extensions, POS integration. Criteria met: data flow + industry + auth.
hubs/small-business-stack/ — groups bookkeeping + merchant processing + strategic planning services. Criteria met: industry + bundle.
hubs/merchant-omnichannel/ — groups Shopify apps + POS + mobile merchant app. Criteria met: data flow + bundle + shared auth.

4c. Hub Membership

A Node can belong to multiple Hubs.
A Node exists exactly once as a folder under nodes/. It is referenced from Hubs via the hubs: frontmatter array in its files — never duplicated.
Every Node declares one “home” Hub in its scope.json → home_hub field. This determines which Hub the “Back to Hub” breadcrumb points to.

4d. Hub Content Rules

Hub landing pages (hubs/<slug>/index.mdx) are 90% auto-generated from a query over all Nodes that list that Hub in their hubs: frontmatter.
The remaining 10% is a hand-written introduction (2-4 paragraphs) explaining the ecosystem.
Adding a product to a Hub is a one-line frontmatter edit in the Node’s files — never a Hub page rewrite.

4e. Hub Governance

Adding a new Hub requires a PR containing a HUB_PROPOSAL.md file in the new Hub’s folder that justifies it against the five criteria. AI can draft the proposal, but only a human can merge it.

5. Node Internal Structure (The Template)

5a. Allowed Surfaces Per Track

This is a closed set. Do not invent new Surfaces without a governance review. Merchant Track surfaces:

index.mdx (Track landing)
guides/ (how-to articles)
tutorials/ (step-by-step walkthroughs)
help/ (help center / support articles)
knowledge-base/ (searchable FAQ)
glossary.mdx (product-specific terms)

Developer Track surfaces (includes everything in Merchant, plus):

quickstart.mdx (getting started in under 5 minutes)
architecture-overview.mdx (system design explanation)
api/ (API reference pages + openapi.yaml)
sdk/ (SDK documentation per language)
webhooks/ (webhook events and handling)
playground.mdx (embeds the shared API playground)
changelog.mdx (version history)

Partner Track surfaces:

index.mdx (Track landing)
affiliate-program.mdx
commission-structure.mdx
co-marketing.mdx
reseller-agreement.mdx
guides/ (partner-specific guides)
glossary.mdx

5b. Required Files in Every Node

These files are mandatory and must exist in every Node, even if they are stubs:

node.json — machine-readable manifest (see §6b for schema)
index.mdx — Node landing page
scope.json — chat scope configuration (see §8b for schema)
merchant/index.mdx — Merchant Track landing
developer/index.mdx — Developer Track landing
partner/index.mdx — Partner Track landing
_shared/metadata.json — contributor info, source repos, SLAs

If a Track has no content yet, its index.mdx must contain a “Coming Soon” message following the standard frontmatter contract. Never leave it empty.

6. Frontmatter Contract

6a. The Law Every .mdx File Obeys

Every Leaf has standardized frontmatter. This is what lets automation build the graph, run link checks, scope chat, generate llms.txt files, and keep everything consistent.

---
title: "Customers API"
description: "One sentence describing the page. Used in search results and llms.txt."
slug: "customers"                       # kebab-case, no spaces, no special characters
node: "shopify/loyalty-rewards"         # category/node-slug — must match folder path
track: "developer"                      # EXACTLY ONE OF: merchant | developer | partner
surface: "api"                          # EXACTLY ONE OF the allowed surfaces for this track (see §5a)
audience_level: "intermediate"          # EXACTLY ONE OF: beginner | intermediate | advanced
content_type: "reference"              # EXACTLY ONE OF: concept | how-to | tutorial | reference | troubleshooting | faq
tags: ["customers", "auth", "rest-api"] # lowercase, kebab-case, 3-10 tags recommended
hubs: ["shopify-ecosystem", "merchant-omnichannel"]  # which Hubs surface this Node
edges:                                  # cross-links this page declares
  - type: "depends-on"                  # EXACTLY ONE OF: depends-on | related | see-also | prerequisite
    target: "shopify/loyalty-rewards/developer/api/authentication"
  - type: "related"
    target: "shopify/loyalty-rewards/merchant/guides/setting-up-points"
source:                                 # ONLY for auto-generated docs; omit for hand-written
  repo: "PcnaidInc/Shopify-Rewards-Loyalty-App"
  path: "app/routes/api.public.v1.customers.ts"
  last_synced: "2026-05-20T02:00:00Z"
  generator: "sync-bot-v1"
maintainer: "ai"                        # EXACTLY ONE OF: ai | human | hybrid
review_status: "auto-generated"         # EXACTLY ONE OF: draft | auto-generated | human-reviewed | locked
last_reviewed: "2026-05-20"
reviewed_by: "abdul@pcnaid.com"         # email of the last human reviewer
version: "1.0.0"                        # semver — follows source app version when generated
llms_include: true                      # whether to include this page in llms.txt generation
llms_priority: 3                        # 1 (highest) to 5 (lowest) — controls ordering in llms.txt
llms_persona: "developer"              # EXACTLY ONE OF: casual | developer | partner | all
---

The Reviewer Bot validates llms_priority as an integer from 1 through 5; booleans and quoted numbers are invalid. Within each Node, the Node-level index.mdx must have a value less than or equal to every other page’s value. Because 1 is the highest priority, this makes the Node landing page at least as high-priority as every sibling page.

6b. node.json Schema

{
  "node_id": "shopify/loyalty-rewards",
  "display_name": "Pcnaid Loyalty & Rewards",
  "category": "shopify",
  "slug": "loyalty-rewards",
  "status": "active",
  "home_hub": "shopify-ecosystem",
  "hubs": ["shopify-ecosystem", "merchant-omnichannel"],
  "source_repos": [
    {
      "repo": "PcnaidInc/Shopify-Rewards-Loyalty-App",
      "branch": "main",
      "sync_enabled": true
    }
  ],
  "tracks": ["merchant", "developer", "partner"],
  "created_at": "2026-05-20",
  "maintainer": "abdul@pcnaid.com",
  "compass_component_id": "optional-atlassian-compass-id"
}

6c. What the Frontmatter Enables

node + track + surface + slug → fully determines the URL. No guessing.
edges → nightly job builds a network-wide link graph for search, related-content sidebars, and broken-link detection.
source → automation knows which upstream repo triggers a regeneration.
review_status: locked → AI cannot overwrite this file. Human edits only.
maintainer: hybrid → AI drafts changes as PRs; humans approve.
llms_include + llms_priority + llms_persona → nightly job assembles llms.txt files.

7. Naming Conventions (Enforced by CI)

These rules are checked by the Reviewer Bot on every PR. Violations block the merge.

Folders: kebab-case. Singular unless the folder is a collection (guides/, tutorials/ are plural; developer/, merchant/ are singular).
Files: kebab-case.mdx for content; kebab-case.json for config. No dates in filenames. No version numbers in filenames (versioning lives in frontmatter).
Slugs in frontmatter: must match the filename exactly, minus the extension.
Node slugs: <product-name-kebab> (e.g., loyalty-rewards, NOT Pcnaid-Loyalty-Rewards-App, NOT pcnaid_loyalty).
Hub slugs: <ecosystem-kebab> (e.g., shopify-ecosystem).
Anchors in headings: auto-generated by Mintlify, lowercase, kebab-cased. Do not manually set anchors.
Image filenames: <node-slug>-<short-description>.png (e.g., loyalty-rewards-dashboard-overview.png). This prevents collisions when served from shared CDN.
Frontmatter keys: snake_case only. No camelCase, no PascalCase.
Git branches (AI-generated): ai/<category>/<node-slug>/<change-type>/<short-slug> (e.g., ai/shopify/loyalty-rewards/api-sync/add-customers-endpoint).
Commits (AI-generated): Conventional Commits format: docs(<category>/<node>): <description> (e.g., docs(shopify/loyalty-rewards): regenerate customers API reference).
PR titles (AI-generated): [AI] <category>/<node>: <description> (e.g., [AI] shopify/loyalty-rewards: update API docs from v1.2.0 release).

8. Scoped Live Chat

8a. Three Tiers

Users interact with an AI chat widget that is context-locked to where they are in the documentation:

Namespace chat (when user is on / or namespace/ pages) — indexes the entire network. For “I don’t know where to start” users.
Hub chat (when user is on hubs/<slug>/ pages) — indexes that Hub’s intro + all linked Nodes’ content. For “I know my industry but not which product” users.
Node chat (when user is on nodes/<category>/<slug>/ pages) — indexes only that Node’s folders. For “I’m using this product and need help” users.

8b. scope.json Schema

Every Hub and Node must have a scope.json. This is the configuration file that the chat system reads.

{
  "scope_id": "node-shopify-loyalty-rewards",
  "scope_type": "node",
  "display_name": "Loyalty & Rewards Support",
  "include_paths": [
    "nodes/shopify/loyalty-rewards/**"
  ],
  "exclude_paths": [
    "**/drafts/**",
    "**/_shared/assets/**"
  ],
  "persona_default": "casual",
  "fallback_scope": "hub-shopify-ecosystem",
  "home_hub": "shopify-ecosystem"
}

Fields explained:

scope_id — unique identifier. Format: <scope_type>-<category>-<slug> for Nodes, <scope_type>-<slug> for Hubs, namespace for the root.
scope_type — node, hub, or namespace.
include_paths — glob patterns for folders this scope retrieves from.
exclude_paths — glob patterns to exclude (drafts, binary assets, etc.).
persona_default — the default audience level for chat responses: casual, technical, or partner.
fallback_scope — if the chat can’t answer from this scope, which parent scope to try next. Nodes fall back to their home Hub; Hubs fall back to namespace.
home_hub — which Hub’s breadcrumb this Node shows. Required for Nodes; omitted for Hubs.

8c. Chat Implementation

The chat widget is Mintlify’s built-in AI chat, configured at the workspace level. Mintlify’s chat automatically uses the page context (which Node/Hub the user is on) to scope its retrieval. No custom chat backend is needed. If Mintlify’s built-in chat is insufficient for a specific scope, a secondary option is the Rovo Docs Agent in Atlassian Studio, scoped to the matching Confluence space (see §10).

9. llms.txt / llms-full.txt Rules

9a. What These Files Are

llms.txt is a slim, structured index of documentation links and descriptions, designed for AI tools to quickly understand what documentation exists. llms-full.txt is a complete Markdown export of the documentation content, designed for IDE integrations and agent workflows that can process large inputs.

9b. Placement Rules

Location	Files Generated	Pattern Used	Purpose
`/namespace/`	`llms.txt` + `llms-full.txt`	Index + Export (Anthropic/Vercel)	Global map of all Hubs and Nodes; full export for IDE/agent ingestion
`/hubs/<slug>/`	`llms.txt` only	Catalog (Stripe/Cloudflare)	Curated entry points into that ecosystem’s Nodes. No full export — too much overlap with Node-level exports
`/nodes/<category>/<slug>/`	`llms.txt` + `llms-full.txt`	Index + Export	Product-specific index and full content export
Track-level (e.g., `/nodes/.../merchant/`)	`llms.txt` only	Focused Workflow (Cursor/Windsurf)	Role-scoped entry points for that persona

9c. Generation Rules

All llms.txt and llms-full.txt files are auto-generated. Never hand-write them.
The generation job runs nightly as a GitHub Actions workflow (llms-txt-generator.yml).
Content is assembled from frontmatter fields: llms_include, llms_priority, llms_persona, title, description, and slug.
Pages with llms_include: false are excluded.
Pages are ordered by llms_priority (1 = first, 5 = last).
Pages are filtered by llms_persona to the appropriate Track-level llms.txt.

9d. llms.txt Format

# Pcnaid Loyalty & Rewards — Documentation

> Pcnaid's loyalty and rewards app for Shopify. Points, tiers, referrals, and custom rewards for merchants.

## Getting Started
- [Quickstart](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/quickstart): Set up the Loyalty app in under 5 minutes
- [Merchant Setup Guide](https://docs.pcnaid.com/shopify/loyalty-rewards/merchant/guides/getting-started): Configure points and rewards for your store

## API Reference
- [Customers API](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/api/customers): Create, read, update customer loyalty profiles
- [Points API](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/api/points): Award, redeem, and query point balances

## Webhooks
- [Events List](https://docs.pcnaid.com/shopify/loyalty-rewards/developer/webhooks/events-list): All webhook events the app emits

## Help & Support
- [Troubleshooting](https://docs.pcnaid.com/shopify/loyalty-rewards/merchant/help/troubleshooting-points-not-showing): Common issues and solutions
- [Billing FAQ](https://docs.pcnaid.com/shopify/loyalty-rewards/merchant/help/billing-faq): Pricing, plans, and payment questions

10. Atlassian Integration

Pcnaid has a full Atlassian stack. These tools supplement the GitHub-based documentation network — they do not replace it. GitHub is always the source of truth for published documentation.

10a. Tools and Their Roles

Atlassian Tool	Role in Documentation Network
Confluence Premium	Authoring and staging for non-technical content. WYSIWYG editing for merchant and partner Tracks. Synced to GitHub via nightly Confluence-to-Markdown workflow.
Jira Premium (23 existing spaces)	Documentation work tracker. Every doc update = a Jira ticket. AI creates tickets; Abdul approves and closes.
Bitbucket Premium	Read-only mirror of the GitHub `documentation` repo. Auto-synced. Not the primary.
Compass	Service catalog. Every Node and Hub is registered as a Compass Component with health scorecards.
JSM (Jira Service Management)	Help Center backend for customer-facing support. Each Node’s `help/` surface embeds the JSM portal filtered by product.
Rovo Studio	Custom AI agents scoped to Confluence knowledge. Secondary chat option alongside Mintlify’s built-in chat.
Loom Business+AI	Tutorial videos embedded in docs. AI transcripts auto-indexed for search.
Statuspage	One Statuspage per Hub (ecosystem-level status). Embedded in Hub landing pages.
Trello	Lightweight public-facing product roadmaps per Hub.
Goals	Track documentation coverage KPIs (% of Nodes fully populated, freshness scores, etc.).

10b. Rovo Agent Roster

These pre-built Atlassian agents are available and should be activated:

Pcnaid Docs Agent — scoped to all 23 Pcnaid Confluence spaces. Answers questions about internal docs.
Release Notes Drafter — triggered by Jira tickets with “Done” status. Drafts changelog entries.
User Manual Writer — long-form casual documentation generation.
Brand Voice Crafter — enforces Pcnaid tone and style on drafted content.
Job Listing Assistant — for hiring documentation (contractor job posts, etc.).

10c. Authoring Flow

Draft in Confluence (using Pcnaid Confluence spaces) or directly in Markdown.
Track as a Jira ticket in the matching Pcnaid Jira space (PCNCM, PCNDM, etc.).
Assist with Rovo agents for AI drafting help.
Publish via PR to github.com/PcnaidInc/documentation.
Render by Mintlify at docs.pcnaid.com.
Mirror auto-pushed to Bitbucket (read-only).

11. The Linking System

11a. Three Link Types

Hard links (edges in frontmatter) — machine-verified. The Reviewer Bot checks that every target in an edges array resolves to an existing file. If the target doesn’t exist, the PR is blocked.
Soft links (inline Markdown links in prose) — the nightly link checker flags 404s in a report. Does not block PRs, but generates a Jira ticket.
External links — checked weekly. Each external link gets a last_verified timestamp in the link graph database.

11b. Edge Types

Edge Type	Meaning	Display
`depends-on`	This page requires the target to be read first	”Prerequisites” sidebar section
`prerequisite`	Same as depends-on, reverse direction	Auto-generated from depends-on edges
`related`	Thematically similar content	”Related Pages” sidebar section
`see-also`	Loosely connected, good for further reading	”See Also” section at page bottom

11c. Back-Link Rules

Every Node links to every Hub that references it. This is auto-maintained by the Hub Rebuilder.
Every Hub landing page is auto-generated from a query over Nodes that list it in their hubs: frontmatter.
Every Node and Hub has a persistent “Back to Pcnaid Documentation” breadcrumb pointing at namespace/. Non-negotiable.
Every page within a Node has breadcrumbs: Pcnaid Docs > [Hub] > [Node] > [Track] > [Surface] > [Page Title].

12. Automation Architecture

12a. Six Automation Pillars

Each is a separate GitHub Actions workflow file. Failures are isolated — one bot failing does not block others. 1. Sync Bot (nightly-sync.yml)

Runs nightly at 02:00 CT.
For every registered source repo (declared in node.json > source_repos), pulls the latest code, diffs against last sync.
Feeds changed files + context to Claude or Codex (via OAuth) with the product-specific system prompt from automation/prompts/sync-bot.md.
Produces PRs against PcnaidInc/documentation grouped by Node.
PRs never auto-merge. Max 1 open AI-PR per Node at any time.

2. Reviewer Bot (reviewer-bot.yml)

Triggered on every AI-generated PR.
Runs: frontmatter validator, link checker, naming convention linter, depth-cap checker, style-guide linter, and a lightweight LLM “does this read well” pass.
Auto-approves only if ALL checks pass AND changes are restricted to files with maintainer: ai or hybrid.
Never auto-approves locked files. Flags them for human review.

3. Hub Rebuilder (hub-rebuilder.yml)

Triggered whenever a Node’s hubs: frontmatter changes.
Regenerates affected Hub landing pages from templates in automation/templates/.
Must complete in under 60 seconds.

4. Link Graph Builder (runs as part of nightly-sync.yml)

Crawls every Leaf’s frontmatter, extracts all edges.
Rebuilds data/graph.sqlite.
Outputs a JSON export at namespace/graph.json for frontend consumption.

5. Freshness Monitor (freshness-monitor.yml)

Runs weekly (Mondays at 08:00 CT).
Flags any Leaf with last_reviewed older than 180 days.
Creates a Jira ticket in the relevant Pcnaid space for each stale page.
Posts a summary report as a GitHub Actions artifact.

6. llms.txt Generator (llms-txt-generator.yml)

Runs nightly after the Sync Bot completes.
Reads all frontmatter, assembles llms.txt and llms-full.txt files per the rules in §9.
Commits the regenerated files directly to main (no PR needed — these are fully deterministic outputs).

7. Confluence Sync (confluence-sync.yml)

Runs nightly.
For Confluence pages flagged for export (via Confluence label sync-to-docs), converts to Markdown and creates/updates PRs.
Handles image downloads and re-paths them to _shared/assets/.

12b. Trigger Sources

GitHub webhook on every Pcnaid source repo → enqueues a sync job.
Scheduled cron for nightly batch sync (catches anything webhooks missed).
Manual trigger — gh workflow run nightly-sync for any Node.
On-release trigger — a source repo cutting a semver release always triggers sync.
Drift alarm — if a Node hasn’t been synced in 7 days despite commits in its source repo, creates a high-priority Jira ticket.

12c. Rate Limiting

Max 1 open AI-PR per Node at any time.
If a new sync job runs while an AI-PR is open, the new changes are rebased onto the existing PR.
If the rebase fails (merge conflict), the old PR is closed and a new one is created with a comment linking to the closed PR.

13. Audience-Aware Content Rules

13a. Track-Specific Writing Rules

Merchant Track — single-column prose. Heavy screenshots. No JSON. No code blocks longer than 3 lines. Every page starts with a “What does this do for me?” section. Reading level: 8th grade or below.
Developer Track — dual-column asymmetric layout for API pages (Mintlify’s 60/40 split with dark code column). Code-first examples. Assumes Git, terminal, and HTTP literacy. Every API page includes a working curl example.
Partner Track — prose plus tables. Revenue projections, commission schedules, case studies. No code. Includes downloadable PDF versions of legal documents (generated from the Markdown source).

13b. Cross-Track Linking Rule

Every guide can (and should) link to its counterpart on another Track. A merchant guide explaining “what webhooks are” links to the developer deep-dive; the developer page links back to the plain-English merchant version. These are related edges in frontmatter.

14. Failure Modes & Safeguards

Failure	Mitigation
Runaway AI generation	Sync Bot capped at 1 open PR per Node. Queue backups create a Jira alert.
Contradictory human + AI edits	Humans always win merge conflicts. AI PRs are rebased, not force-pushed.
Source repo deleted	Sync jobs fire a “tombstone” alert. Node is NOT auto-deleted. Manual archive only.
Broken external links	Weekly check produces a report. Never auto-removes links.
LLM hallucination	Every AI-generated file has `review_status: auto-generated`. UI renders a “This page was AI-generated” banner until a human sets `review_status: human-reviewed`.
Search poisoning	Mintlify’s AI assistant prioritizes `human-reviewed` and `locked` pages over `auto-generated` pages.
SQLite corruption	All SQLite files are rebuilt from source data (frontmatter + content). If corrupted, delete and re-run the nightly job. No data loss possible.
GitHub Actions quota exhaustion	Monitor Actions minutes via the billing API. Alert when 80% consumed. Reduce frequency of non-critical jobs (freshness monitor → biweekly).
Mintlify build failure	Mintlify builds are isolated from the Git repo state. A bad MDX file blocks rendering but not the repo. The Reviewer Bot’s frontmatter validator catches most MDX errors before merge.

15. Governance (Human-in-the-Loop Checkpoints)

AI maintains the network, but humans control these gates:

Adding a new top-level category under nodes/ — human only.
Adding a new Hub — human only (AI drafts the HUB_PROPOSAL.md).
Adding a new Track beyond the three defined (merchant/developer/partner) — human only. This has never been needed and likely never will be.
Adding a new Surface to the closed set — human only.
Marking a file as review_status: locked — human only.
Merging any PR that touches architecture/STANDARD.md — human only.
Merging any PR that touches namespace/ — human only.
Changing the frontmatter contract or naming conventions — human only.
Deleting any Node or Hub — human only.
Configuring API keys or OAuth tokens for external services — human only.

Everything else — creating new Nodes, new Leaves, updating existing Leaves, regenerating references, rebuilding link graphs, generating llms.txt files — AI can do autonomously as long as the PR passes the Reviewer Bot.

16. Shared Infrastructure Rules

One Mintlify workspace hosts the entire network. Mintlify charges per workspace, not per product. Use folder routing, not multiple workspaces. One API playground backend (playground.pcnaid.com) — a single Cloudflare Worker or GitHub Pages-hosted tool that proxies “Try It” requests. Each API reference page embeds it with ?node=shopify/loyalty-rewards&api=v1. Zero per-Node code. One search index — Mintlify’s built-in search. node and track frontmatter become filter facets. One CDN — Cloudflare in front of docs.pcnaid.com. Images and assets under shared/assets/ or nodes/<category>/<slug>/_shared/assets/. One OpenAPI renderer — Mintlify renders every Node’s openapi.yaml. No per-Node tooling. One CI/CD pipeline — GitHub Actions. One workflow file per automation pillar. One version control repo — PcnaidInc/documentation. Monorepo. CODEOWNERS routes reviews.

17. Rollout Phasing

Phase 0 — Foundations (week 1): Stand up PcnaidInc/documentation with the full folder skeleton, namespace/ landing page, one pilot Node (Shopify Loyalty & Rewards), the frontmatter contract, CI with the Reviewer Bot in dry-run mode, and architecture/STANDARD.md (this file).
Phase 1 — First Node Live (weeks 2-3): Fully populate the Loyalty & Rewards Node across all three Tracks. This validates the template end-to-end. Deploy to docs.pcnaid.com via Mintlify.
Phase 2 — First Hub Live (week 4): Create hubs/shopify-ecosystem/ with the Loyalty Node referenced. Hub Rebuilder automation proven. llms.txt generation proven.
Phase 3 — Automation Live (weeks 5-6): Sync Bot starts producing AI-PRs from the source repo. Reviewer Bot moves from dry-run to enforcing. Freshness Monitor active. Confluence Sync active.
Phase 4 — Scale (ongoing): Add each additional Node one at a time. Each follows the same template. AI handles bulk population. Humans review. New Hubs created as Node count justifies them.

18. Quick Reference for AI Models

If you are an AI model working on this repository, here is your checklist:

✅ Read this entire STANDARD.md before starting any work.
✅ Clone the Node template structure from §3c when creating a new Node.
✅ Use the exact frontmatter schema from §6a — no extra fields, no missing fields.
✅ Follow naming conventions from §7 — the Reviewer Bot will reject your PR if you don’t.
✅ Check the depth cap from §3d — if you’re creating a level-6 folder, stop and split the Node.
✅ Declare all cross-references as edges in frontmatter, not just inline links.
✅ Set review_status: auto-generated on everything you create. Never set human-reviewed or locked.
✅ Set maintainer: ai on files you create. Set maintainer: hybrid if a human asked you to update an existing file.
✅ Use Conventional Commits format for commit messages.
✅ Limit to 1 open PR per Node.
❌ Do NOT use startup credits or API keys for documentation tasks. Use OAuth-authenticated GitHub integrations only.
❌ Do NOT create external databases. Use SQLite files under /data/.
❌ Do NOT add new categories, Hubs, Tracks, or Surfaces without human approval.
❌ Do NOT delete or overwrite locked files.
❌ Do NOT auto-merge PRs.

End of Architecture Standard v1.1

​Pcnaid Documentation Network — Architecture Standard

​How to Read This Document

​1. Core Vocabulary (Locked Terms)

​2. Infrastructure Stack (Simplified)

​2a. GitHub Actions (All Automation)

​2b. SQLite (All Data Storage)

​2c. GitHub Pages + Mintlify (Rendering)

​2d. Startup Credits (Reserved for Products, NOT Documentation)

​3. Folder Layout (Complete Reference)

​3a. Top-Level Structure

​3b. Top-Level Categories (Closed Set)

​3c. Full Node Structure (6-Level Example)

​3d. Depth Rules (Hard Caps)

​4. Hub Rules

​4a. What Justifies a Hub

​4b. Examples of Valid Hubs

​4c. Hub Membership

​4d. Hub Content Rules

​4e. Hub Governance

​5. Node Internal Structure (The Template)

​5a. Allowed Surfaces Per Track

​5b. Required Files in Every Node

​6. Frontmatter Contract

​6a. The Law Every .mdx File Obeys

​6b. node.json Schema

​6c. What the Frontmatter Enables

​7. Naming Conventions (Enforced by CI)

​8. Scoped Live Chat

​8a. Three Tiers

​8b. scope.json Schema

​8c. Chat Implementation

​9. llms.txt / llms-full.txt Rules

​9a. What These Files Are

​9b. Placement Rules

​9c. Generation Rules

​9d. llms.txt Format

​10. Atlassian Integration

​10a. Tools and Their Roles

​10b. Rovo Agent Roster

​10c. Authoring Flow

​11. The Linking System

​11a. Three Link Types

​11b. Edge Types

​11c. Back-Link Rules

​12. Automation Architecture

​12a. Six Automation Pillars

​12b. Trigger Sources

​12c. Rate Limiting

​13. Audience-Aware Content Rules

​13a. Track-Specific Writing Rules

​13b. Cross-Track Linking Rule

​14. Failure Modes & Safeguards

​15. Governance (Human-in-the-Loop Checkpoints)

​16. Shared Infrastructure Rules

​17. Rollout Phasing

​18. Quick Reference for AI Models