Xandeum pNode Analytics Platform

Backend — Real-time monitoring, analytics, and infrastructure for Xandeum pNodes.

A high-performance TypeScript backend for monitoring and analyzing Xandeum pNodes. Built with Fastify, PostgreSQL, Redis, and WebSocket support for real-time updates. Designed for production deployment with a RESTful API and a live dashboard frontend.

Live Demo: xandeum-analytics-board.vercel.app

Project Status

Aspect	Status
Backend API	Production-ready
Database Layer	PostgreSQL + Drizzle ORM
Real-time Monitoring	WebSocket live updates
Frontend Dashboard	Live at Vercel
Deployment	Render + Vercel (CI/CD)

---

What This Demonstrates

This project showcases skills in:

• Backend Engineering: RESTful API design with Fastify, request validation with Zod, rate limiting, and error handling
• Database Design: PostgreSQL schema design, migrations with Drizzle ORM, time-series data for historical tracking
• Real-time Systems: WebSocket-based live updates for monitoring dashboards
• Caching & Performance: Redis-backed caching layer for optimal query performance
• Scheduled Jobs: Cron-based data collection, cleanup, and alert checking
• DevOps: Dockerized deployment, environment configuration, CI/CD with Vercel and Render
• TypeScript: Full type safety across the codebase

Relevant job roles: Backend Engineer, Full Stack Developer, DevOps Engineer, Infrastructure Engineer

---

Screenshots

[Add a screenshot of the live dashboard here — e.g., assets/dashboard.png]

---

Features

• pNode Discovery: Automatically discovers pNodes from the Xandeum gossip network
• Pod Credits Integration: Fetches and tracks credits from podcredits.xandeum.network
• Credits Leaderboard: Rank pNodes by credits with historical tracking
• Uptime Tracking: Calculates and stores uptime percentage for each pNode
• Real-time Monitoring: WebSocket-based live updates for pNode status changes
• Historical Data: Stores and queries time-series metrics for trend analysis
• Alert System: Configurable alerts with threshold-based notifications
• Data Export: CSV and JSON export endpoints for analytics data
• Rate Limiting: Built-in API rate limiting for production use
• RESTful API: Comprehensive API for frontend integration
• Caching Layer: Redis-backed caching for optimal performance

---

Tech Stack

Component	Technology
Runtime	Node.js 20+
Language	TypeScript 5.x
Framework	Fastify 5.x
Database	PostgreSQL 16 + Drizzle ORM
Cache	Redis (ioredis)
Scheduler	node-cron
Validation	Zod
WebSocket	@fastify/websocket

---

Prerequisites

• Node.js 20+
• PostgreSQL 16+ (or Supabase free tier)
• Redis 7+ (optional, for caching)
• [pNode Setup (Without License)]: Instructions provided for local testing including creating a 10GB file and symlinking to /run/xandeum-pod

---

Database Setup

Supports Supabase (recommended for free tier) or local PostgreSQL.

• Supabase: Requires using the "Session Pooler" connection string for IPv4 networks and URL-encoding special characters in the password. Run npm run setup:db to initialize.
• Local: Run npm run setup:db or manually via createdb xandeum_analytics followed by migrations.

---

Installation

# 1. Clone the repository
git clone https://github.com/rootkit-io/Xandeum-backend.git
cd Xandeum-backend

# 2. Install dependencies
npm install

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your DATABASE_URL, REDIS_URL, PRPC_ENDPOINT, etc.

# 4. Initialize the database
npm run setup:db

# 5. Start development server
npm run dev

---

Running the Application

# Development mode (with hot reload)
npm run dev

# Production build
npm run build
npm start

---

API Reference

Category	Endpoints	Description
Health	GET /health, GET /health/prpc	Connectivity and service health checks
pNodes	GET /pnodes, GET /pnodes/:ip, GET /pnodes/:ip/stats, POST /pnodes/:ip/validate	List, details, stats history, IP validation
Statistics	GET /stats/overview, GET /stats/history, GET /stats/versions	Network overview, historical trends, version distribution
Alerts	CRUD endpoints for alerts	Create, read, update, delete threshold-based alerts
Leaderboard	GET /leaderboard/credits, GET /leaderboard/uptime	Ranked pNodes by credits and uptime
Export	GET /export/csv, GET /export/json	Data export endpoints for analytics

WebSocket API

Endpoint: ws://localhost:3000/ws

Event	Description
connected	Connection established
stats_updated	pNode statistics updated
nodes_discovered	New pNodes discovered
alert_triggered	Alert threshold exceeded

---

Project Structure

Xandeum-backend/
├── src/
│   ├── db/          # Database migrations and schema (Drizzle ORM)
│   ├── services/    # Business logic (pnode, stats, alerts)
│   ├── routes/      # API route handlers
│   ├── jobs/        # Scheduled collectors and cleanup tasks
│   ├── websocket/   # WebSocket event handlers
│   ├── types/       # TypeScript type definitions
│   └── index.ts     # Application entry point
├── scripts/         # Utility scripts (seed, migration, etc.)
├── docs/            # Documentation and API specs
├── frontend/        # Linked frontend dashboard
├── .env.example     # Environment variable template
├── drizzle.config.ts
├── package.json
└── README.md

---

Scheduled Jobs

Job	Interval	Purpose
Stats Poll	Every 30s	Collect pNode statistics
Discovery	Every 5m	Discover new pNodes from gossip network
Alert Check	Every 1m	Evaluate alert thresholds
Cleanup	Daily at 3 AM	Purge stale data and optimize database

---

Deployment

• Backend: Deployed on Render with auto-deploy on push to main
• Frontend Dashboard: Deployed on Vercel at xandeum-analytics-board.vercel.app
• Database: PostgreSQL via Supabase (free tier)
• Environment: Production-ready with .env configuration

---

License

MIT — see LICENSE for details.

---

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

---

Built by rootkit-io | Profile