cherry backend

The cherry backend is a Node.js and TypeScript API built with Express and Firebase. It powers the cherry mobile app and supports a simple, trustworthy donation checkout flow for pre-loved clothing.

What this API covers

• Firebase-backed auth and user lookup
• Product, category, and charity APIs
• Order creation and CSV export
• Stripe payment intent creation and webhook handling
• Sendcloud shipping, pickup-point lookup, and webhook handling
• Swagger docs for local API exploration

MVP boundary

For the current MVP, the backend is designed to validate the digital checkout loop safely.

• Use Stripe sandbox only for local development and testing
• Treat real money flows as out of scope for MVP verification
• Default non-production shipping to mocked responses so checkout can be exercised without live logistics
• Keep names optional in checkout payloads unless a later requirement makes them necessary

The fuller rationale is in docs/backend-mvp-boundary.md.

Prerequisites

• Node.js 20 or later
• npm
• A Firebase project for non-test local development

Quick start

1. Install dependencies:

npm install

2. Copy the env template:

cp .env.example .env

3. Fill in the values you need for your local setup.

4. Start the API:

npm run start:dev

The API runs on http://localhost:3000 by default.

Swagger is available at:

http://localhost:3000/api-docs

Environment notes

Important vars for local work:

• STRIPE_SECRET_KEY
• STRIPE_PUBLISHABLE_KEY
• STRIPE_WEBHOOK_SECRET
• SENDCLOUD_MODE
• SENDCLOUD_PUBLIC_KEY
• SENDCLOUD_SECRET_KEY
• SENDCLOUD_WEBHOOK_SECRET
• FIREBASE_PROJECT_ID

Recommended defaults:

• Keep Stripe in test mode locally
• Set SENDCLOUD_MODE=mock outside production
• Only use live Sendcloud credentials when you are deliberately testing the live shipping integration

See .env.example for the full template.

Development commands

npm run start:dev
npm run build
npm test -- --runInBand

Key backend ownership

These files are the main entry points for the checkout path:

• Auth: src/shared/middleware/authMiddleWare.ts, src/modules/auth/
• Orders: src/modules/order/controllers/orderController.ts, src/modules/order/repositories/OrderRepository.ts
• Payments: src/shared/config/stripeConfig.ts, src/modules/payment/
• Shipping: src/shared/config/sendcloudConfig.ts, src/modules/shipping/
• App wiring: src/app.ts

Contributing

Start with CONTRIBUTING.md. It covers local setup, mock-first workflows, and the files that usually need to change together.