This is a two day hackathon project. DO NOT USE IN PRODUCTION.

A monorepo for the Homegate project - your gateway to sign up and join the Pubky homeserver network.

Live demo for the Staging homeserver: homegate.live

Features

• Three-tier signup system: Free (math captcha), Basic (50k sats), Pro (200k sats)
• Bot protection with math captcha verification and SMS verification via Prelude
• Lightning Network payments for Basic and Pro plans
• Real-time payment notifications via WebSocket
• Invite code generation system for homeserver access
• Simple user profile creation with a name and image
• Sign in with an existing user
• User dashboard showing the user's plan

External Dependencies

• Cloudflare Turnstile Invisible captcha bot protection
• Prelude SMS Verification made easy
• phoenixd Receive Bitcoin Lightning payments

# Start with Docker (recommended)
make dev              # Development mode with logs
# or
make up               # Background mode

# Access: http://localhost:8882 (frontend)

Add the PRELUDE_API_TOKEN to front-end/.env.local for SMS verification.

That's it! The frontend and backend and phoenixd will be running.

homegate/
├── front-end/         # Next.js 16 web application
│   ├── src/
│   │   ├── app/       # Next.js App Router pages and API routes
│   │   ├── components/ # React components and UI elements
│   │   ├── contexts/  # React context providers
│   │   ├── hooks/     # Custom React hooks
│   │   └── lib/       # Utility functions and configurations
│   └── public/        # Static assets
├── back-end/          # Express.js API server
│   ├── src/
│   │   ├── controllers/ # Request handlers
│   │   ├── routes/     # API route definitions
│   │   └── services/   # Business logic and WebSocket service
│   └── dist/          # Compiled TypeScript output
└── phoenixd/          # Phoenix Lightning node data (git-ignored)

Next.js 16 web application with shadcn/ui for the homeserver signup gateway.

Tech Stack:

• Next.js 16.0.0 with App Router
• React 19.2.0
• TypeScript 5 (strict mode)
• Tailwind CSS v4
• shadcn/ui components (button, dialog)
• @prelude.so/sdk for SMS verification
• @synonymdev/pubky for Pubky integration
• React Hook Form with Zod validation
• Lucide React icons

Get Started:

cd front-end
npm install
npm run dev

See the front-end directory for detailed documentation.

Express.js REST API server with WebSocket support for handling Lightning invoices and payments.

Tech Stack:

• Express.js 4.21.2
• TypeScript 5.7.2
• WebSocket support (ws package)
• Phoenix daemon integration
• CORS enabled
• ts-node-dev for development

API Endpoints:

• /health - Health check with WebSocket status
• /api/invoice - Lightning invoice management
• /api/webhook - Webhook handling
• /ws - WebSocket connection for real-time updates

Get Started:

cd back-end
npm install
npm run dev

See the back-end directory for detailed documentation.

• Node.js 18+ (for local development)
• npm, yarn, or pnpm (for local development)
• Docker & Docker Compose (for containerized development)

The easiest way to run the entire stack:

# Quick start with Makefile
make dev              # Start with logs (recommended for development)
make up               # Start in background

# Or use Docker Compose directly
docker compose up     # Start with logs
docker compose up -d  # Start in background

Access the application:

• Frontend: http://localhost:8882
• Backend API: http://localhost:8881
• phoenixd API: http://localhost:9740

Other useful commands:

make logs      # View logs
make down      # Stop services
make restart   # Restart services
make help      # See all available commands

See the docker-compose.yml file for complete Docker configuration.

1. Clone the repository

git clone <repository-url>
cd homegate

2. Set up the frontend

cd front-end
npm install
npm run dev

3. Open your browser

• Frontend: http://localhost:8882

This is set up as a monorepo to accommodate multiple packages:

• front-end: Next.js web application
• back-end: Express.js API server
• phoenixd: Lightning Network node (managed by Docker)

The project includes Docker Compose configuration with the following services:

• Port: 8882
• Container: Next.js 16 application
• Features: Hot reload, volume mounting for live development
• Image: Custom build from front-end/Dockerfile

• Port: 8881
• Container: Express.js API server with WebSocket support
• Features: Hot reload with ts-node-dev, REST API endpoints, WebSocket connections
• Image: Custom build from back-end/Dockerfile
• Endpoints: /api/invoice, /api/webhook, /health, /ws

• Port: 9740
• Container: Lightning Network node
• Features: Data persistence, automatic restart
• Image: acinq/phoenixd:latest
• Volume: ./phoenixd (automatically created, git-ignored)

💡 Tip: Use make dev for active development to see logs in real-time.