Koin Ping

A lightweight on-chain monitoring and alerting system designed to give users situational awareness over blockchain addresses they care about.

Overview

Koin Ping is designed to reliably observe on-chain activity and notify users when predefined conditions are met. It does not execute transactions, manage wallets, or speculate on prices.

Project Structure

koin_ping/
├── backend/                  # Node.js + Express + PostgreSQL backend
│   ├── api/                 # API endpoints and server configuration
│   ├── poller/              # Blockchain polling logic
│   ├── alerts/              # Alert evaluation and management
│   ├── notifications/       # Notification delivery system
│   ├── domain/              # Domain models and business logic
│   ├── infra/               # Infrastructure (database, external services)
│   └── shared/              # Shared utilities and helpers
│
└── frontend/                 # React + Vite frontend
    ├── public/              # Static assets
    └── src/
        ├── api/             # Frontend API calls to backend
        ├── components/      # Reusable UI components
        ├── pages/           # Top-level pages (views)
        └── utils/           # Utility functions

Tech Stack

Backend

• Runtime: Node.js
• Framework: Express
• Database: PostgreSQL
• Key Dependencies:
  • pg - PostgreSQL client
  • dotenv - Environment variable management
  • cors - CORS middleware
  • nodemon - Development auto-reload

Frontend

• Framework: React 19
• Build Tool: Vite
• Language: JavaScript/TypeScript (mixed)
• Type Checking: TypeScript

Getting Started

Prerequisites

• Node.js (v18 or higher recommended)
• PostgreSQL database
• npm or yarn

Backend Setup

1. Navigate to the backend directory:

   cd backend
   

2. Install dependencies (already done):

   npm install
   

3. Create a .env file (see backend/README.md for required variables)

4. Start the development server:

   npm run dev
   

The backend will run on http://localhost:3001

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend
   

2. Install dependencies (already done):

   npm install
   

3. Start the development server:

   npm run dev
   

The frontend will run on http://localhost:3000