# WRNexusJS 0.3 Architecture

## Design goals

WRNexusJS 0.3 is an additive architecture release focused on one invariant:

> A valid `.wrn` file must be parsed, diagnosed, compiled, rendered, hydrated,
> formatted, migrated, and edited from one shared language model.

The release keeps existing application contracts while adding extension seams for
full-stack data, plugins, partial hydration, observability, tenancy, advanced
routing, build analysis, jobs, and deployment adapters.

## Package boundaries

### Language and compilation

- `@wrnexus/syntax`: canonical tokens, AST, source positions, diagnostics, and spec
- `@wrnexus/compiler`: SSR/client code generation and deprecated parser re-exports
- `@wrnexus/csr`: browser navigation and fine-grained reactive hydration
- `@wrnexus/reactive`: framework-independent signals, computed values, effects, and batching

### Request and application runtime

- `@wrnexus/core`: context, middleware, security, typed endpoints, loaders/actions,
  tenant APIs, tracing, feature flags, and performance budgets
- `@wrnexus/router`: route discovery, matching, groups, optional/catch-all params,
  conflicts, and typed URL generation
- `@wrnexus/ssr`: document rendering plus string, promise, and async-iterable streaming
- `@wrnexus/dev-server`: shared dev/production request runtime and portable fetch handlers

### Extension and operations

- `@wrnexus/plugin`: deterministic plugin ordering and lifecycle hooks
- `@wrnexus/dev-toolbar`: source-linked page diagnostics
- `@wrnexus/cli`: build, doctor, config explanation, analyzer, migrations, and generators
- `@wrnexus/queue`: jobs, priority, concurrency, idempotency, cancellation, cron helpers,
  and workflows
- `@wrnexus/pubsub`: realtime scaling adapters

## Compatibility layers

The compiler's former parser, tokenizer, and AST modules re-export the canonical
syntax package. No existing public compiler import must be changed immediately.

The client runtime continues to support legacy hydration scopes, `data-for`, and
`{#each}` output. New hydration metadata is additive:

```html
<div data-wrn-hydration="stable-id" data-wrn-hydrate="visible" data-wrn-runtime="universal"></div>
```

The updater creates a full application-source backup before source normalization.
Its migration report lists every changed file.

## Request flow

```text
Request
  -> security/CORS/body-size boundary
  -> optional tracing middleware
  -> optional tenant middleware
  -> application middleware
  -> route matcher
  -> loader/API/page/realtime dispatch
  -> SSR document assembly
  -> response cookies/security/compression
```

Development and production use the same `createHandlers` runtime. Production also
exposes `createProductionHandlers`, a portable web-standard fetch seam used by Bun,
Node, and future edge/serverless adapters.

## Reactive update flow

```text
signal write
  -> dependency invalidation
  -> microtask batch
  -> computed values refresh on demand
  -> only subscribed renderers/effects run
  -> DOM bindings update
```

Renderer scheduling is coalesced so repeated writes in one task do not cause a full
component rerender for each write.

## Plugin lifecycle

Plugins are ordered deterministically with `enforce`, `before`, and `after`:

```text
configure
configResolved
buildStart / configureServer
transformAst
plugin diagnostics
transformCode
buildEnd
```

Duplicate names and ordering cycles fail with stable plugin errors. Plugin hooks
are optional and the absence of plugins has zero behavioral effect.

## Build outputs

A production build can emit:

- compiled route/component modules
- source maps when enabled
- route and asset measurements
- `dist/build-report.json`
- performance-budget violations
- generated production entry with security, observability, tenancy, storage,
  databases, realtime, mobile, PWA, and SEO configuration

Use:

```bash
wrnexus config . --explain
wrnexus build .
wrnexus analyze .
wrnexus doctor .
```

## Stability levels

- **Stable**: existing behavior, canonical syntax ownership, diagnostics, router
  compatibility, typed core primitives, build reports, migration safety
- **Additive stable API**: plugin contracts, tracing, tenancy, loaders/actions,
  endpoint definitions, job definitions
- **Experimental runtime behavior**: server components, broader streaming boundaries,
  custom adapter implementations, and plugin transforms can be gated in config

Experimental flags make feature adoption explicit without forcing existing apps to
change their runtime behavior.