UAIX Runtime Architecture Notes

Updated: 2026-04-24

Metadata

Field	Value
Source site	uaix.org
Source URL	https://uaix.org/
Canonical AIWikis URL	https://aiwikis.org/uaix/files/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-runtime-a-e51b653c/
Source reference	raw/system-archives/uaix/internal-memory-reorg/2026-05-01/docs/runtime-architecture.md
File type	md
Content category	memory-file
Last fetched	2026-06-22T01:56:21.9510185Z
Last changed	2026-04-24T01:38:24.9048199Z
Content hash	sha256:e51b653cbd4b47691bd2d49ff4e1c0ef9faae70e5f67cb56f37a081a84fc41da
Import status	unchanged
Raw source layer	data/sources/uaix/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-runtime-architecture-md-e51b653cbd4b.md
Normalized source layer	data/normalized/uaix/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-runtime-architecture-md-e51b653cbd4b.txt

Current File Content

Structure Preview

• UAIX Runtime Architecture Notes
• Status
• How To Use This Document
• Purpose
• Current Runtime Shape
• Current Architectural Strengths
• Architectural Concerns
• 1. Eager bootstrap on plugin load
• 2. Inconsistent isolation model across plugins
• 3. Activation assumes compatibility instead of proving it
• 4. Dependency modeling is incomplete
• 5. Packaging and deployment are architecture
• 6. The smoke-test gate must remain mandatory
• 7. Observability is too weak for operational debugging
• 8. Public routing logic must remain isolated from admin behavior
• Key Code Signals Behind These Concerns
• Current Decision Directions
• Standardize plugin boot
• Standardize naming and isolation
• Standardize dependencies
• Standardize deployment
• Standardize diagnostics
• Recommended Next Steps

Raw Version

# UAIX Runtime Architecture Notes

Updated: 2026-04-24

## Status

This is a supporting runtime and architecture note.

It is not a canonical launch-truth document.

## How To Use This Document

- Use this file to understand current runtime architecture concerns, plugin boot patterns, and deployment-adjacent technical risks.
- Prefer `docs/deploy.md` for current release procedure.
- Prefer `docs/roadmap.md` for future runtime and release-architecture priorities.
- Prefer implemented source code for current runtime behavior.

Selective traversal helpers:

- `docs/navigation/implementation-and-runtime.md` for current technical ownership flow
- `wp-content/plugins/README.md` when you need to narrow quickly to one plugin source tree
- `docs/navigation/operations-and-release.md` when architecture concerns overlap packaging, smoke testing, or deployment behavior

## Purpose

This document records the architectural concerns that still matter to the current UAIX WordPress runtime.

The goal is to keep a short list of the patterns that affect reliability, packaging, routing, and maintainability across the custom UAIX theme and plugin stack.

## Current Runtime Shape

- `uaix-authority-theme` is the active public theme and owns the public launch surface.
- `uaix-core`, `uaix-bridge`, `uaix-modules`, `uaix-seo-sweep`, and `ns12-locale-router` form the current custom plugin and runtime layer.
- `docs/deploy.md` defines the supported packaging, smoke-test, and release workflow.
- `docs/roadmap.md` tracks future runtime hardening so completed launch-surface work does not remain in architecture notes as open roadmap work.
- Implemented source code remains the final truth for exact runtime behavior.

## Current Architectural Strengths

- `ns12-locale-router` already uses a more resilient structure than the older UAIX plugins, including lightweight activation and setup work, admin diagnostics, Site Health exposure, and explicit locale-routing checks.
- The release process now has a scripted packaging and Studio smoke-test path through `scripts/publish-wordpress-packages.ps1` and `scripts/smoke-test-wordpress-packages.ps1`.
- Public routing expectations, root SEO files, and locale-path verification are centralized in `docs/deploy.md` instead of being spread across ad hoc notes.

## Architectural Concerns

### 1. Eager bootstrap on plugin load

Several plugins fully bootstrap themselves as soon as WordPress includes the main plugin file.

Examples in the current code:

- `wp-content/plugins/uaix-core/uaix-core.php` loads bootstrap files and immediately calls `uaix_core()`
- `wp-content/plugins/uaix-bridge/uaix-bridge.php` immediately calls `uaix_bridge()`
- `wp-content/plugins/uaix-modules/uaix-modules.php` immediately calls `uaix_modules()`
- `wp-content/plugins/ns12-locale-router/ns12-locale-router.php` immediately boots `\Ns12LocaleRouter\Plugin::boot( __FILE__ )`

Architectural risk:

- if any required file, class, function, or WordPress API assumption is wrong for the host environment, plugin activation fails hard instead of failing gracefully
- heavy setup work is harder to isolate from activation, recovery, and diagnostics

Required direction:

- shift to lightweight bootstrap files
- perform environment and dependency preflight checks before constructing runtime objects
- delay expensive or coupled service creation until hooks such as `plugins_loaded`, `init`, or explicit capability-checked admin flows

### 2. Inconsistent isolation model across plugins

The UAIX plugin set currently mixes two architectural styles:

- legacy-style global classes and functions in `uaix-core`, `uaix-bridge`, and `uaix-modules`
- namespaced implementation in `ns12-locale-router`

Examples:

- global classes such as `UAI_Core_Plugin`, `UAI_API_Bridge_Plugin`, `UAI_Modules_Plugin`
- global helper functions such as `uaix_core()`, `uaix_bridge()`, and `uaix_modules()`
- namespaced classes under `Ns12LocaleRouter\...`

Architectural risk:

- class and function name collisions become more likely
- stale plugin copies or duplicate installs become harder to reason about
- the stack is harder to test, package, and evolve consistently
- shared patterns are harder to document when each plugin boots differently

Required direction:

- standardize all UAIX plugins on namespaced code
- keep globally exposed helper functions to an absolute minimum
- adopt one plugin boot pattern across the entire UAIX plugin family

### 3. Activation assumes compatibility instead of proving it

Plugin headers declare minimum WordPress and PHP versions, but the runtime architecture still assumes the environment is compatible once activation starts.

Current pattern:

- activation hooks mostly just set options or flush rewrite rules
- there is no shared runtime preflight layer that validates environment support before full boot

Architectural risk:

- activation failures are discovered only after WordPress attempts to load real code
- the admin experience degrades into generic fatal activation errors instead of actionable compatibility notices
- production and local behavior can drift when requirements are only checked implicitly

Required direction:

- add a shared UAIX preflight routine for PHP version, WordPress version, required extensions, required functions, writable directories, and REST dependencies
- show admin notices and block activation cleanly when requirements are not met
- do not instantiate service objects until preflight passes

### 4. Dependency modeling is incomplete

`uaix-modules` depends on core contracts from `uaix-core`, but the current architecture only detects this after the plugin is loaded.

Current behavior:

- `uaix-modules` checks for `UAI_Module_Interface` during `plugins_loaded`
- if missing, it displays an admin notice and returns

Architectural risk:

- dependencies are implicit instead of enforced
- activation order and environment state can affect behavior
- WordPress cannot reason about plugin dependencies before activation
- troubleshooting becomes slower because missing dependencies surface too late

Required direction:

- use WordPress plugin dependency metadata where supported
- make `uaix-core` the authoritative runtime dependency for `uaix-modules`
- consider whether `uaix-bridge` should depend on `uaix-core` or remain explicitly standalone

### 5. Packaging and deployment are architecture

WordPress installation behavior depends on archive shape, release structure, and repeatable validation. Packaging mistakes and manual-upload confusion are architectural reliability problems, not just release-process mistakes.

Architectural risk:

- installers can create broken plugin paths
- activation URLs can point to missing files
- deployment confidence drops even when code is otherwise correct
- manual uploads can be misread as source problems when the real issue is a stale ZIP, wrong ZIP, or overwrite failure

Required direction:

- keep packaging logic scripted and version-controlled
- verify archive contents through the deployment checklist in `docs/deploy.md`
- treat installability as part of the architecture acceptance criteria

### 6. The smoke-test gate must remain mandatory

The workspace now has a scripted publish-and-smoke-test path through `scripts/publish-wordpress-packages.ps1` and `scripts/smoke-test-wordpress-packages.ps1`, with the expected operational checklist captured in `docs/deploy.md`.

Architectural risk:

- packaging issues, parse errors, missing files, and host assumptions can still escape if contributors bypass the scripted release path
- optional packaging-only runs such as `-SkipStudioSmokeTest` can be misused if they are treated as release approval instead of temporary exceptions
- locale-routing, root-file, and manual-install edge cases can regress if smoke testing is treated as optional

Required direction:

- keep the repeatable smoke-test gate in place for each plugin and theme release
- reserve `-SkipStudioSmokeTest` for clearly documented exceptions
- use the canonical checklist in `docs/deploy.md`

### 7. Observability is too weak for operational debugging

The current architecture still needs stronger diagnostic visibility when activation or routing fails on a remote site.

Architectural risk:

- the team sees only generic WordPress activation errors
- the real fatal cause remains hidden until someone accesses server logs manually
- routing or packaging regressions are harder to confirm without explicit diagnostics in wp-admin and Studio smoke tests

Required direction:

- enable `WP_DEBUG_LOG` in non-production test environments
- document recovery mode and log collection steps
- add guarded diagnostic logging around bootstrap and preflight failures

### 8. Public routing logic must remain isolated from admin behavior

Locale routing is now part of platform behavior and must stay carefully scoped. The release-time routing expectations and locale-link review now live in `docs/deploy.md`.

Architectural risk:

- routing logic can accidentally affect admin flows or API endpoints if not isolated consistently
- server rewrite configuration can mask application-level fixes by terminating locale-prefixed requests before WordPress receives them
- proxy and site URL scheme drift can make otherwise-correct locale redirects point at the wrong protocol
- hardcoded internal links in themes or plugins can silently discard locale context even when the router itself is working correctly

## Key Code Signals Behind These Concerns

- `wp-content/plugins/uaix-core/uaix-core.php`
- `wp-content/plugins/uaix-core/includes/class-uai-core-plugin.php`
- `wp-content/plugins/uaix-bridge/uaix-bridge.php`
- `wp-content/plugins/uaix-bridge/includes/class-uai-api-bridge-plugin.php`
- `wp-content/plugins/uaix-modules/uaix-modules.php`
- `wp-content/plugins/uaix-modules/includes/class-uai-modules-plugin.php`
- `wp-content/plugins/ns12-locale-router/ns12-locale-router.php`
- `wp-content/plugins/ns12-locale-router/src/Plugin.php`
- `wp-content/plugins/ns12-locale-router/src/Router.php`

These files show the current mix of eager bootstrapping, incomplete dependency enforcement, inconsistent namespacing, and activation-time assumptions.

## Current Decision Directions

### Standardize plugin boot

- create one shared UAIX bootstrap pattern
- use lightweight main plugin files
- run preflight checks before full runtime construction

### Standardize naming and isolation

- move UAIX plugins to namespaced code
- reduce global symbols
- avoid duplicate class names across deploys

### Standardize dependencies

- define which plugins are standalone and which require `uaix-core`
- use WordPress dependency metadata where available
- make dependency failure produce a clear admin notice instead of a fatal path

### Standardize deployment

- follow `docs/deploy.md` as the canonical deployment workflow
- keep the packaging script under version control
- publish only validated ZIPs

### Standardize diagnostics

- define a minimum activation-debug procedure
- require environment logging in staging
- capture activation smoke-test results before publishing according to `docs/deploy.md`

## Recommended Next Steps

1. Refactor the legacy UAIX plugins toward a shared preflight-first bootstrap model.
2. Continue namespacing the legacy UAIX plugin family to reduce global symbol risk.
3. Add stronger dependency metadata and runtime guards where plugin order matters.
4. Keep `docs/deploy.md` plus the publish and smoke scripts as the only supported release path.
5. Preserve admin diagnostics, routing checks, and clean-install smoke tests as release gates.
6. Track future runtime work through `docs/roadmap.md` instead of re-opening completed launch-surface items here.

Why This File Exists

This is a memory-system evidence file from uaix.org. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is memory-system evidence. It records source history, archive transfer, intake disposition, or another piece of provenance that should be retrievable without becoming an unsupported public claim.

Structure

The file is structured around these visible headings: UAIX Runtime Architecture Notes; Status; How To Use This Document; Purpose; Current Runtime Shape; Current Architectural Strengths; Architectural Concerns; 1. Eager bootstrap on plugin load. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

• Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
• LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
• Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
• Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

• Source overview
• Site file index
• Site report index
• UAI system index
• Source provenance
• Site directory
• Organization reports

Provenance And History

• Current observation: 2026-06-22T01:56:21.9510185Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-1107 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "UAIX Runtime Architecture Notes",
    "source_site":  "uaix.org",
    "source_url":  "https://uaix.org/",
    "canonical_url":  "https://aiwikis.org/uaix/files/raw-system-archives-uaix-internal-memory-reorg-2026-05-01-docs-runtime-a-e51b653c/",
    "source_reference":  "raw/system-archives/uaix/internal-memory-reorg/2026-05-01/docs/runtime-architecture.md",
    "file_type":  "md",
    "content_category":  "memory-file",
    "content_hash":  "sha256:e51b653cbd4b47691bd2d49ff4e1c0ef9faae70e5f67cb56f37a081a84fc41da",
    "last_fetched":  "2026-06-22T01:56:21.9510185Z",
    "last_changed":  "2026-04-24T01:38:24.9048199Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-1107",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-06-22T01:56:21.9510185Z"
}