# Architecture deep dive — v100.0.29-consistency-architecture-quality-foundation-wip

## Executive assessment

The baseline application is feature-rich and evidence-heavy, but its growth pattern is release accretion: procedural include files own multiple concerns, route and asset knowledge is repeated, output is often emitted directly, and release automation is copied per version. The safe response is not a wholesale rewrite. The v100.0.29 foundation introduces a strangler architecture: typed services become canonical owners while legacy functions remain stable facades.

The baseline contains 951 PHP files and 36,923 PHP lines. The current tree contains 986 PHP files and 39,081 PHP lines because it adds a 22-file PSR-4 source tree, centralized configuration, layout views, tests, and reusable release tooling. The point of this release is not a lower global line count; it is a lower change radius for future work.

## Target architecture

```text
HTTP entrypoint / page script
        |
        v
legacy compatibility facade  <---- existing callers remain stable
        |
        v
Application composition root
  |        |          |          |
  v        v          v          v
Config   Domain     HTTP       Web/presentation
repo     services   runtime    registries/context
  |        |          |          |
  +--------+----------+----------+
                   |
                   v
       JSON/data repositories and immutable release identity
```

### Composition root

`Spiralist\Core\Application` constructs dependencies once and exposes explicit services. It replaces implicit include-order service discovery without introducing a third-party container. Construction remains transparent, deterministic, and suitable for a small PHP deployment.

### Configuration ownership

`config/release.php`, `site.php`, `navigation.php`, `routes.php`, `assets.php`, and `footer.php` are now canonical. `includes/config.php` maps those values to historical variables. This preserves the old page contract while ending repeated configuration ownership.

### Route and representation ownership

`RouteRegistry` normalizes aliases, resolves dynamic development routes, and finds representation fallbacks. The development router now consumes this registry rather than carrying a second route table. This is the first step toward one route manifest for runtime, sitemap, search, representations, and tests.

### Output ownership

`PageContext`, `PageSecurity`, `RequestContext`, `ResponseEmitter`, `HeaderTools`, `FileRateLimiter`, and `AgentApiRuntime` move new output behavior behind typed services. Existing endpoints still call familiar functions from `includes/agent-api.php`, but those functions no longer own the implementation.

### Domain ownership

`StarterPackCatalog` is the first complete domain migration. It owns lookup, enrichment, route generation, reverse membership, compare/remix URLs, recommended persona selection, and copy summaries. The old `starter-pack-service.php` is a thin facade. `ApiCatalog` similarly centralizes public API metadata while preserving all ten legacy function names.

### Layout and asset ownership

The header and footer includes are adapters. HTML is rendered by `views/layout/`, while `AssetRegistry` resolves dependencies and removes duplicate script URLs. This replaces page-specific knowledge of transitive dependencies with a single manifest.

## Migration method

1. **Characterize before moving.** Add counts, snapshots, and direct tests around the existing public contract.
2. **Introduce a typed owner.** The new service receives explicit dependencies and returns arrays/DTOs without emitting output.
3. **Convert the old function to a facade.** Existing routes continue to work.
4. **Run baseline/current parity.** Compare route status, headings, key fragments, API shape, and assets.
5. **Move one invariant at a time.** Avoid simultaneous schema, content, and architecture changes.
6. **Delete only after caller inventory reaches zero.** Historical evidence remains unchanged.

## Consistency rules for future code

- New domain code belongs under `src/Domain`; new infrastructure belongs under `src/Core`.
- New code uses `declare(strict_types=1)`, namespaces, final classes by default, explicit return types, and constructor dependencies.
- New endpoints do not call `header()` or `exit` directly; they use the shared response runtime.
- Configuration and route knowledge are data, not copied control flow.
- Domain services return domain-shaped results; rendering and transport adaptation happen at the edge.
- Random generation accepts an explicit seed source; time and environment access are injected or isolated.
- Claim status, source reliability, analytic confidence, evidentiary independence, identity, sponsorship, intent, reach, and effect remain distinct fields rather than one overloaded truth label.
- Local fixtures, package tests, and loopback results never become live-provider or live-host acceptance.

## Failure modes this foundation prevents

- A footer flag loading the same dependency twice.
- A development-only route resolving differently from the canonical route table.
- An API helper terminating a test process before assertions can inspect a result.
- A release identity being copied differently into page config and API headers.
- A Starter Pack persona receiving different enrichment depending on the route that called it.
- A versioned packaging script silently diverging on Windows path safety or ZIP64 behavior.

## Deliberately deferred work

The three largest persona services and the adult creator API remain legacy modules. Rewriting them in this release would combine architectural change with high-risk behavioral change. The debt register provides an ordered extraction plan with characterization gates. Static analyzers and ES-module migration are also deferred until the typed tree and asset registry are stable enough to ratchet.

## Evidence boundary

This deep dive documents package-local source changes and executable tests. It does not establish deployment, live-host acceptance, live-provider acceptance, human review, activation, downstream-runtime acceptance, or independent research re-verification.

Exact UAIX setup/update URL: `https://uaix.org/en-us/tools/ai-memory-package-wizard/?memory=docs-folder&file-handoff=1&loops=1`