# 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:
   ```bash
   cd backend
   ```

2. Install dependencies (already done):
   ```bash
   npm install
   ```

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

4. Start the development server:
   ```bash
   npm run dev
   ```

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

### Frontend Setup

1. Navigate to the frontend directory:
   ```bash
   cd frontend
   ```

2. Install dependencies (already done):
   ```bash
   npm install
   ```

3. Start the development server:
   ```bash
   npm run dev
   ```

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