Design Principles

A few decisions run through every layer of Galactic Core: what the public API is allowed to do, what an order sets in motion, where prices are decided, how tenants are separated, and what a read is permitted to cost.

​

The public surface is storefront-only

Every endpoint serves a shopper on a storefront, or a headless backend acting on that shopper’s behalf: browsing the catalog, searching, reading reviews, managing a cart, placing an order, paying, signing in. Store management does not appear on the public API — creating products, moderating reviews, issuing refunds, and changing configuration all happen in the merchant’s admin, against the database directly. That boundary is what makes a publishable key safe to embed in a browser. There is no administrative surface behind it to abuse, so the read-only guarantee is real rather than a matter of trust. It also keeps the surface small and cacheable, which the rest of the architecture depends on.

​

An order carries its consequences

Creating an order is not inserting a row. A paid order reduces stock, redeems any gift cards, posts double-entry accounting journal entries, and updates the customer’s lifetime metrics — in one transaction, triggered by a single API call. If part of that post-processing fails, the order is not silently marked complete: the failure is recorded on the order and returned to you, so you always know the true state. Because one call sets all of that in motion, writes are transactional and idempotent — a retry never produces a second order, and no part of the sequence can be half-applied. The Request Lifecycle shows exactly what runs when an order is created.

​

The platform owns the money math

Totals, discounts, and gift-card redemption are computed on the server, in the database, at write time. The API never trusts a client-sent price; it recalculates and rejects a mismatch. This is what lets an order be placed from a browser-adjacent backend without turning pricing into an attack surface — the authority for what a customer pays lives on the server, not in the request.

​

Isolation matched to the tenant

Isolation comes at two levels, and which applies depends on the tenant rather than on the code. On the shared platform — where a single merchant runs — every row is scoped to a store and enforced by the database’s row-level security. A tenant that needs more than a logical boundary — a marketplace operator, an enterprise client, a data-residency requirement — runs on a dedicated deployment, a separate database and API layer that no other tenant touches, which adds a reliability boundary on top of the security one: its load or incident cannot reach another tenant, because it shares no database or compute. Data Model & Multi-tenancy covers how both are enforced.

​

The cost of a read

Reads are the bulk of commerce traffic, so the platform is built so they rarely reach the database. They are cacheable and served from the edge; writes are the minority and the only traffic that must reach the primary. The caching pipeline, the purpose-built read views, and the fixed budget an authenticated read is held to all follow from that. The Caching Pipeline is where they play out.