Architecture

Mika is a set of commerce contracts and copyable Astro surfaces around a host-owned storefront.

The main layers are:

Layer	Typical file	Responsibility
Host content and routes	src/pages/products/[slug].astro or equivalent	Load product content, choose page layout, and decide public URLs.
Copied storefront UI	src/components/ProductPurchase.astro, src/pages/cart.astro	Render forms and request-bound pages after the host copies template files.
Astro Actions	src/actions/index.ts and src/actions/mika.ts	Accept browser form posts and run Mika operations through Astro’s action runtime.
Request helper	createMika(Astro) from @bnomei/emdash-mika/astro	Resolve cart, wishlist, account, checkout, catalog, and webhook operations for the current request.
Host API	src/lib/mika-api.ts or a native plugin entrypoint	Implement Mika’s API with host repositories, provider registry, notifications, IDs, hashing, defaults, and config.
EmDash plugin	mikaPlugin({ api }) in astro.config.mjs	Register Mika storage, plugin JSON routes, and scheduled maintenance in EmDash.
Provider adapters	server-only host modules plus optional Mika adapters	Translate provider SDKs such as Stripe into Mika’s provider contract.
Admin actions	EmDash admin plus @bnomei/emdash-mika/admin	Expose trusted Mika operations as admin action manifests and runner calls.
Agent metadata	@bnomei/emdash-mika/agent and copied metadata endpoints	Describe capabilities and boundaries without exposing protected tools by default.

The host app composes these layers and remains responsible for final policy.

Descriptor Vs Runtime Plugin

mikaPlugin() is the EmDash descriptor factory used from astro.config.mjs. It declares Mika’s plugin ID, native entrypoint, capabilities, storage config, descriptor options, and maintenance schedule toggle.

createPlugin() is the runtime entrypoint EmDash activates. It sets the default Mika API overrides used by request helpers, builds the live MikaApi, registers plugin JSON routes, registers storage, and schedules the mika_maintenance cron task.

For simple setups, passing mikaPlugin({ api }) is enough. For host APIs that contain functions or other values that should not be serialized through descriptor options, use a native entrypoint such as src/plugins/mika-template-plugin.ts and call createPlugin({ api }) there.

How The Layers Talk

mikaPlugin({ api }), createMikaActions(), and createMika(Astro) should all resolve the same host API unless a test or fixture intentionally passes an override. That is the core pattern: plugin routes, forms, and pages share one operation implementation instead of each page inventing its own cart or checkout logic.

The copied template files demonstrate that pattern, but they do not become package-owned routes after copy. If a host changes /cart to /bag, or adds an account gate before checkout, that is normal host code.

Related Tasks

• Host-Owned Boundaries is the canonical boundary page.
• Integration File Map maps each layer to concrete files.
• First Integration Checklist turns the architecture into a first host wiring pass.

External References

• Astro Actions for the action runtime used by src/actions/index.ts.
• EmDash plugin guide for the plugin extension model Mika registers into.

Source Anchors

• ⓟ ../emdash-mika/README.md
• ⓟ ../emdash-mika/src/plugin.ts
• ⓟ ../emdash-mika/src/api/runtime-api.ts
• ⓟ ../emdash-mika/src/astro-actions.ts
• ⓐ ../emdash-mika/src/templates/astro/README.md
• ⓣ ../emdash-mika-template/astro.config.mjs
• ⓣ ../emdash-mika-template/src/lib/mika-api.ts
• ⓣ ../emdash-mika-template/src/plugins/mika-template-plugin.ts