# X and XApps: Drop the Folder and It Runs The simplest statement of my software philosophy is this: **drop a folder somewhere and it runs**. The folder might live on an inexpensive shared server, a dedicated host, a local computer, a desktop application, or inside another tool. The host could change. The language could change. The durable parts of the application—its content, configuration, identity, transformations, and behavioral contracts—should remain understandable and portable. That principle is the connective tissue between [[projects/Shazam - A Portable Perl Capability Library|Shazam]], X, XApps, [[projects/AutoSites - Folder-Native Publishing and Distribution|AutoSites]], and [[projects/XDO - Executable Markdown and Portable Workflows|XDO]]. These were not isolated experiments. They were successive attempts to make useful behavior survive changes in servers, languages, frameworks, and product surfaces. The objective was **maximum utilization with minimum dependency**: think through a capability once, give it a stable interface, and make it available wherever the work needed to run. --- ## What this architecture would be called now - **Drop a self-contained folder into a host and run it.** Modern translation: a portable application bundle, zero-install deployment, and [[wiki/Convention over Configuration|convention over configuration]]. - **The folder contains code, data, configuration, and resources.** Modern translation: a self-describing deployment unit and [[wiki/Local-First Software|local-first package]]. - **Small loaders discover paths and initialize the environment.** Modern translation: a bootstrap layer, composition root, and runtime discovery. - **X exposes the same named functions in PHP, browser JavaScript, Node, Perl, and planned Python.** Modern translation: [[wiki/Polyglot API|polyglot API]] and [[wiki/Cross-Runtime Capability Parity|cross-runtime parity]]. - **Shared names are backed by input, output, and error rules.** Modern translation: [[wiki/Tool Contract|typed tool contract]], [[wiki/Portable Contract|portable contract]], and schema-governed capability. - **Shared fixtures prove that ports behave alike.** Modern translation: consumer-driven contract testing and [[wiki/Conformance Testing|conformance testing]]. - **Pure transformations are separated from files, HTTP, databases, and editors.** Modern translation: [[wiki/Ports and Adapters|ports-and-adapters architecture]] and a functional core with an imperative shell. - **X is the capability layer; XApps binds it to a host.** Modern translation: a platform core plus [[wiki/Host Adapter|host adapters]]. - **Capabilities are resolved by name.** Modern translation: [[wiki/Capability Registry|capability registry]], [[wiki/Dynamic Dispatch|dynamic dispatch]], and [[wiki/Capability Discovery|capability discovery]]. - **The same folder structure survives different server and desktop hosts.** Modern translation: substrate portability and environment-independent packaging. - **Minimal dependency keeps the archive repairable.** Modern translation: dependency minimization, technological sovereignty, and long-lived software design. - **Generated combined distributions coexist with modular source.** Modern translation: source/distribution separation and [[wiki/Generated Packaging|build artifacts]]. - **A controlled X surface is exposed to DoLang.** Modern analogy: an application tool layer comparable to an [[wiki/Model Context Protocol|MCP]] server's allowlisted tools and resources. - **AI-generated implementations must satisfy the same fixtures.** Modern translation: schema-constrained generation, [[wiki/Structured Outputs|structured outputs]], and deterministic verification. The compact translation is: **X/XApps was a polyglot capability platform organized around portable contracts, generated packages, host adapters, and self-contained deployment units.** It resembles the architectural layer now needed between AI-generated code and reliable execution: named tools, explicit schemas, narrow permissions, shared tests, and host-specific adapters. See [[wiki/Modern Technical Translation Map|Modern Technical Translation Map]] for the shared vocabulary. ## The governing rule The ideal deployment unit was not an installation ceremony. It was a directory with a predictable internal structure. ```text application-folder/ ├── loader ├── settings ├── libraries ├── content ├── resources └── data ``` Place the directory into an appropriate host, point the small loader at it, and the application should discover the rest. A domain could map to a folder. A folder could become an account. Files and subdirectories could become routes. Markdown could become a page. A compact settings file could alter behavior without changing the application. This was not containerization in the modern sense, and it should not be described anachronistically as such. It was a closely related portability instinct implemented with the tools available to me: explicit paths, small loaders, plain files, conventional directories, self-contained libraries, and as little environmental coupling as possible. ## One capability, many runtimes The larger X objective was to align useful functions across languages and hosts: ```text X behavioral contract | +----------------+----------------+ | | | browser JS Node PHP | | | +----------------+----------------+ | the same result ``` Perl belongs in this lineage through the earlier [[projects/Shazam - A Portable Perl Capability Library|Shazam]] and [[wiki/KeyDB|KeyDB]] systems. Python was part of the broader portability direction but is not present as a comparably complete historical port in the recovered `_x` tree. The modern continuation should include both Python and Perl, but it should do so through explicit contracts and conformance tests rather than by claiming parity that the surviving archive does not demonstrate. The practical rule is straightforward: > If a function has the same name and contract in several runtimes, the same normalized input should produce the same normalized output. That turns language ports into implementations of one capability rather than unrelated rewrites. It also means a parser, slug generator, text normalizer, quote extractor, or path function can behave consistently in a web server, an Obsidian plugin, a command-line tool, or a local editor. ## What survives in the archaeology The recovered historical `_x` tree makes the intention visible in its structure: - `xphp` contains the largest implementation, including more than one hundred top-level `x_*` PHP functions in the principal library. - `xjs` separates browser-oriented capabilities into categories such as strings, data, files, mathematics, networking, and WebGL. - `xnode` mirrors several of those categories while adding host-specific facilities such as filesystem access, databases, authentication, and server initialization. - shared datasets include reserved slugs, public suffix information, valid top-level domains, common subdomains, and moderation-related word lists. - XApps loaders establish library paths, configure the host, and optionally load debugging or XDO support from a relocatable application directory. Several files also preserve PHP-shaped functions beside JavaScript implementations. Those mixed working files are untidy, but archaeologically valuable: they expose the act of translating a capability between runtimes while trying to keep the algorithms aligned. The implementation was uneven. PHP is substantially more complete than the JavaScript surfaces, and some JavaScript files are unmistakably experimental. That is a maturity fact, not a failure of the architecture. The structure demonstrates the intended separation between a shared capability system and host-specific adapters. ## Minimal dependency was a durability strategy Low dependency is sometimes mistaken for aesthetic austerity. My reason was operational: dependencies become owners of your future. A system built from plain text, explicit conventions, small functions, and replaceable adapters can outlive a framework, a package manager, a database, a vendor, or a particular server configuration. It can be inspected when the original tooling is gone. It can be repaired with ordinary tools. It can be moved without negotiating with an abandoned stack. The recurring design choices follow from that: - files and folders remain the canonical, inspectable record; - databases and indexes may accelerate reading but should be reconstructable; - content is stored separately from presentation; - host-specific behavior lives at an adapter boundary; - small loaders replace elaborate installation requirements; - capability names and outputs remain stable across implementations; - generated artifacts never become the only surviving truth. This is the same engineering disposition described in [[projects/Ten Years Building a Symbolic Language Engine|Ten Years Building a Symbolic Language Engine]]: perform expensive thinking once, create a representation that makes later questions cheap, and preserve that representation in a form that remains usable. ## XApps as the deployment expression X was the function and data layer. XApps was the application-hosting expression of the same philosophy. A surviving XApps loader can be given a different root path at initialization. From that root it derives the library and open-library paths, establishes include paths, sets runtime options, and loads the X core. Optional features such as debugging and XDO can be enabled without changing the application code. That design is small, but consequential. It means the application does not need to know where it was installed. The loader resolves the environment; the application consumes the capabilities. Copies of this arrangement survive in server projects and portable desktop experiments. The same recognizable application package appears under web roots, BrowserBox work, PHP Desktop projects, and other local packaging tests. These copies do not establish perfect write-once execution across every host, but they do establish that portability was being tested as a deployment property rather than described only as an aspiration. ## The modern form The clean continuation is not a new monolith called X. It is a small protocol with four layers: 1. **X Contracts** define canonical names, inputs, outputs, normalization, errors, and fixtures. 2. **X Core** implements deterministic capabilities in JavaScript, PHP, Python, and Perl. 3. **X Host Kits** expose controlled environment features for browsers, Node, PHP servers, editors, filesystems, and databases. 4. **DO Language** composes registered X capabilities from readable documents without granting arbitrary execution. This structure retains the old freedom while adding what the historical experiments lacked: automated conformance, explicit security boundaries, versioned contracts, and generated compatibility documentation. The result should be recognizable in every environment: ```text portable content + X contracts + host adapter = runnable system ``` An Obsidian plugin should not invent its own quote parser. A PHP site should not invent a different slug algorithm. A Node generator should not silently normalize text differently from a Perl migration tool. Each host supplies the things only that host can supply; the reusable logic remains aligned. ## Why this matters now The present software culture has made portable components common while often making whole systems less portable. A project may have thousands of dependencies, opaque build requirements, remote services, and framework-specific assumptions before it has represented its core idea clearly. Maximum utilization also applies to content. In AutoSites, one sentence marked while writing can become a quote record, landing page, poster, stable link, search object, and RSS item. A parameterized feed can then select, reshape, randomize, attach media to, and probabilistically deliver that item to an external automation heartbeat. The writer maintains one Markdown source while the system produces many channel-appropriate surfaces. That is the X philosophy operating on meaning rather than only on code: perform the semantic work once, preserve it in a portable form, and let reusable capabilities realize every appropriate use of it. X begins at the other end: > What is the smallest durable representation of this capability, and how many environments can use it without surrendering control of it? That question is especially relevant to AI-assisted development. A model can generate a one-off implementation quickly. Without shared contracts, fixtures, provenance, and host boundaries, the next generated implementation may disagree with the first. X provides the constraint system that turns rapid generation into interoperable engineering. The promise remains the same as it was at the beginning: put the complete thought into the folder, keep its dependencies few and visible, and let the host bring it to life. --- ## Evidence status | Claim | Basis | Status | |---|---|---| | The historical system was organized around XApps loaders and relocatable library roots | Surviving `x_loader.php` implementations and repeated XApps directory structures | Artifact-visible | | Browser JavaScript, Node, and PHP were being developed as related X surfaces | Recovered `_x/xjs`, `_x/xnode`, and `_x/xphp` trees with overlapping categories and functions | Artifact-visible | | PHP was the most complete recovered `_x` implementation | Comparative inventory of the surviving runtime trees | Artifact-visible | | Perl is an ancestor of X rather than an equally complete port inside the recovered `_x` tree | Shazam, KeyDB, and direct function-lineage comparison | Artifact-visible reconstruction | | Python and renewed Perl parity belong in the modern continuation | Present architectural decision | Proposed reuse | | “Drop a folder somewhere and it runs” was the governing philosophy | Bryant McGill's account, supported by the repeated loader, folder, domain-account, and portable-host designs | Owner account with artifact support | ## Related projects - [[projects/Shazam - A Portable Perl Capability Library|Shazam: A Portable Perl Capability Library]] - [[projects/AutoSites - Folder-Native Publishing and Distribution|AutoSites: Folder-Native Publishing and Distribution]] - [[projects/XDO - Executable Markdown and Portable Workflows|XDO: Executable Markdown and Portable Workflows]] - [[projects/Ten Years Building a Symbolic Language Engine|Ten Years Building a Symbolic Language Engine]] - [[wiki/KeyDB|KeyDB]]