diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c961db5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing to Flash POS + +Thanks for helping improve Flash POS. This guide keeps contributions easy to +review and safe for a payment-focused mobile app. + +## Before You Start + +1. Check the issue tracker for an existing issue. +2. Comment on the issue if you plan to work on it, especially for bounty work. +3. Keep credentials, API keys, wallet data, screenshots with private account + information, and production payment details out of commits and PR comments. + +## Local Setup + +```bash +git clone https://github.com/lnflash/flash-pos.git +cd flash-pos +yarn install +cp .env.example .env +yarn start +``` + +Use `yarn android` or `yarn ios` from a second terminal to run the app. NFC, +printing, and production payment flows should be tested on physical devices +when your change touches those areas. + +## Development Workflow + +1. Create a focused branch from `main`. +2. Make the smallest change that solves the issue. +3. Add or update docs when behavior, setup, or operator expectations change. +4. Run the relevant checks: + +```bash +yarn test +yarn lint +``` + +For Android release-sensitive changes, also smoke-check: + +```bash +yarn apk-android +``` + +## Pull Request Checklist + +- Describe the user-visible change. +- Link the issue being fixed. +- Include screenshots or screen recordings for UI changes. +- Note the test commands you ran. +- Call out any hardware-tested flows, such as NFC cards or printers. +- Explain any follow-up work that is intentionally left out of scope. + +## Bounty Notes + +Some issues may include Lightning or other reward terms. Eligibility depends on +the issue description and maintainer review. Do not include payment addresses, +API secrets, private keys, or other sensitive payment details in the repository. +Share payout details only through the maintainer-approved private process. diff --git a/README.md b/README.md index 12470c3..d77c5a7 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,155 @@ -This is a new [**React Native**](https://reactnative.dev) project, bootstrapped using [`@react-native-community/cli`](https://github.com/react-native-community/cli). +# Flash POS -# Getting Started +Flash POS is a React Native point-of-sale app for merchants who accept Bitcoin +and Lightning payments. It combines invoice creation, NFC flashcard support, +customer rewards, transaction history, and receipt printing in one mobile +checkout flow. ->**Note**: Make sure you have completed the [React Native - Environment Setup](https://reactnative.dev/docs/environment-setup) instructions till "Creating a new application" step, before proceeding. +## Screenshots -## Step 1: Start the Metro Server +

+ Amount entry keypad + Lightning invoice screen + Flashcard balance screen +

-First, you will need to start **Metro**, the JavaScript _bundler_ that ships _with_ React Native. +## Features -To start Metro, run the following command from the _root_ of your React Native project: +- Create Lightning invoices for customer payments. +- Let customers pay with QR code, copied invoice text, shared invoice text, or + supported NFC flashcards. +- Award configurable customer rewards for Lightning or external cash/card + payments. +- View transaction history and flashcard activity. +- Configure reward settings and event-mode promotions behind PIN protection. +- Print receipts through supported mobile receipt-printer integrations. + +## Hardware Support + +Flash POS can run on Android and iOS devices supported by React Native 0.76. +The optional hardware-dependent flows require: + +- An NFC-capable phone or tablet for reading Bolt Card/Flashcard-compatible + NDEF tags. +- NFC enabled at the operating-system level before scanning customer cards. +- A Bluetooth, network, or platform-supported receipt printer when receipt + printing is enabled. +- A configured Lightning backend, GraphQL API, and BTCPay Server pull-payment + setup for production payments and rewards. + +NFC and printer behavior should be validated on real devices because most +simulators do not expose the native hardware APIs used by the app. + +## Local Development + +### Prerequisites + +- Node.js 18 or newer. +- Yarn. +- Android Studio and a configured Android SDK for Android development. +- Xcode and CocoaPods for iOS development on macOS. +- A physical device for NFC or printer testing. + +### Setup ```bash -# using npm -npm start +git clone https://github.com/lnflash/flash-pos.git +cd flash-pos +yarn install +cp .env.example .env +``` -# OR using Yarn -yarn start +Edit `.env` with your local or staging service endpoints. The most important +values are: + +```bash +FLASH_GRAPHQL_URI=https://api.your-server.com/graphql +FLASH_GRAPHQL_WS_URI=wss://api.your-server.com/graphql +FLASH_LN_ADDRESS_URL=https://ln.your-server.com +FLASH_LN_ADDRESS=your-domain.com +BTC_PAY_SERVER=https://btcpay.your-server.com +PULL_PAYMENT_ID=your-btcpay-pull-payment-id ``` -## Step 2: Start your Application +See [docs/environment-configuration.md](./docs/environment-configuration.md) +for the full environment reference. -Let Metro Bundler run in its _own_ terminal. Open a _new_ terminal from the _root_ of your React Native project. Run the following command to start your _Android_ or _iOS_ app: +### Run the App -### For Android +Start Metro: ```bash -# using npm -npm run android +yarn start +``` + +Run Android: -# OR using Yarn +```bash yarn android ``` -### For iOS +Run iOS: ```bash -# using npm -npm run ios - -# OR using Yarn +cd ios +pod install +cd .. yarn ios ``` -If everything is set up _correctly_, you should see your new app running in your _Android Emulator_ or _iOS Simulator_ shortly provided you have set up your emulator/simulator correctly. - -This is one way to run your app — you can also run it directly from within Android Studio and Xcode respectively. - -## Step 3: Modifying your App +### Validate Changes -Now that you have successfully run the app, let's modify it. - -1. Open `App.tsx` in your text editor of choice and edit some lines. -2. For **Android**: Press the R key twice or select **"Reload"** from the **Developer Menu** (Ctrl + M (on Window and Linux) or Cmd ⌘ + M (on macOS)) to see your changes! +```bash +yarn test +yarn lint +``` - For **iOS**: Hit Cmd ⌘ + R in your iOS Simulator to reload the app and see your changes! +For release smoke checks: -## Congratulations! :tada: +```bash +yarn apk-android +yarn aab-android +``` -You've successfully run and modified your React Native App. :partying_face: +## Project Structure + +```text +flash-pos/ + App.tsx Root providers and app shell + src/routes/ React Navigation stack and tabs + src/screens/ POS, invoice, rewards, profile, and history screens + src/components/ Shared UI and feature components + src/contexts/ Activity and NFC flashcard context providers + src/graphql/ Apollo client, mutations, subscriptions, queries + src/store/ Redux Toolkit slices and persistence + docs/ Detailed architecture and feature documentation + android/ Android native project + ios/ iOS native project +``` -### Now what? +## Documentation -- If you want to add this new React Native code to an existing application, check out the [Integration guide](https://reactnative.dev/docs/integration-with-existing-apps). -- If you're curious to learn more about React Native, check out the [Introduction to React Native](https://reactnative.dev/docs/getting-started). +- [Project overview](./docs/01-project-overview.md) +- [Development setup](./docs/02-development-setup.md) +- [API integration](./docs/04-api-integration.md) +- [Screens and navigation](./docs/05-screens-navigation.md) +- [NFC integration](./docs/06-nfc-integration.md) +- [Rewards system](./docs/07-rewards-system.md) +- [Printing system](./docs/08-printing-system.md) +- [Testing](./docs/10-testing.md) +- [Deployment](./docs/11-deployment.md) +- [Security](./docs/12-security.md) -# Troubleshooting +## Contributor Quick Start -If you can't get this to work, see the [Troubleshooting](https://reactnative.dev/docs/troubleshooting) page. +1. Pick an open issue or create one before starting larger work. +2. Create a branch from `main` and keep your change focused. +3. Update related docs and run `yarn test` plus `yarn lint` before opening a + pull request. -# Learn More +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full workflow. -To learn more about React Native, take a look at the following resources: +## License -- [React Native Website](https://reactnative.dev) - learn more about React Native. -- [Getting Started](https://reactnative.dev/docs/environment-setup) - an **overview** of React Native and how setup your environment. -- [Learn the Basics](https://reactnative.dev/docs/getting-started) - a **guided tour** of the React Native **basics**. -- [Blog](https://reactnative.dev/blog) - read the latest official React Native **Blog** posts. -- [`@facebook/react-native`](https://github.com/facebook/react-native) - the Open Source; GitHub **repository** for React Native. +No repository license file is currently included. Confirm licensing with the +maintainers before redistributing or publishing derived builds. diff --git a/docs/screenshots/flashcard-balance.svg b/docs/screenshots/flashcard-balance.svg new file mode 100644 index 0000000..a3866b2 --- /dev/null +++ b/docs/screenshots/flashcard-balance.svg @@ -0,0 +1,24 @@ + + Flashcard balance screen + A phone mockup showing a scanned customer flashcard balance and recent activity. + + + Flashcard Balance + + + FLASH CARD + Tap to pay or receive rewards + 12,450 sats + Approx. balance after scan + Recent Activity + + + Coffee purchase + Lightning payment + -2,100 + + Reward + Loyalty points + +250 + + diff --git a/docs/screenshots/invoice.svg b/docs/screenshots/invoice.svg new file mode 100644 index 0000000..8ed97cb --- /dev/null +++ b/docs/screenshots/invoice.svg @@ -0,0 +1,26 @@ + + Flash POS Lightning invoice screen + A phone mockup showing a Lightning invoice QR code with copy, share, and NFC payment options. + + + Pay to merchant + + NFC + $12.50 + Invoice expires in 10:00 + + + + + + + + + + + Copy + + Share + + Back + diff --git a/docs/screenshots/keypad.svg b/docs/screenshots/keypad.svg new file mode 100644 index 0000000..2dcaf36 --- /dev/null +++ b/docs/screenshots/keypad.svg @@ -0,0 +1,22 @@ + + Flash POS amount entry screen + A phone mockup showing the merchant keypad for entering a customer payment amount. + + + Pay to merchant + $12.50 + Enter sale amount + + Note + Coffee + + 123 + 456 + 789 + .0del + + + Give Points + + Next +