Skip to content

Commit 553435a

Browse files
bc-traciporterbc-traciporter
authored
Merge pull request #1 from slsriehl/patch-2
README revisions
2 parents 21b5ce4 + 6e20e3b commit 553435a

1 file changed

Lines changed: 84 additions & 67 deletions

File tree

‎README.md‎

Lines changed: 84 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,86 +1,103 @@
11
# BigCommerce Point of Sale Foundation
22

3-
🚀 This open-sourced POS showcases how custom in-store apps could be built using the BigCommerce platform.
3+
This open source proof-of-concept app showcases the BigCommerce platform's customizable ability to support point-of-sale transactions.
44

5-
💰 **Pre-integrated into Stripe Terminal**, including connection to multiple terminals at a single location.
5+
💰 **Integrated with Stripe Terminal**. Secure, pre-certified hardware with an SDK that recognizes multiple registers at a single location.
66

7-
| Register Screen | Checkout Screen |
8-
| ---------------------------------------- | -------------------------------------------- |
9-
| ![App Preview](sample-register-screen.png) | ![App Preview](sample-checkout-screen.png) |
7+
🚀 **Powered by MongoDB Cloud and the Prisma ORM**. Pre-configured migrations and seed data help you get started customizing the look, feel, and functionality of your POS implementation.
8+
9+
10+
| Register View | Checkout View |
11+
|:-------------:|:-------------:|
12+
| ![Register View](sample-register-screen.png) | ![Checkout View](sample-checkout-screen.png) |
13+
14+
## Core technologies
15+
16+
* Node.js 14.x / npm
17+
* A [BigCommerce (sandbox) store](https://developer.bigcommerce.com/api-docs/partner/getting-started/create-a-sandbox-store?source=pos-foundation)
18+
* A [pre-certified Stripe Terminal EMV card reader](https://stripe.com/terminal)
1019

11-
## Prerequisites
12-
You will need the following:
13-
* [BigCommerce sandbox store](https://developer.bigcommerce.com/docs/ZG9jOjM4MzMyNTE-create-a-sandbox-store?source=subscription-foundation) (required to develop and test apps)
14-
* a database (BigCommerce recommends MongoDB)
15-
* a shipping zone with a [Pickup in Store](https://support.bigcommerce.com/s/article/Free-Shipping?language=en_US#in-store) shipping method
16-
* a [Stripe POS terminal and card reader](https://stripe.com/terminal)
17-
* Experience using [npm](https://www.npmjs.com/)
18-
* Node.js 14.x
1920

2021
## Getting started
2122

22-
Head to the [POS Foundation](/api-docs/partner/pos-solutions/foundation-guide) guide to begin!
23-
24-
25-
## Key areas of codebase
26-
27-
- `/backend`
28-
- Where the auth and various API services live. These are used within the internal API endpoints to keep routes secure and reach out to external APIs.
29-
- `/prisma`
30-
- Where the DB models and initial seed data live. Prisma uses this to generate DB clients for the app.
31-
- `/shared`
32-
- Where the types are located.
33-
- `/src/pages`
34-
- Where the sections of the app are managed.
35-
- Next.js docs: https://nextjs.org/docs/basic-features/pages
36-
- `/src/pages/api`
37-
- Where the APIs for the app are managed.
38-
- Next.js docs: https://nextjs.org/docs/api-routes/introduction
39-
- `/src/providers`
40-
- Where the context providers used within pages and components live.
41-
- Most are built using the concept of an 'ActionBuilder' that manages execution, loading status, and data setting consistently.
42-
- `/{provider}/context.ts`: The types used throughout the provider.
43-
- `/{provider}/index.ts`: The actions available to the pages and components using the context providers.
44-
- `/{provider}/ methods.ts`: The functions used within the actions to fetch / modify data.
23+
Find prerequisites, configuration details, and more in the [POS Foundation Guide](https://developer.bigcommerce.com/api-docs/partner/pos-solutions/foundation-guide?source=pos-foundation) at the [BigCommerce Dev Center](https://developer.bigcommerce.com).
24+
25+
26+
## Directory structure highlights
27+
28+
```shell
29+
...
30+
├── backend/
31+
# Authentication and shared API services
32+
├── prisma/
33+
# DB models, migrations, and seed data
34+
├── public/
35+
├── shared/
36+
# Shared types
37+
└── src/
38+
...
39+
├── pages/
40+
# Top-level React component views and API routes
41+
# See https://nextjs.org/docs/basic-features/pages
42+
└── api/
43+
# The page's API routes
44+
# See https://nextjs.org/docs/api-routes/introduction
45+
└── providers/
46+
# Context providers for pages.
47+
# Most providers use a single higher-order 'ActionBuilder' wrapper to execute functions, set data, and update loading status. This pattern minimizes side effects and ensures consistent error handling.
48+
└── {NameOfProvider}/
49+
├── index.ts
50+
# The actions available to this provider's page and its child components.
51+
├── context.ts
52+
# The types available to this provider's page and its child components.
53+
└── methods.ts
54+
# The functions called by the provider's actions to fetch / modify data.
55+
56+
```
4557

4658
## Contributing
4759

48-
Want to help expand this foundation? We'd love to collaborate! To kick-off, here's a breakdown of items we've itemized as either potential improvements to the existing codebase or features worth adding.
49-
50-
- Improvements:
51-
- Improve error handling and types within try/catch in the employee service: backend/services/employee.service.ts
52-
- Create types for CreatePaymentIntentResponse and CapturePaymentIntentResponse: src/providers/CartProvider/context.ts
53-
- Move the transaction success screen shown when payment is completed to be its own component: src/components/modules/Orders/TenderDialog.tsx
54-
- Move numeric entry pad functionality into component: src/components/modules/Orders/TenderCash.tsx
55-
- Incorporate more graceful error handling for API calls and supply a generic method to show error messages on the FE
56-
- Add the shared component to handle loading indicators (overall and within buttons)
57-
- Create types for customer lookup actions in src/providers/CartProvider
58-
- Utilize the BigCommerce API Client types instead of the custom types (pending release of new client)
59-
- Prevent loading of the app if environment variables or BigCommerce store setup is invalid, along with instructions on how to fix
60-
- Features:
61-
- Ship-to-Customer checkout flow (creation / selection of shipping address)
62-
- Customer management section
63-
- Recall and finalize the payment on incomplete orders
64-
- Receipt Printer Hardware Support
65-
- Barcode Scanner Hardware Support
66-
- Cash Drawer Support
67-
- Product Lookup / Search
68-
- Basic Loyalty / Gift Card integration
69-
- Support for Multi-location Inventory, unlocking BOPIS (Buy Online, Pickup in Store)
70-
- Selection of store currency from the list of transactional currencies active on the POS channel
71-
- Returns, refunds, and store credit flows
72-
- Shift Change Operations
60+
Want to help expand this foundation? We'd love to collaborate! You can start with this list of both potential improvements and features worth adding to the existing codebase. You can also check out the [expansion resources](https://developer.bigcommerce.com/api-docs/partner/pos-solutions/foundation-guide?source=pos-foundation#expansion-resources) in our Dev Center's POS Foundation Guide.
61+
62+
### Improvements
63+
64+
| Location / Feature | Description |
65+
|:-------------------|:------------|
66+
| `backend/services/employee.service.ts` | Improve error handling and types within try/catch block. |
67+
| `src/providers/CartProvider/context.ts` | Create types for `CreatePaymentIntentResponse` and `CapturePaymentIntentResponse`. |
68+
| `src/components/modules/Orders/TenderDialog.tsx` | Move the transaction success view into the listed component. |
69+
| `src/components/modules/Orders/TenderCash.tsx` | Move the numeric entry pad into the listed component. |
70+
| Error handling | Supply a generic method to show error messages on the frontend; incorporate more graceful error handling for API calls. |
71+
| Loading indicators | Add a shared component to handle loading indicators, both overall and within buttons. |
72+
| `src/providers/CartProvider` | Create types for customer lookup actions. |
73+
| Types | Pending the release of the new BigCommerce Nodejs API client, refactor to replace the app's type system with the new standard types. |
74+
| Validity checks on load | If the BigCommerce store setup or environment variables are invalid, prevent the app from loading and provide instructions on how to remedy the failure. |
75+
### Features
76+
77+
| Feature Description | Goal |
78+
|:--------------------|:-----|
79+
| Refactor as a BigCommerce app with a dedicated sales channel | <ul><li>Access the POS from the **Channel Manager** view in the store control panel</li><li>Use in multiple physical locations</li><li>Associate transactions with the POS storefront</li></ul> |
80+
| A ship-to-customer checkout flow | Create and select shipping addresses |
81+
| Customer management view and logic | CRUD customer-related data |
82+
| Retrieve incomplete checkouts | Finalize or discard transactions |
83+
| Support additional hardware | <ul><li>Print receipts</li><li>Scan barcodes</li><li>Operate cash drawers</li></ul> |
84+
| Product lookup view and logic | Search for products |
85+
| Support multi-location inventory-related (MLI) features | <ul><li>Buy online, pickup in store (BOPIS)</li><li>Buy online, return in store (BORIS)</li><li>Buy in store, pickup at another store</li><li>Buy in store for delivery</li></ul> |
86+
| Select a transaction's currency from the list of transactional currencies active on the POS channel | Accept multiple currencies |
87+
| Integrate Orders V3 functionality | Accept returns, give refunds, etc. |
88+
| Issue, manage, and accept customer-centered payment methods | <ul><li>Gift cards</li><li>Store credit</li><li>Loyalty cards</li></ul> |
89+
| Multi-cashier functionality | Shift change operations, audit support, etc. |
7390

7491
## Learn more
7592

76-
### Additional point of sale solutions
93+
### Existing point of sale solutions
7794

78-
Check out the wide variety of POS apps on the [BigCommerce App Marketplace](https://www.bigcommerce.com/apps/in-store/?source=pos-foundation).
95+
Check out the variety of POS apps on the [BigCommerce App Marketplace](https://www.bigcommerce.com/apps/in-store/?source=pos-foundation).
7996

8097
### The BigCommerce platform
8198

82-
Looking to help the world's leading brands and the next generation of successful merchants take flight? To learn more about developing on top of the BigCommerce platform, take a look at the following resources:
99+
Looking to help the world's leading brands and the next generation of successful merchants take flight? To learn more about developing with the BigCommerce platform, take a look at the following resources:
83100

84-
- [BigCommerce Developer Center](https://developer.bigcommerce.com/?source=pos-foundation) - Learn more about BigCommerce platform features, APIs and SDKs
85-
- [BigDesign](https://developer.bigcommerce.com/big-design/?source=pos-foundation) - An interactive site for BigCommerce's React Components with live code editing
86-
- [Building BigCommerce Apps](https://developer.bigcommerce.com/api-docs/getting-started/building-apps-bigcommerce/building-apps?source=pos-foundation) - Learn how to build apps for the BigCommerce marketplace
101+
- [BigCommerce Dev Center](https://developer.bigcommerce.com/?source=pos-foundation) - Learn more about BigCommerce platform features, APIs and SDKs
102+
- [BigDesign](https://developer.bigcommerce.com/big-design/?source=pos-foundation) - BigCommerce's library of React components with sandbox tools
103+
- [Building BigCommerce Apps](https://developer.bigcommerce.com/api-docs/apps/guide/intro?source=pos-foundation) - Learn more about apps, from lightweight single-merchant customizations to fully-featured apps you can sell in the BigCommerce App Marketplace

0 commit comments

Comments
 (0)