# nextshop

**Repository Path**: Kuaima-tech/nextshop

## Basic Information

- **Project Name**: nextshop
- **Description**: nextshop
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NextShop

NextShop is a Shopify-like cross-border commerce SaaS built with Next.js, TypeScript, Prisma, MySQL, Tailwind CSS, and shadcn/ui.

The current codebase keeps the original multi-tenant foundation but moves the product direction from food ordering to SaaS ecommerce: platform operations, merchant organization, store admin, storefront, products, markets, checkout, payments, orders, fulfillment, APIs, webhooks, analytics, exports, and release gates.

## Main Surfaces

- Platform: `/platform`
- Merchant: `/merchant`
- Store admin: `/admin`
- Storefront: `/store/[storeHandle]/[locale]`
- Admin API: `/api/v1/admin/*`
- Storefront API: `/api/v1/storefront/*`
- Platform API: `/api/v1/platform/*`
- System API: `/api/v1/system/*`

## Setup

```bash
npm install
npx prisma generate
npm run dev
```

The local dev server defaults to port `3300`.

## Required Environment

```env
DATABASE_URL="mysql://root:password@localhost:3306/nextshop"
JWT_SECRET="replace-with-a-long-secret"
APP_URL="http://localhost:3300"

ENABLE_SAAS_V1="true"
ENABLE_MARKETS="true"
ENABLE_EXPORTS="true"

ENABLE_STRIPE_PAYMENTS="false"
STRIPE_SECRET_KEY=""
STRIPE_WEBHOOK_SECRET=""

PAYPAL_ENV="sandbox"
PAYPAL_CLIENT_ID=""
PAYPAL_CLIENT_SECRET=""
```

## Release Gate

Run the full release gate before staging or production deploy:

```bash
npm run release:gate
```

This runs:

- Vitest unit/integration tests.
- TypeScript check.
- ESLint.
- Production build.
- Playwright E2E smoke.

Staging env and remote smoke checks:

```bash
npm run check:env:staging
STAGING_BASE_URL=https://staging.example.com npm run verify:staging
```

Default Docker Compose staging deployment:

```bash
cp .env.staging.example .env.staging
npm run deploy:staging
```

The deep staging commerce E2E is enabled with:

```bash
ENABLE_E2E_FIXTURES=true RUN_COMMERCE_E2E=true npm run test:e2e
```

For pre-seeded staging data, you can also pass `E2E_STORE_ID=<store-id>` and `E2E_ORDER_ID=<order-id>` to reuse existing records instead of creating deterministic fixtures.

## Production Deployment

See:

- `docs/PRODUCTION_DEPLOYMENT.md`
- `docs/STAGING_ACCEPTANCE.md`
- `docs/STAGING_ACCEPTANCE_REPORT.md`

Minimum deployment sequence:

```bash
npm ci
npm run check:env:production
npx prisma generate
npx prisma migrate deploy
npm run release:gate
npm run build
npm run start
```

## Payments

- Stripe is the MVP payment provider.
- PayPal adapter is available for v1 commercial readiness and uses sandbox mode unless PayPal credentials are configured.

Stripe webhook endpoint:

```text
/api/v1/webhooks/stripe
```

PayPal order endpoint:

```text
/api/v1/admin/payments/paypal
```

## Clean Baseline

NextShop starts from a clean SaaS/Commerce Prisma baseline. Existing environments must create a fresh database and run the baseline migration rather than applying it to an older domain database.

## Commercial v1 Capabilities

Current v1 readiness endpoints:

- Buyer account: `/api/v1/storefront/account`
- Theme settings: `/api/v1/admin/theme`
- Notifications: `/api/v1/admin/notifications`
- PayPal orders: `/api/v1/admin/payments/paypal`
- Platform billing: `/api/v1/platform/billing`
- Staging report: `/api/v1/system/staging-report`
- E2E fixture: `/api/v1/system/e2e-fixture`

## Documentation

- `docs/SHOPIFY_SAAS_DEVELOPMENT_PLAN.md`
- `docs/API_CONTRACTS.md`
- `docs/DOMAIN_MODEL.md`
- `docs/MARKETS_LOCALIZATION.md`
- `docs/CHECKOUT_AND_ORDER_STATE.md`
- `docs/TEST_STRATEGY.md`
- `docs/PRODUCTION_DEPLOYMENT.md`
- `docs/STAGING_DEPLOYMENT.md`
- `docs/STAGING_ACCEPTANCE.md`
- `docs/ROADMAP_STATUS.md`