---
title: "Architecture"
description: "Applications, packages, origins, request flow, and persistence boundaries in the Nyxel monorepo."
canonical_url: "https://nyxel.dev/docs/project-structure"
markdown_url: "https://nyxel.dev/docs/project-structure.md"
---

# Architecture
URL: /docs/project-structure
LLM index: /llms.txt
Description: Applications, packages, origins, request flow, and persistence boundaries in the Nyxel monorepo.

# Architecture

Nyxel separates deployable applications from reusable packages. The storefront and editor run on different origins in development because they have different security, build, and deployment responsibilities.

```text
nyxel/
├── apps/
│   ├── storefront/   Astro storefront and reference theme
│   ├── editor/       Standalone Vite/Svelte editor host
│   ├── connect/      Partial Shopify-facing project and release host
│   └── site/         Documentation and blog
└── packages/
    ├── component/    Typed component DSL and manifests
    ├── runtime/      Templates, sources, themes, Yjs, actions
    ├── astro/        Astro composer, integration, middleware, dev APIs
    ├── svelte/       Svelte adapter and presentation helpers
    ├── react/        React adapter
    ├── editor/       Portable editor UI library
    ├── connect/      Framework-neutral project, provider, and release contracts
    ├── sdk/          Static extraction and tooling compatibility exports
    └── cli/          nyxel command-line interface
```

## Application boundaries

`apps/storefront` owns public routes, Shopify request context, theme files, component source, template JSON, and development-only editor endpoints. It contains no editor panels or selection overlays.

`apps/editor` is a thin host for `@nyxel/editor`. It points at a storefront origin, fetches manifests and documents, and provides persistence and rendering callbacks. The editor library never imports the storefront’s components or virtual modules.

`apps/connect` is a separate SvelteKit host for the partial production control plane. It verifies Shopify sessions, stores Nyxel-owned project and release state, coordinates GitHub and Vercel through server-only clients, and issues bounded editor capabilities. It is not part of the normal local storefront/editor supervisor.

`apps/site` publishes the documentation and blog. It does not share the storefront runtime or act as a deployment host for the editor.

## Development origins

The standard local ports are:

| Service    | Origin                  | Responsibility                                                      |
| ---------- | ----------------------- | ------------------------------------------------------------------- |
| Storefront | `http://localhost:5273` | Routes, commerce, preview sessions, Canvas rendering, document APIs |
| Editor     | `http://localhost:5274` | Editing UI and local draft orchestration                            |
| Site       | `http://localhost:5280` | Documentation and blog                                              |
| Connect    | `http://localhost:5450` | Optional project, provider, and release control plane               |

The editor host can use another allocated port when an isolated worktree is running. Set `VITE_STOREFRONT_ORIGIN` to choose the storefront it controls.

## Request flow

Astro middleware builds one request-scoped context containing URL, locale, market, cookies, headers, Shopify client, cart identity, preview session, and route sources. Route loaders resolve the page template and commerce data. `@nyxel/astro` recursively composes nodes and dispatches each one to its renderer adapter.

The editor uses separate development calls for registry data, theme configuration, templates, presets, schema defaults, Canvas rendering, and Preview session snapshots. Those file-backed endpoints are not mounted in production.

In the partial Connect flow, the Shopify host creates a one-use handoff for one project. The editor exchanges it for a short-lived encrypted capability, then sends project-scoped document and render requests back through Connect. Provider credentials stay in the host. This shape is implemented, but the customer-owned provider authorization flow remains incomplete.

## Persistence boundaries

Template documents live under `apps/storefront/src/lib/templates/`. A `kind` field distinguishes route pages, shared groups, and saved sections. Theme settings use their own JSON document.

While editing, each persisted document has a Yjs representation. Header, page, footer, and theme stay separate so saving one boundary does not silently rewrite another. Save projects the selected documents back to validated JSON.

## Package consumption

Workspace builds use source exports where hot module replacement is valuable and built `dist` entries where Node or Astro requires them. Package verification checks the publish shape separately from the workspace shape. `@nyxel/connect` keeps the provider and release vocabulary independent from the SvelteKit host.

When a change crosses contracts, runtime, storefront, or editor boundaries, run the root handoff gate instead of relying on one application’s typecheck. [CLI](/docs/cli) lists the commands and their scopes.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).