Afribit NFC Setup App - Complete Documentation

Project Status: ✅ Research Complete - Ready to Implement

Timeline: 8-10 weeks | Budget: $25K-$65K | Team: 1-2 developers

📋 Quick Navigation

Document	Description	Priority
IMPLEMENTATION_ROADMAP.md	Start here! Week-by-week plan, getting started guide	🔴 CRITICAL
TECH_STACK_ANALYSIS.md	Complete technology stack analysis and architecture	🔴 CRITICAL
NTAG424_IMPLEMENTATION.md	NFC card programming guide with code examples	🟠 HIGH
BOLT_CARD_FACTORY_API.md	BTCPay Server plugin API documentation	🟠 HIGH
RENDER_DEPLOYMENT_GUIDE.md	Backend deployment and remote access setup	🟡 MEDIUM

🎯 What You're Building

A React Native mobile app that automates Bitcoin "Bolt Card" (NTAG424 DNA) provisioning:

Current Process (Manual):

Requires laptop + USB NFC writer
Manual API key generation
Switching between 3 different websites
Technical knowledge required

Your Solution (Automated):

Mobile app with "scan and tap" workflow
Connects to merchant's Blink account
Programs NFC cards via phone's antenna
No technical knowledge needed

✅ Prerequisites You Have

Based on your message:

BTCPay Server instance running
Bolt Card Factory plugin installed
Blank NTAG424 DNA NFC cards
Render.com account for backend
GitHub repository: https://github.com/Afribit-Africa/nfc

🚀 Critical Discovery: You Can Start Immediately!

1. NTAG424 Library Already Exists 🎉

Found: https://github.com/boltcard/bolt-nfc-android-app

This React Native app has complete NTAG424 implementation:

Ntag424.js - All APDU commands
Cmac.js - AES-128 cryptography
apdu.js - Command builders

Action: Port these 3 files = saves 2-3 weeks of development!

2. BTCPay Plugin API Documented ✅

Endpoints discovered:

POST /plugins/boltcards/factories/{factoryId}/cards
GET  /plugins/boltcards/balance/{cardUid}
POST /plugins/boltcards/reset/{cardUid}

Authentication: BTCPay API Key (Bearer token)

See BOLT_CARD_FACTORY_API.md for details.

3. Backend Architecture Defined ✅

Node.js/Express on Render.com
PostgreSQL database (hosted by Render)
JWT authentication
Complete deployment guide ready

See RENDER_DEPLOYMENT_GUIDE.md for setup.

🛠️ Tech Stack Summary

Mobile App

React Native 0.72+ (TypeScript)
├── react-native-nfc-manager (NFC operations)
├── NTAG424 library (ported from bolt-nfc-android-app)
├── react-native-crypto (AES encryption)
├── React Query (API state management)
├── Zustand (local state)
└── React Native Paper (UI components)

Backend

Node.js 18 + TypeScript
├── Express.js (REST API)
├── PostgreSQL (Render hosted)
├── Sequelize (ORM)
├── JWT (authentication)
└── Axios (external API calls)

External Services

BTCPay Server (your instance)
├── Bolt Card Factory plugin
└── Greenfield API v1

Blink (Galoy)
└── GraphQL API

📅 8-Week Development Plan

Phase	Duration	Focus	Deliverable
Phase 1	Week 1-2	Foundation	Backend API + Mobile skeleton
Phase 2	Week 3-4	NFC Integration	Card detection and reading
Phase 3	Week 4-5	BTCPay Integration	Store creation and registration
Phase 4	Week 5-7	Card Programming	Full NTAG424 writing
Phase 5	Week 7-8	User Interface	Complete mobile UI
Phase 6	Week 8-9	Testing	Hardware validation
Phase 7	Week 9-10	Deployment	App Store submission

Detailed breakdown: See IMPLEMENTATION_ROADMAP.md

💻 Quick Start (Today!)

Step 1: Clone Repositories

# Your main repo
git clone https://github.com/Afribit-Africa/nfc.git
cd nfc

# Reference repo (for NTAG424 code)
git clone https://github.com/boltcard/bolt-nfc-android-app.git ../bolt-reference

Step 2: Setup Backend

mkdir backend
cd backend
npm init -y
npm install express cors helmet dotenv pg sequelize jsonwebtoken bcryptjs axios

# Follow templates in RENDER_DEPLOYMENT_GUIDE.md

Step 3: Setup Mobile

npx react-native init AfribitNFC --template react-native-template-typescript
cd AfribitNFC
npm install react-native-nfc-manager react-query zustand

# Copy NTAG424 files from bolt-reference
mkdir -p src/lib/ntag424
cp ../bolt-reference/Ntag424.js ./src/lib/ntag424/Ntag424.ts
cp ../bolt-reference/Cmac.js ./src/lib/ntag424/Cmac.ts

Step 4: Test NFC

import NfcManager, { NfcTech } from 'react-native-nfc-manager';

async function testNFC() {
  await NfcManager.start();
  await NfcManager.requestTechnology(NfcTech.IsoDep);
  const tag = await NfcManager.getTag();
  console.log('Card detected:', tag);
  await NfcManager.cancelTechnologyRequest();
}

Step 5: Test BTCPay

curl -H "Authorization: token YOUR_API_KEY" \
  https://your-btcpay-instance.com/api/v1/stores

Full getting started guide: IMPLEMENTATION_ROADMAP.md

📊 Success Metrics

Technical Milestones

Backend deployed to Render.com
Mobile app detects NTAG424 cards
BTCPay store created successfully
First card programmed end-to-end
Card works with Lightning wallet
95%+ card write success rate

Business Milestones

💰 Budget Breakdown

Development (8-10 weeks)

Mobile Developer: 320 hours @ $75/hr = $24,000
Backend Developer: 160 hours @ $75/hr = $12,000
Testing & QA: 40 hours @ $50/hr = $2,000

Infrastructure (First Year)

Render.com: $84/year
BTCPay hosting: $300/year
Domain + SSL: $15/year

Hardware & Tools

NTAG424 cards (100): $150
Test devices: $500
App Store fees: $124

Contingency (20%)

Unexpected issues: $7,800

TOTAL: ~$47,000 first year

🎓 Required Skills

Mobile Developer

React Native (TypeScript)
NFC/APDU protocols
iOS/Android app deployment
Cryptography basics (AES)

Backend Developer

Node.js/Express
PostgreSQL/SQL
REST API design
JWT authentication
Bitcoin/Lightning basics

Bonus Skills

BTCPay Server administration
Blink API experience
Financial app security

🐛 Common Pitfalls & Solutions

Issue	Solution	Document
"NFC not available"	Run on physical device	NTAG424_IMPLEMENTATION.md
"Tag lost during write"	Add retry logic, hold 5+ seconds	NTAG424_IMPLEMENTATION.md
"BTCPay API 401"	Check API key permissions	BOLT_CARD_FACTORY_API.md
"Database connection failed"	Add `?sslmode=require` to URL	RENDER_DEPLOYMENT_GUIDE.md
"Keys don't match"	Verify 16 bytes of 0x00 default	NTAG424_IMPLEMENTATION.md

📚 Learning Resources

🔐 Security Considerations

Critical Requirements

API Key Storage - Never store BTCPay admin keys in mobile app
Key Encryption - Use AES-256 for card keys in database
Transport Security - HTTPS/TLS 1.3 for all API calls
Rate Limiting - Max 20 cards per hour per merchant
NTAG424 Locking - Set read-only after programming

Full security guide: TECH_STACK_ANALYSIS.md

📞 Support & Communication

Primary Channels

GitHub Issues: Bug reports, feature requests
GitHub Discussions: General questions
Weekly sync: Progress updates

Emergency Contacts

BTCPay Community: https://chat.btcpayserver.org/
Bolt Card Telegram: https://t.me/bolt_card

🎯 Next Immediate Actions

For You (Project Owner)

Add developer as GitHub collaborator
Share Render.com account access
Provide BTCPay API key
Share Blink API key for testing
Setup communication channel

For Developer

🏁 Definition of Done

Project is complete when:

✅ Mobile app on App Store and Play Store ✅ Backend deployed and stable on Render ✅ 100 cards successfully programmed ✅ 3+ merchants actively using ✅ Documentation complete ✅ Zero critical bugs ✅ 99.9% uptime for 30 days ✅ Positive user feedback (4+ stars)

📝 Project Status

Research Phase: ✅ Complete (November 25, 2025) Development Phase: 🟡 Ready to start Testing Phase: ⚪ Not started Deployment Phase: ⚪ Not started

📖 Documentation Index

Core Documents (Start Here)

IMPLEMENTATION_ROADMAP.md - Week-by-week development plan
TECH_STACK_ANALYSIS.md - Technology decisions and architecture
NTAG424_IMPLEMENTATION.md - NFC programming guide
BOLT_CARD_FACTORY_API.md - BTCPay plugin integration
RENDER_DEPLOYMENT_GUIDE.md - Backend hosting setup

Additional Resources

Source code reference: https://github.com/boltcard/bolt-nfc-android-app
Your repository: https://github.com/Afribit-Africa/nfc

🎉 Ready to Build!

All research is complete. All blockers resolved. Documentation is comprehensive.

You have everything needed to start development today.

📧 Questions?

If you need clarification on any document:

Check the specific document first
Search GitHub Issues
Post in GitHub Discussions
Contact via agreed communication channel

📄 License

MIT License - see LICENSE file

🙏 Acknowledgments

BTCPay Server team for the Bolt Card Factory plugin
Bolt Card community for reference implementations
React Native NFC Manager maintainers
Blink (Galoy) for Lightning infrastructure

Last Updated: November 25, 2025 Version: 1.0 Status: Research Complete ✅

Let's build something amazing! 🚀⚡

Name		Name	Last commit message	Last commit date
backend		backend
mobile		mobile
.gitignore		.gitignore
BACKEND_UPDATE.md		BACKEND_UPDATE.md
BOLT_CARD_FACTORY_API.md		BOLT_CARD_FACTORY_API.md
BTCPAY_API_FIX.md		BTCPAY_API_FIX.md
COMPLETE_SETUP_GUIDE.md		COMPLETE_SETUP_GUIDE.md
DATABASE_ALTERNATIVES.md		DATABASE_ALTERNATIVES.md
IMPLEMENTATION_ROADMAP.md		IMPLEMENTATION_ROADMAP.md
NEXT_STEPS.md		NEXT_STEPS.md
NTAG424_IMPLEMENTATION.md		NTAG424_IMPLEMENTATION.md
PROGRESS_REPORT.md		PROGRESS_REPORT.md
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
RENDER_DEPLOYMENT_GUIDE.md		RENDER_DEPLOYMENT_GUIDE.md
RESEARCH_FINDINGS.md		RESEARCH_FINDINGS.md
SETUP_INSTRUCTIONS.md		SETUP_INSTRUCTIONS.md
SUCCESS_SUMMARY.md		SUCCESS_SUMMARY.md
TECH_STACK_ANALYSIS.md		TECH_STACK_ANALYSIS.md
railway.toml		railway.toml

Latest commit

History

Folders and files

Repository files navigation