Node.js backend API and services for the Lumina Network — a blockchain-based vesting vault and token streaming platform on Stellar Soroban.
Lumina Backend provides the off-chain infrastructure powering the Lumina ecosystem. It includes a REST API, GraphQL endpoint, WebSocket server, job queue workers, Soroban integration services, and database management — all containerized for scalable deployment.
lumina-backend/
├── backend/ # Express.js REST API server
├── src/ # NestJS application services
│ ├── services/ # Business logic services
│ └── utils/ # Shared utilities
├── routes/ # API route definitions
├── workers/ # Background job workers
├── db/ # Database migrations and seeds
├── tests/ # Test suites
├── kubernetes/ # K8s deployment manifests
├── helm/ # Helm charts
├── scripts/ # Utility scripts
├── legacy_cleanup/ # Legacy migration tooling
├── docker-compose.yml # Local development setup
└── docker-compose-scalable.yml # Production-grade deployment
- REST API — Express.js server for vesting schedule management, claims processing, and administrative operations
- GraphQL API — Apollo GraphQL endpoint for flexible data queries
- WebSocket Server — Real-time event streaming via Socket.IO and NestJS WebSockets
- Soroban Integration — Stellar Soroban SDK client for on-chain contract interactions
- Background Workers — Bull/BullMQ job queue workers for async processing (vesting, Soroban indexer, PII scrubbing)
- Analytics — Off-chain vesting analytics and historical data aggregation
- Authentication — JWT-based auth with Passport.js and NestJS guards
- File Processing — CSV and xlsx report generation, file upload handling via Multer
- Notification System — SendGrid email integration
| Layer | Technology |
|---|---|
| Runtime | Node.js >= 20.11 |
| API Framework | Express.js + NestJS |
| GraphQL | Apollo Server |
| WebSockets | Socket.IO |
| Database | PostgreSQL + Knex migrations |
| Cache/Queue | Redis + BullMQ / Bull |
| Blockchain | Stellar SDK + Soroban Client |
| Auth | JWT + Passport.js |
| Storage | IPFS (web3.storage), Cloudinary, AWS S3 |
| Logging | Winston + Sentry |
| Payment | Stripe |
| Testing | Jest + Supertest |
| Deployment | Docker, Kubernetes, Helm |
| Documentation | Swagger (swagger-autogen + swagger-ui-express) |
- Node.js >= 20.11
- PostgreSQL
- Redis
npm install
cp .env.example .env
# Configure your environment variables
npm run migrate
npm run dev| Command | Description |
|---|---|
npm start |
Start Express API server |
npm run dev |
Start server with hot reload (nodemon) |
npm start:ws |
Start NestJS WebSocket server |
npm run worker |
Start background job worker |
npm run soroban |
Start Soroban indexer worker |
npm run test |
Run Jest test suite |
npm run migrate |
Run database migrations |
npm run docs |
Generate Swagger documentation |
API documentation is auto-generated via Swagger. After starting the server:
http://localhost:3000/api/docs
The project includes comprehensive deployment configurations:
# Docker Compose (development)
docker compose up
# Docker Compose (production-ready with scaling)
docker compose -f docker-compose-scalable.yml up
# Kubernetes
kubectl apply -f kubernetes/
# Helm
helm install lumina ./helm- lumina-frontend — Next.js web dashboard
- lumina-core — Soroban smart contracts