Skip to content
OxyHQPublic

About

Marketplace by Oxy: shops and second hand, side by side

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

1,335 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

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

Expo SDK 58 React Native 0.88 TypeScript Bun Express PostgreSQL


πŸ›’ Three apps, one API

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.

πŸ”‘ Identity comes from Oxy

There is no Mercaria account. Sign in is the device first Oxy session, handled end to end by @oxy.so/services on the client and @oxy.so/core on the server.

No local token providers, no auth interceptors, no hand rolled bearer parsing. See the Oxy platform repo for how the session itself works.

Packages

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/ui is never built to dist. Apps resolve it through Metro watchFolders, a Tailwind preset and a tsconfig path alias, which is what keeps formatMoney, PriceDisplay and FxContext from being copied into three apps.

Quick start

bun install
cp packages/backend/.env.example packages/backend/.env
bun run dev:backend
bun run dev:frontend

Bun 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 --noEmit

bun 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 postgres

The 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.

Conventions

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.


Part of the Oxy ecosystem

About

Marketplace by Oxy: shops and second hand, side by side

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages