lnflash · ChuanWeis · May 12, 2026
diff --git a/CONTRIBUTING.md 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
@@ -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
+<p align="center">
+  <img src="./docs/screenshots/keypad.svg" alt="Amount entry keypad" width="240" />
+  <img src="./docs/screenshots/invoice.svg" alt="Lightning invoice screen" width="240" />
+  <img src="./docs/screenshots/flashcard-balance.svg" alt="Flashcard balance screen" width="240" />
+</p>
 
-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 <kbd>R</kbd> key twice or select **"Reload"** from the **Developer Menu** (<kbd>Ctrl</kbd> + <kbd>M</kbd> (on Window and Linux) or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> (on macOS)) to see your changes!
+```bash
+yarn test
+yarn lint
+```
 
-   For **iOS**: Hit <kbd>Cmd ⌘</kbd> + <kbd>R</kbd> 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
diff --git a/docs/screenshots/invoice.svg b/docs/screenshots/invoice.svg
diff --git a/docs/screenshots/keypad.svg b/docs/screenshots/keypad.svg