Mercaria is a buy and sell marketplace by Oxy.
New items from shops, secondhand items from people, one commerce backend behind all of it.
mercaria.co Β· dashboard.mercaria.co Β· pos.mercaria.co
|
The storefront, the merchant dashboard and the point of sale are three separate Expo apps built from one codebase, and they all talk to a single Express API. Selling is not a bolted on mode. A listing can be owned by a person or by a store, so a secondhand sale and a shop order run through the same catalogue, cart, checkout and refund paths. |
There is no Mercaria account. Sign in is the device first Oxy session, handled end to end by No local token providers, no auth interceptors, no hand rolled bearer parsing. See the Oxy platform repo for how the session itself works. |
| Package | Path | What it is |
|---|---|---|
@mercaria/frontend |
packages/frontend/ |
Expo storefront: browse, search, cart, checkout, orders |
@mercaria/dashboard |
packages/dashboard/ |
Expo merchant and store admin: catalogue, inventory, discounts, reports |
@mercaria/pos |
packages/pos/ |
Expo point of sale: in person sales through draft orders |
@mercaria/ui |
packages/ui/ |
Shared marketplace UI, consumed from source with no build step |
@mercaria/backend |
packages/backend/ |
Express API: TypeScript, PostgreSQL via Drizzle, Socket.IO |
@mercaria/shared-types |
packages/shared-types/ |
Domain DTOs every package imports |
Every app renders @oxy.so/bloom primitives with NativeWind on top of @mercaria/ui.
@mercaria/uiis never built todist. Apps resolve it through MetrowatchFolders, a Tailwind preset and a tsconfig path alias, which is what keepsformatMoney,PriceDisplayandFxContextfrom being copied into three apps.
bun install
cp packages/backend/.env.example packages/backend/.env
bun run dev:backend
bun run dev:frontendBun 1.4.3 and Node 22. Use bun and bunx, never npm, yarn or npx.
All the commands
bun run dev # every workspace at once
bun run dev:frontend # storefront
bun run dev:dashboard # merchant dashboard
bun run dev:pos # point of sale
bun run dev:backend # API
bun run build # shared-types, then backend, then frontend
bun run build:dashboard # Expo web export for the dashboard
bun run build:pos # Expo web export for the POS
bun run lint # Biome format+lint (every package) + Expo env-var ESLint
bun run lint:fix # Biome safe fixes and formatting
bun run format # Biome formatter only
bun run doctor:oxy # verify canonical Oxy package versions and scopes
bun run --filter @mercaria/backend test # Vitest
bun run --filter @mercaria/backend typecheck # tsc --noEmitbun run android, bun run ios and bun run web target the storefront. Each app pins its own Metro port, so all three can run side by side.
The API test suite needs a PostgreSQL server running. The repositories are tested against a real PostGIS database rather than a mock β a mocked query cannot tell whether the server would accept the SQL. Start one before test:
docker compose -f docker-compose.postgres.yml up -d postgresThe suite never writes to that database. TEST_DATABASE_URL (falling back to DATABASE_URL, and defaulting to the compose server) names a SERVER, on which the harness creates a throwaway, fully-migrated database per run and drops it afterwards.
Oxy ecosystem dependencies are checked read-only with bun run doctor:oxy.
The same check runs immediately after CI installs the frozen lockfile. See
docs/dependencies.md for the update policy.
What the API actually models
One backend serves the storefront, the dashboard and the point of sale. The admin surface lives under /admin/stores/:storeId/*.
| Concept | Notes |
|---|---|
Listing |
Owned by a user or a store, carries product variants |
Location and InventoryLevel |
Multi location inventory, race safe at the location grain |
Collection |
Manual and rule based, materialized onto the listing |
Discount |
Code and automatic, percentage, fixed and BOGO, with usage limits |
TaxRate |
Per jurisdiction |
Customer |
Includes point of sale walk ins, with running spend stats |
DraftOrder |
A point of sale sale, converted to a paid order idempotently |
Refund |
Partial and full, restocked per line at the right location |
| Reports | Sales summary, sales, top products |
Store access is a 16 permission matrix: owner has all of them, admin has all but store management, staff has the 9 operational ones.
Money: multi currency, provider neutral, FAIR preferred
The catalogue stores each price in its own native currency and never converts it on write. Every transacted amount on an order or refund is a DualMoney carrying two sides: shop, the seller's own accounting currency and the basis for reports and refunds, and presentment, what the buyer actually saw and paid. The order also snapshots the rate between them, naming the source that quoted it and the moment it was taken, so a later rate move can never alter a placed order.
No currency is a settlement invariant. FairCoin (FAIR, β) is the preferred default β the presentment currency a buyer gets when they have chosen none, and the display default β which is a product decision, not an architectural one. What a payment settles in is a property of the payment provider handling it and lives in the payment domain, so an order priced in euros completes with no FairCoin rate available at all.
Amounts are integer minor units with an enforced ceiling (MAX_MONEY_MINOR_UNITS), asserted everywhere an amount is formed: request validation, the pricing engine, currency conversion, refund proration and persistence.
The currency set is data driven from @mercaria/shared-types, so adding a code there propagates to the database schema, the pricing engine and the UI.
Abuse reports go to CrowdSource
Mercaria does not run a moderation panel. Abuse reports are committed locally with a durable outbox row in the same transaction, then delivered to CrowdSource, which decides them with a randomly drawn jury and returns signed decisions over a webhook.
CrowdSource owns cases and decisions, Oxy Trust owns reputation, and Mercaria only ever enforces against its own catalogue: restricting a listing, holding an order, or sending a listing back to draft for the seller to fix. Enforcement defaults to observe, which computes and records the identical plan without changing anything.
Built on @oxy.so/crowdsource and @oxy.so/crowdsource-express.
Deploy
Everything ships from GitHub Actions in .github/workflows/:
| Workflow | Target |
|---|---|
ci.yml |
Lint, tests, API build and app builds on every push and pull request |
deploy-aws.yml |
API to AWS ECS Fargate on linux/arm64 |
deploy-cloudflare.yml |
Storefront to a Cloudflare Worker serving static assets |
deploy-dashboard.yml |
Dashboard Worker |
deploy-pos.yml |
Point of sale Worker |
The web apps are Workers with static assets rather than Pages, so only the custom domain is ever reachable.
TypeScript first, with no as any, no @ts-ignore and no non null assertions. Styling is NativeWind classes rather than inline styles. State is Zustand, data fetching is TanStack Query, routing is expo-router. Backend auth is @oxy.so/core/server middleware and is never hand rolled.
Longer form docs live in docs/, the full working agreement in AGENTS.md, and setup details in CONTRIBUTING.md.