Binance Airdrop Points Tracker

A Node.js/Express/PostgreSQL system for tracking daily trading activities and calculating points for Binance airdrop eligibility. The backend exposes RESTful APIs for record management and statistics, while the frontend is served from the `public/` directory.

Project Architecture

Backend Structure

**Main entry point:** `server.js`

**Database layer:** `models/database.js` (PostgreSQL, table: `transactions`)

**Frontend assets:** `public/` directory (HTML, CSS, JS)

API Endpoints

The backend exposes the following RESTful endpoints:

`GET /api/records/:date` — Fetch record by date

`POST /api/records` — Create/update record (upsert by date)

`PUT /api/records/:id` — Update record by ID (currently upserts by date)

`GET /api/stats/:year/:month` — Monthly statistics

`GET /api/records` — Fetch all records

`GET /api/health` — Health check

Data Flow

1. Frontend makes API requests to backend endpoints

2. Backend processes requests and interacts with PostgreSQL database

3. Database operations are handled through `models/database.js`

4. Responses follow standard format: `{ success, data, message }`

Instructions for AI Agent

1. Understanding the Codebase

When working with this project:

**Review `server.js`** for all API route definitions and request handling

**Check `models/database.js`** for database schema and all DB operations

**Examine `public/`** for frontend files that interact with the API

**Reference `env.example`** for required environment variables

2. Development Workflows

**Starting the server:**

Run `npm start` to start the server normally

Run `npm run dev` to start with nodemon for auto-reload

On Windows: use `start.bat` if present

On Linux/Mac: use `start.sh` if present

**Database setup:**

PostgreSQL connection configured via environment variables (see `env.example`)

Table auto-creates on server start via `initDatabase` in `models/database.js`

For manual setup, execute `init.sql`

Copy `env.example` to `.env` and fill in database credentials

**Docker deployment:**

Use `docker-compose.yml` or `docker-compose.dev.yml` for containerized setup

3. Project-Specific Patterns

**Upsert by date:**

All record creation/updates are keyed by `date` field

Database has unique constraint on `date` column

**API response format:**

Always return `{ success, data, message }` structure

Include `error` field when applicable

**Points calculation:**

Formula: `net_points = points_balance + points_trading - points_consumed`

Implement this calculation in API responses for statistics

**Error handling:**

Centralized error middleware in `server.js`

Returns generic message in production

Detailed errors only in development mode

**Static assets:**

Place all frontend files in `public/` directory

Backend automatically serves them at root route `/`

4. Adding New Features

**To add a new API endpoint:**

1. Define the route in `server.js` following existing patterns

2. Implement database logic in `models/database.js`

3. Follow the standard response format: `{ success, data, message }`

4. Add appropriate error handling

5. Test with the existing frontend or create new UI components in `public/`

**To modify database schema:**

1. Update the table structure in `models/database.js` (initDatabase function)

2. If needed, update `init.sql` for manual setup

3. Ensure existing API endpoints handle new fields appropriately

**To add frontend functionality:**

1. Add HTML/CSS/JS files to `public/` directory

2. Use fetch API to interact with backend endpoints

3. Handle responses in standard `{ success, data, message }` format

5. Key Constraints

PostgreSQL is required; ensure connection is properly configured

All records must have a unique `date` field

Environment variables must be set before starting the server

Frontend files must be placed in `public/` to be served correctly

6. Integration Points

**PostgreSQL database:** Configure via environment variables

**Docker support:** Use provided docker-compose files

**Environment config:** Use `.env` file based on `env.example`

7. Common Tasks

**Viewing records:**

Query `GET /api/records` for all records

Query `GET /api/records/:date` for specific date

**Creating/updating records:**

POST to `/api/records` with date and points data

System will upsert based on date

**Getting statistics:**

Query `GET /api/stats/:year/:month` for monthly aggregations

Examples

Example: Adding a Daily Summary Endpoint

```javascript

// In server.js

app.get('/api/summary/daily/:date', async (req, res) => {

try {

const { date } = req.params;

const summary = await getDailySummary(date);

res.json({ success: true, data: summary, message: 'Daily summary retrieved' });

} catch (error) {

res.status(500).json({ success: false, message: error.message });

}

});

// In models/database.js

async function getDailySummary(date) {

const result = await pool.query(

'SELECT * FROM transactions WHERE date = $1',

[date]

);

// Calculate net_points

const record = result.rows[0];

if (record) {

record.net_points = record.points_balance + record.points_trading - record.points_consumed;

}

return record;

}

```

Notes

Review existing patterns in `server.js` and `models/database.js` before making changes

Ask for clarification if any workflow or pattern is unclear

Maintain consistency with existing code style and response formats

Always test database operations with proper error handling

Binance Airdrop Points Tracker

Binance Airdrop Points Tracker

Project Architecture

Backend Structure

API Endpoints

Data Flow

Instructions for AI Agent

1. Understanding the Codebase

2. Development Workflows

3. Project-Specific Patterns

4. Adding New Features

5. Key Constraints

6. Integration Points

7. Common Tasks

Examples

Example: Adding a Daily Summary Endpoint

Notes

Reviews (0)