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, { api }) 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 and a native plugin entrypoint	Implement Mika’s API with host repositories, provider registry, notifications, IDs, hashing, defaults, and config.
EmDash plugin	mikaPlugin({ entrypoint }) 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 host runtime entrypoint EmDash activates. That function should call createMikaPlugin({ api }) from @bnomei/emdash-mika/server to build the live MikaApi, register plugin JSON routes, register storage, and schedule the mika_maintenance cron task.

Live APIs contain functions and provider objects, so pass them through a native entrypoint such as src/plugins/mika-template-plugin.ts; do not put them in mikaPlugin() descriptor options.

How The Layers Talk

createMikaPlugin({ api }), createMikaActions({ api }), and createMika(Astro, { api }) should all receive 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/server.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