LoraCon

Decentralized VPN & stealth-proxy ecosystem — enterprise billing, multi-gateway payments, real-time telemetry, and AI-agent integration.

Documentation Map · Architecture · Components · Quick Start · API · Security · Roadmap

Built by Lorapok Labs

📚 Documentation Map

The root README is the single entry point. Every other doc is linked here:

Doc	What it covers
DOCUMENTATION.md	Full API reference — every route, request/response shapes
DEPLOYMENT.md	AWS production deployment guide (VPC, ECS/EC2, ALB, RDS, CloudFront)
INSTRUCTIONS.md	Developer onboarding — setup, env vars, build, troubleshooting
PROJECT_CONTEXT.md	Architecture context table + features + run commands
planning.md	Roadmap checkboxes (completed / in-progress / planned)
features.md	Protocol + product feature list
web_admin_panel/README.md	Backend + React frontend architecture, admin tabs, endpoints
mcp_server/README.md	MCP JSON-RPC tools, env, AI-client wiring
browser_extension/README.md	Chrome MV3 / Firefox MV2 load + build
apple/README.md	Native iOS / iPadOS / macOS client (Swift + NetworkExtension)
desktop_client/README.md	Tauri 2.x desktop build per platform (Windows / Ubuntu / macOS)
infrastructure/terraform/README.md	AWS IaC layout + apply steps
skills/README.md	Agent skills index
AGENTS.md	Conventions + subagent roster + multi-agent ops rules
.kiro/brain/SYNC.md	Live coordination state — who owns what, current status
.kiro/brain/AI-ORCHESTRATION.md	How the specialist agents circulate work to convergence

Architecture

graph TD
    subgraph Clients
        ANDROID[Android Client<br/>Kotlin / Compose<br/>VpnService userspace tunnel]
        APPLE[Apple Client<br/>iOS / iPadOS / macOS<br/>SwiftUI + NetworkExtension + WireGuardKit]
        WEB[Web Admin Panel<br/>React / Vite / Tailwind]
        EXT[Browser Extension<br/>Chrome MV3 / Firefox MV2 proxy]
        DESKTOP[Desktop Client<br/>Rust / Tauri 2.x<br/>Windows / Ubuntu / macOS]
    end

    subgraph Backend
        API[Express API :5000<br/>JWT / rate-limit / WS]
        DB[db.js Data Layer<br/>Prisma or JSON fallback]
        FINANCE[finance.js<br/>Revenue / P&L / Cost Explorer]
        GATEWAYS[payments/gateways.js<br/>Stripe / PayPal / Paddle / Coinbase]
        WS[WS Telemetry<br/>/ws/telemetry 5s broadcast]
    end

    subgraph Integrations
        SOL[Solana Mainnet<br/>On-chain tx verify]
        PAY[Payment Gateways<br/>Stripe / PayPal / Paddle / Coinbase]
        AIPROXY[AI Proxy<br/>Gemini / Grok]
        MCP[MCP Server<br/>JSON-RPC stdio + WS :8765]
    end

    subgraph Infrastructure
        TF[Terraform IaC<br/>VPC / EC2 / RDS / ElastiCache / CloudFront]
        CI[GitHub Actions CI/CD<br/>deploy.yml]
        PAGES[gh-pages build<br/>public hosting pending]
        TESTS[Property tests<br/>fast-check / Kotest]
    end

    subgraph AI Orchestration
        ORCH[11 specialist agents<br/>+ consistency checker + docs gate<br/>.kiro/brain/AI-ORCHESTRATION.md]
    end

    ANDROID -->|REST + JWT| API
    APPLE -->|REST + JWT| API
    WEB -->|Axios + JWT| API
    WEB -.->|WSS telemetry| WS
    EXT -->|node list + proxy| API
    DESKTOP -->|embeds web panel| WEB

    API --> DB
    API --> FINANCE
    API --> GATEWAYS
    API --> WS
    API -->|tx verify| SOL
    GATEWAYS -->|signed webhooks| PAY
    API -->|proxied chat| AIPROXY
    MCP -->|JSON-RPC + JWT| API

    TF -->|provisions| API
    CI -->|builds + tests| TESTS
    CI -->|builds frontend| PAGES
    CI -->|terraform apply| TF
    ORCH -->|edits + verifies| API
    ORCH -->|edits + verifies| WEB

AI orchestration: the codebase is maintained by a layer of 11 specialist agents (backend, frontend, design, android, apple, desktop, devops, security-review, consistency, docs, git) coordinated through .kiro/brain/SYNC.md, a cached consistency checker, and a docs-before-commit gate. See .kiro/brain/AI-ORCHESTRATION.md.

Components

Component	Path	Stack
Android client	`app/`	Kotlin, Jetpack Compose, Retrofit/Moshi, DataStore, VpnService (userspace UDP tunnel relay; WireGuard encryption stubbed)
Apple client	`apple/`	Swift, SwiftUI, NetworkExtension Packet Tunnel Provider + WireGuardKit; iOS / iPadOS / macOS (XcodeGen) — scaffold
Node.js backend	`web_admin_panel/backend/`	Express, JWT, ws, bcrypt, Solana web3, db.js (Prisma/JSON)
React web panel	`web_admin_panel/frontend/`	Vite, React Router, Tailwind, Framer Motion, Axios
MCP server	`mcp_server/`	Node, JSON-RPC over stdio + WebSocket (:8765)
Browser extension	`browser_extension/`	Chrome MV3 / Firefox MV2 proxy, WebRTC leak block
Desktop client	`desktop_client/`	Rust + Tauri 2.x (embeds web panel)
Terraform IaC	`infrastructure/terraform/`	AWS VPC, ECS Fargate, ALB, RDS, S3/CloudFront
CI/CD	`.github/workflows/deploy.yml`	Build, test, deploy backend + frontend + APK
Kiro steering	`.kiro/`	Brain, specs, agents, hooks, steering files

Platform Coverage

Platform	Path / Tech	Status	Notes
Android	`app/` — Kotlin/Compose, VpnService	Production	Userspace UDP tunnel; WireGuard encryption stubbed
iOS / iPadOS	`apple/` — SwiftUI + NetworkExtension + WireGuardKit	Scaffold	Builds on a Mac w/ Xcode; encryption gated on WireGuardKit + node keys
macOS	`apple/` (native) or `desktop_client/` (Tauri)	Scaffold	Native NetworkExtension preferred; Tauri is the cross-platform alternative
Windows	`desktop_client/` — Tauri/Rust	Stub	wintun + boringtun + WFP kill-switch — TODO
Ubuntu / Linux	`desktop_client/` — Tauri/Rust	Scaffold	`wg`/`ip` tunnel + iptables kill-switch (Command-based); `.deb`/`.AppImage`
Browser	`browser_extension/` — MV3 / MV2	Production	One-click proxy + WebRTC-leak block (Chrome/Brave/Firefox)
Web panel	`web_admin_panel/frontend/` — React	Production	Admin + landing

Roadmap — additional platforms (suggested)

Windows — finish the wintun/boringtun + WFP stub to a real tunnel.
Apple TV (tvOS) / Android TV — geo-unblock streaming is a top VPN use case; reuse the Apple/Android tunnel cores.
Router / OpenWRT — WireGuard config export for whole-home coverage with no per-device app.
Headless CLI (Go/Rust) — Linux servers, Raspberry Pi, power users.
Flatpak / Snap / .rpm — broader Linux-distro reach beyond .deb/.AppImage.
ChromeOS — already runs the Android APK; document + verify.

Feature Highlights

JWT authentication -- access tokens (15 min) + refresh tokens (7 days), HttpOnly cookies, in-memory-only storage on frontend
WebSocket telemetry -- real-time node load/latency broadcast every 5 seconds with exponential-backoff reconnect
Solana Mainnet verification -- on-chain transaction lookup, treasury address matching, amount validation
4-tier Protocol subscription system -- Free Relay (0 SOL) / Protocol Stealth (0.5 SOL ≈ $75) / Protocol Warp (1.2 SOL ≈ $180) / Sentinel Prime (2.5 SOL ≈ $375), SOL-priced with USD equivalent, bandwidth and node-access controls
Multi-gateway payments -- Stripe, PayPal, Paddle, and crypto (Coinbase/BTCPay) with signature-verified webhooks
Finance & Reports dashboard -- subscriber revenue, AWS costs (live Cost Explorer or estimated fallback), P&L, CSV export
Cost Dashboard -- real-time AWS spend monitoring via Cost Explorer, budget alerts via SNS
Payment Control Panel -- admin toggle for each payment gateway, transaction ledger, revenue breakdown
Privilege keys -- admin-issued encrypted VPN access keys with tier-based permissions
MCP server for AI agents -- list_nodes, deploy_ephemeral_tunnel, rotate_keys via JSON-RPC
Browser extension -- one-click stealth proxy with WebRTC leak protection for Chrome/Brave/Firefox
Android userspace tunnel -- protected UDP relay (TUN ↔ socket loops to peer :51820), kill-switch and auto-reconnect; WireGuard encryption (Noise_IKpsk2 + ChaCha20) is still stubbed — the relay moves plaintext pending boringtun/wireguard-go via JNI + live node keys
Tauri desktop scaffold -- Rust + Tauri 2.x with WireGuard tunnel stubs and OS-level kill-switch branches
Property-based tests -- fast-check (backend) and Kotest (Android) covering JWT, sessions, sanitization, entities
Kiro integration -- steering files, hooks (lint, build-check), agents, brain, and enterprise specs

Quick Start

Backend

cd web_admin_panel/backend
npm install
cp .env.example .env   # configure JWT_SECRET, optional: DATABASE_URL, payment keys
npm start               # http://localhost:5000
npm test                # jest + fast-check (7 suites, 43 tests)

Frontend

cd web_admin_panel/frontend
npm install
echo "VITE_API_BASE_URL=http://localhost:5000" > .env
npm run dev             # http://localhost:5173

Android

Requires JDK 21. The repo pins Gradle 9.3.1 (via the wrapper) and AGP 9.1.1 / Kotlin 2.2.10 / compileSdk 36.1; a .gitattributes enforces LF for gradlew, CRLF for *.bat, and binary for *.jar/*.zip/images to keep the Gradle wrapper from corrupting on Windows checkouts.

./gradlew assembleDebug   # uses the pinned wrapper (Gradle 9.3.1, JDK 21)
# APK: app/build/outputs/apk/debug/app-debug.apk
# Or open in Android Studio and run on device/emulator

MCP Server

cd mcp_server
npm install
node index.js           # stdio + ws://localhost:8765

Browser Extension

Chrome/Brave: Copy manifest.v3.json to manifest.json, open chrome://extensions, enable Developer mode, click Load unpacked, select browser_extension/.

Firefox: Copy manifest.v2.json to manifest.json, open about:debugging#/runtime/this-firefox, Load Temporary Add-on, select manifest.json.

Desktop Client

cd desktop_client
npm install
npm run tauri:dev       # requires Rust 1.77+ and Tauri CLI

See desktop_client/README.md for platform-specific build instructions (Windows .exe, macOS .dmg, Linux .AppImage/.deb).

Deployment

For full AWS production deployment (VPC, ECS Fargate, ALB with HTTPS/WSS, RDS, ElastiCache, S3+CloudFront, Route 53, WAF, GuardDuty, Cost Explorer), see DEPLOYMENT.md.

CI/CD runs via .github/workflows/deploy.yml on push to main. The Android jobs use ./gradlew on JDK 21 (temurin); the default (no-AWS) pipeline is verified green on main — APK build + frontend build + gh-pages publish.

The frontend builds to the gh-pages branch in CI. Public GitHub Pages hosting is not currently enabled (private repo; Pages not active on the plan) — the build artifact is produced and ready, but there is no live public URL yet.

Project Structure

LoraCon/
├── app/                              # Android client (Kotlin/Compose)
│   ├── src/main/java/com/example/    # Main source
│   └── src/test/java/com/example/    # Property-based tests (Kotest)
├── web_admin_panel/
│   ├── frontend/                     # React + Vite + Tailwind
│   │   └── src/
│   │       ├── pages/                # LandingPage, AdminPanel, DocsPage
│   │       ├── components/           # Reusable UI
│   │       └── services/api.js       # Centralized Axios layer
│   └── backend/                      # Node.js API server
│       ├── server.js                 # Entry point + all routes
│       ├── db.js                     # Data access layer (Prisma/JSON)
│       ├── finance.js                # Revenue + cost reporting
│       ├── prisma/schema.prisma      # PostgreSQL schema
│       ├── tests/                    # Property-based tests (jest/fast-check)
│       └── data/                     # JSON fallback storage (gitignored)
├── mcp_server/                       # MCP JSON-RPC server
│   └── index.js
├── browser_extension/                # Chrome MV3 / Firefox MV2
│   ├── manifest.v3.json
│   ├── manifest.v2.json
│   ├── background.js
│   └── popup/
├── desktop_client/                   # Rust + Tauri 2.x scaffold
│   ├── src-tauri/
│   │   ├── tauri.conf.json
│   │   ├── src/main.rs
│   │   └── src/vpn/
│   └── package.json
├── infrastructure/terraform/         # AWS IaC
│   ├── main.tf
│   ├── variables.tf
│   └── providers.tf
├── .github/workflows/deploy.yml      # CI/CD pipeline
├── .kiro/                            # Kiro steering, brain, specs, hooks
│   ├── brain/BRAIN.md
│   ├── steering/
│   ├── hooks/
│   ├── agents/
│   └── specs/
├── skills/                           # Agent skill definitions
├── DOCUMENTATION.md                  # Full API reference
├── DEPLOYMENT.md                     # AWS production guide
├── PROJECT_CONTEXT.md                # Architecture context
└── AGENTS.md                         # AI agent instructions

API Endpoints

Public

Method	Path	Description
`GET`	`/api/health`	Liveness probe (status + uptime)
`GET`	`/api/subscriptions/tiers`	List all subscription tiers with pricing
`GET`	`/api/auth/nonce?wallet=`	Issue nonce for wallet-based login
`POST`	`/api/auth/login`	Username/password login, returns JWT
`POST`	`/api/auth/register`	Create new user account (requires SUPERADMIN JWT)
`POST`	`/api/auth/refresh`	Exchange refresh token for new access token
`POST`	`/api/auth/wallet-login`	Solana wallet signature login
`POST`	`/api/auth/reset-password`	Password reset (auth + owner/SUPERADMIN + current-password proof)
`POST`	`/api/wishlist/submit`	Submit a Protocol Request — `{ name, email, service? }` → `{ success: true }` (rate-limited)

Protected (Bearer JWT)

Method	Path	Description
`GET`	`/api/admin/config`	System config + registered nodes
`POST`	`/api/admin/config/update`	Update pricing, limits, providers
`GET`	`/api/admin/sessions`	Active VPN sessions
`GET`	`/api/admin/servers`	Node pool for Android client
`POST`	`/api/admin/server/add`	Register new relay node
`DELETE`	`/api/admin/server/delete/:id`	Decommission node
`GET`	`/api/admin/finance/overview`	Revenue, costs, P&L summary
`GET`	`/api/admin/finance/export`	CSV report download
`GET`	`/api/admin/payment-methods`	List payment gateway toggles
`POST`	`/api/admin/payment-methods/toggle`	Enable/disable a gateway
`GET`	`/api/admin/payments/ledger`	Paginated transaction ledger
`GET`	`/api/admin/payments/revenue-breakdown`	Revenue by gateway and tier
`GET`	`/api/admin/subscriptions`	Paginated subscription list
`POST`	`/api/admin/privilege-keys/issue`	Issue VPN privilege key
`POST`	`/api/admin/privilege-keys/revoke`	Revoke privilege key
`GET`	`/api/admin/wishlist?page=`	Paginated Protocol Request submissions (SUPERADMIN only)
`POST`	`/api/payment/verify`	Verify Solana on-chain payment
`POST`	`/api/ai/chat`	AI proxy (Gemini/Grok)

Checkout & Webhooks

Method	Path	Description
`POST`	`/api/checkout/create`	Create checkout session (Stripe/PayPal/Paddle/crypto)
`POST`	`/api/webhooks/stripe`	Stripe webhook (signature verified)
`POST`	`/api/webhooks/paypal`	PayPal webhook (signature verified)
`POST`	`/api/webhooks/paddle`	Paddle webhook (signature verified)
`POST`	`/api/webhooks/crypto`	Crypto webhook (Coinbase/BTCPay, signature verified)

WebSocket

Protocol	Path	Description
`WS`	`/ws/telemetry`	Real-time node load/latency (5s broadcast)

Security

JWT auth, fails closed in prod -- short-lived access tokens (15 min), refresh tokens (7 days) in HttpOnly cookies (Secure in production, never echoed in the JSON body); access token stored in-memory only. In production a strong JWT_SECRET is required — the backend refuses to boot on a missing/default secret (no committed default)
No default-credential takeover -- removed the plaintext-login fallback and in-memory usersDB; auth is bcrypt-only via db.findUser. Production admin bootstrap password comes from ADMIN_BOOTSTRAP_PASSWORD (re-applied on boot)
Privileged account management -- /api/auth/register requires a SUPERADMIN JWT; /api/auth/reset-password requires auth and (owner or SUPERADMIN) and proof of the current password
PayPal webhook signature verification -- the PayPal verify-webhook-signature API is called (with PAYPAL_WEBHOOK_ID + transmission headers) before any DB write; returns 503 when creds are missing rather than granting access. Stripe (stripe-signature), Paddle (HMAC), and crypto (Coinbase HMAC) are likewise verified before any write
CORS allowlist -- pinned to the CORS_ORIGINS env allowlist; cross-origin requests are denied in production when no allowlist is configured (no origin:true reflection)
Solana payment amount check -- /api/payment/verify requires the treasury address to be credited >= expected lamports (net postBalances − preBalances), not merely present in accountKeys
AI proxy bounds -- /api/ai/chat validates and caps conversationHistory (≤30 messages, ≤4000 chars each) before forwarding upstream
Rate limiting -- express-rate-limit on all routes (auth + wishlist routes use the stricter auth limiter)
Input sanitization -- express-validator with HTML escape on all user input
bcrypt password hashing -- cost factor 12 via bcryptjs
WebRTC leak block -- browser extension disables non_proxied_udp when proxy is active
CSP headers -- Content Security Policy on desktop client restricting connect-src
No client-side secrets -- API keys centralized on backend; AI proxy routes mask credentials

Roadmap

Completed

Needs Credentials / Further Work

Connect live AWS Cost Explorer (requires AWS_ACCESS_KEY_ID)
Enable Stripe/PayPal/Paddle webhooks (requires production API keys)
Run prisma migrate with PostgreSQL (requires DATABASE_URL)
[~] Android WireGuard production handshake — userspace tunnel I/O done; encryption (Noise_IKpsk2 + ChaCha20) pending boringtun/wireguard-go via JNI + live node keys
Desktop client: implement platform WireGuard/kill-switch (requires Rust toolchain)
Multi-signature wallet support
Additional blockchain networks (Polygon, Arbitrum)
Machine learning node optimization

Environment Variables

All optional. The backend boots and serves with zero external credentials (JSON fallback mode).

Variable	Purpose
`JWT_SECRET`	JWT signing key. Dev default only; required (no default) in production — boot fails otherwise
`ADMIN_BOOTSTRAP_PASSWORD`	Production admin seed/bootstrap password (re-applied on boot; dev literal used only when unset)
`CORS_ORIGINS`	Comma-separated allowlist of permitted browser origins (pinned when set)
`PAYPAL_WEBHOOK_ID`	PayPal webhook ID for `verify-webhook-signature`; webhook returns 503 without it
`DATABASE_URL`	PostgreSQL connection (enables Prisma; otherwise JSON fallback)
`REDIS_URL`	Session cache (optional)
`STRIPE_SECRET_KEY`	Stripe payments
`STRIPE_WEBHOOK_SECRET`	Stripe webhook signature
`PAYPAL_CLIENT_ID` / `PAYPAL_SECRET`	PayPal payments
`PADDLE_API_KEY` / `PADDLE_WEBHOOK_SECRET`	Paddle payments
`COINBASE_COMMERCE_KEY` / `COINBASE_WEBHOOK_SECRET`	Crypto payments
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`	Cost Explorer + infrastructure
`SNS_TOPIC_ARN`	CloudWatch alert notifications
`AWS_COST_BUDGET_USD`	Monthly budget threshold
`GEMINI_API_KEY`	Google Gemini AI
`X_AI_GROK_API_KEY`	xAI Grok AI
`SOLANA_RPC_URL`	Solana RPC endpoint
`VITE_API_BASE_URL`	Frontend API base URL

Last updated: 2026-06-28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

LoraCon

📚 Documentation Map

Architecture

Components

Platform Coverage

Roadmap — additional platforms (suggested)

Feature Highlights

Quick Start

Backend

Frontend

Android

MCP Server

Browser Extension

Desktop Client

Deployment

Project Structure

API Endpoints

Public

Protected (Bearer JWT)

Checkout & Webhooks

WebSocket

Security

Roadmap

Completed

Needs Credentials / Further Work

Environment Variables

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
.claude		.claude
.github/workflows		.github/workflows
.kiro		.kiro
app		app
apple		apple
assets		assets
browser_extension		browser_extension
desktop_client		desktop_client
gradle		gradle
infrastructure/terraform		infrastructure/terraform
mcp_server		mcp_server
skills		skills
web_admin_panel		web_admin_panel
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
DEPLOYMENT.md		DEPLOYMENT.md
DOCUMENTATION.md		DOCUMENTATION.md
INSTRUCTIONS.md		INSTRUCTIONS.md
LICENSE		LICENSE
PROJECT_CONTEXT.md		PROJECT_CONTEXT.md
README.md		README.md
build.gradle.kts		build.gradle.kts
features.md		features.md
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
metadata.json		metadata.json
planning.md		planning.md
settings.gradle.kts		settings.gradle.kts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

LoraCon

📚 Documentation Map

Architecture

Components

Platform Coverage

Roadmap — additional platforms (suggested)

Feature Highlights

Quick Start

Backend

Frontend

Android

MCP Server

Browser Extension

Desktop Client

Deployment

Project Structure

API Endpoints

Public

Protected (Bearer JWT)

Checkout & Webhooks

WebSocket

Security

Roadmap

Completed

Needs Credentials / Further Work

Environment Variables

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages