> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How Vulpy Commerce is structured

> The Vulpy Commerce stack: Fox as the driver, plus a Next.js and Payload storefront, Medusa v2 commerce engine, and consent-gated self-hosted Matomo.

Vulpy Commerce splits into a driver and an engine. Fox drives (a Hermes agent container running the Vulpy WebUI and missions system). The engine is a familiar Medusa plus Next.js plus Payload stack, with self-hosted Matomo for behavioral analytics on live. This page shows how those pieces fit together.

<Tip>
  **Ask Fox for the live picture.** These diagrams describe the shape; Fox knows what's actually running in your checkout right now.

  Try prompts like:

  * "Which containers are running right now?"
  * "Show me where the storefront talks to Medusa."
  * "Where is Payload media stored?"
</Tip>

## The stack

| Layer              | What                                                                                                  | Runs as                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Fox (Hermes agent) | Your AI operator: WebUI, missions, environment context, environment actions, catalog and content work | `docker-compose.hermes.yml` (hermes, gitea, searxng) |
| Storefront         | Next.js `@apps/storefront` with NextMerce UI and Payload CMS                                          | Host process on port 3000                            |
| Commerce engine    | Medusa v2 backend, PostgreSQL, Redis                                                                  | Host process on port 9000; DB via Docker             |
| Analytics          | Self-hosted Matomo, consent-gated                                                                     | Production only, on `MATOMO_DOMAIN`                  |

The storefront and Medusa run as Node processes on the host by default. Postgres and Redis run in Docker. Fox is a separate container. On a VPS, Caddy sits in front of everything and terminates TLS.

## The Vulpy WebUI

The WebUI is your Fox control surface. It ships as six built-in experience features under `extensions/hermes-webui/features/`, all bundled as one manifest entry:

* `vulpy-commerce-core`, the bootstrap registry and event bus loaded first
* `vulpy-commerce-welcome`, the guided first-boot flow
* `vulpy-commerce-side-panel`, the right drawer with tabbed iframes into admin surfaces
* `vulpy-commerce-env-context`, the live shop state banner
* `vulpy-commerce-env-actions`, the approved dev-only action bar
* `vulpy-commerce-profile-switcher`, for switching shop profiles

## Where Fox lives in the tree

Fox's workspace at `/app/workspace` inside the Hermes container is a bind mount of your host checkout. Files Fox writes are immediately live on the host filesystem: no `git pull` needed on the host after Fox edits. Only `/data` (host `.data/hermes/`) and `/app/workspace` survive container recreate or rebuild.

<Note>
  Fox has no Docker socket and cannot create environments. The `pnpm vulpy env add|up|down|golive` commands refuse inside the container. Staging and live remain human-only operations.
</Note>

<CardGroup cols={2}>
  <Card title="Meet Fox" icon="robot" href="/fox/overview">
    What Fox is and what it does inside your shop.
  </Card>

  <Card title="The Vulpy WebUI" icon="window-maximize" href="/fox/webui">
    A tour of the six built-in experience features.
  </Card>
</CardGroup>