Platform Architecture

App ownership

Betterstore is split into focused apps:

apps/marketing serves public marketing pages, legal pages, blog pages, inquiry pages, and documentation.
apps/platform serves authenticated merchant and admin workflows.
apps/api serves Hono OpenAPI-backed API routes for products, collections, customers, auth, checkout, client checkout, utilities, and internal integrations.

The former combined web app has been retired. New public work should go to marketing, and new authenticated dashboard work should go to platform.

Shared packages hold cross-app behavior:

Package	Responsibility
`@repo/database`	Drizzle schema, database clients, and generated types
`@repo/ui`	Shared design-system primitives and global styles
`@repo/config`	App, company, platform, marketing, and SEO configuration
`@repo/stripe`	Stripe integration helpers
`@repo/shipping`	Shipping profiles, locations, rates, and shipping logic
`@repo/inventory`	Inventory and reservation behavior
`@repo/discounts`	Discount validation and application logic
`@repo/fulfillment`	Fulfillment and payment-intent related flows
`@repo/emails`	Transactional email rendering and delivery helpers
`@repo/observability`	Logging and monitoring integrations

Most platform workflows follow this path:

UI or server component
  -> server action or feature module
  -> shared package or app database helper
  -> Drizzle query
  -> Neon/Postgres

Most public API workflows follow this path:

Hono route
  -> request validation
  -> handler
  -> service/query parser/domain package
  -> Drizzle query
  -> typed JSON response

When changing platform or API behavior:

Preserve route paths, response shapes, permissions, form validation, and payment semantics unless a behavior change is explicitly approved.
Prefer feature-by-feature migration and verification over large rewrites.
Add tests before refactoring checkout, discounts, shipping, fulfillment, inventory reservations, finance, or payout behavior.
Use shared design-system components for user-facing UI.