Events Logger

A self-hosted event tracking and visualization dashboard. Track events from your applications -- signups, orders, deploys, payments -- and visualize them in a clean, real-time dashboard.

Built with the AHA stack: Astro + HTMX + Alpine.js.

Project documentation

The package includes BUILDING.md, a detailed guide to how I built the software, the order I followed, the difficult parts, the verification process, and what I would change next. It also includes architecture, decisions, customization, deployment, configuration, security, and AI-agent guides.

Quick Start

npm install
npm run dev

Open http://localhost:4321, create a project, and start pushing events. Your global API key is displayed on the home page.

Push Your First Event

Create a project via the CLI:

node cli/index.js init --api-key ev_your-key-here --name "my-app"

Push an event:

node cli/index.js push \
  --api-key ev_your-key-here \
  --project q4q8nb18qc2i \
  --category signups \
  --title "User Registered" \
  --description "New user **[email protected]** signed up" \
  --icon "👤" \
  --user-id "user-123"

Or use the API directly:

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key-here" \
  -d '{
    "project": "q4q8nb18qc2i",
    "category": "orders",
    "title": "Order Placed",
    "description": "Order **#1234** placed by **Maria**",
    "icon": "🛍️",
    "user_id": "user-456",
    "tags": {"email": "[email protected]", "amount": "$89.99"}
  }'

Or use the built-in Playground page to test events interactively with a form and live code preview.

API Integration

The app uses a single global API key (shown on the home page). All write endpoints require this key in the Authorization header and a project ID in the request body.

JavaScript / Node.js

await fetch("http://localhost:4321/api/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ev_your-key-here",
  },
  body: JSON.stringify({
    project: "q4q8nb18qc2i",
    category: "signups",
    title: "User Registered",
    description: "New user **[email protected]** signed up",
    icon: "👤",
    user_id: "user-123",
    tags: { plan: "pro", source: "google" },
  }),
});

Python

import requests

requests.post("http://localhost:4321/api/events", json={
    "project": "q4q8nb18qc2i",
    "category": "payments",
    "title": "Payment Received",
    "description": "**$49.99** from user-456",
    "icon": "💰",
    "user_id": "user-456",
    "tags": {"amount": "49.99", "currency": "USD"},
}, headers={
    "Authorization": "Bearer ev_your-key-here",
})

Event Fields

See API.md for the full API documentation with examples in JavaScript, Python, PHP, Ruby, and Go, plus integration patterns for Stripe webhooks, CI/CD pipelines, and more.

Features

• Feed -- chronological event stream with live search, auto-refresh, and browser notifications
• Charts -- bar charts showing event frequency per category over time
• Insights -- KPI dashboard cards for real-time metrics
• Playground -- interactive form to test event publishing with live code preview
• Categories -- auto-created groupings to organize events
• User tracking -- associate events with user IDs via the user_id field
• Favorites -- mark events as favorites and filter the feed to show only starred items
• Search -- filter events by title, description, or tags
• Delete -- remove individual events or insight cards from the dashboard
• Settings -- project info, rename, delete project
• CLI -- command-line tool to push events and manage projects
• REST API -- JSON API for integration with any service
• Export/Import -- export all data to JSON, load demo scenarios or backups
• Demo scenarios -- 4 pre-built scenarios with 1800+ events for presentations
• Responsive -- mobile-friendly layout with collapsible sidebar

Tech Stack

• Astro 5 (SSR mode with Node adapter) -- pages, layouts, API routes
• HTMX -- live feed updates, search, polling without page reloads
• Alpine.js -- dropdowns, toggles, sidebar, playground interactivity
• SQLite via better-sqlite3 -- local database, zero configuration
• Drizzle ORM -- type-safe schema and queries
• Chart.js -- bar charts on the charts page
• Commander -- CLI tool

Project Structure

See docs/architecture.md for the full project layout and component descriptions.

API Reference

See API.md for complete API documentation with code examples in multiple languages.

See docs/api.md for the endpoint reference in compact form.

CLI Reference

See CLI.md for all commands and options.

Database

See docs/database.md for the schema, tables, and indexes.

Demo Scenarios

Load pre-built demo data to showcase the app without using personal data:

# Load all 4 scenarios (1800+ events across 30 days)
node cli/index.js load --file demos/all-scenarios.json

# Load a single scenario
node cli/index.js load --file demos/ecommerce.json

# Export your current data first (backup)
node cli/index.js export --file my-backup.json

# Regenerate fresh random demo data
node demos/generate.js

See demos/WALKTHROUGH.md for a full presentation script.

Roadmap

See docs/roadmap.md for planned features.

Use Cases

• E-commerce -- user registrations, cart events, orders, shipping, reviews
• SaaS -- signups, trial conversions, subscription changes, feature usage
• CI/CD -- build status, deploys, test results, rollbacks
• Content platforms -- posts published, comments, subscriber growth
• Indie projects -- waitlist signups, feedback, revenue milestones

Scripts

License

MIT

Events Dashboard exposes a REST API that any application can use to push events, update metrics, and query data. All responses are JSON.

Base URL: http://localhost:4321 (or wherever you deploy the app)

Quick Start

# 1. Create a project (requires API key)
curl -X POST http://localhost:4321/api/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-api-key" \
  -d '{"name": "my-app"}'

# Response: {"id": "q4q8nb18qc2i", "name": "my-app"}

# 2. Push an event
curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-api-key" \
  -d '{"project": "q4q8nb18qc2i", "category": "signups", "title": "User Registered", "icon": "👤"}'

# 3. Query events
curl "http://localhost:4321/api/events?project=q4q8nb18qc2i"

Authentication

All write endpoints (POST /api/events, POST /api/insight, POST /api/projects) require the global API key in the Authorization header:

Authorization: Bearer ev_your-api-key-here

A single API key is auto-generated when the app starts for the first time. It is displayed on the home page. The key is prefixed with ev_ and looks like ev_pf7au9f9-sb8r-aa2w-eog8-sw42acp7m4bj.

Read-only endpoints (GET /api/events, GET /api/projects, GET /api/charts) do not require authentication.

Endpoints

POST /api/projects

Create a new project. Requires authentication.

Body:

Example:

curl -X POST http://localhost:4321/api/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-api-key" \
  -d '{"name": "my-saas-app"}'

Response 201:

{
  "id": "q4q8nb18qc2i",
  "name": "my-saas-app"
}

Errors:

GET /api/projects

List all projects.

curl http://localhost:4321/api/projects

Response 200:

[
  {
    "id": "q4q8nb18qc2i",
    "name": "my-saas-app",
    "createdAt": "2026-02-27T08:00:00.000Z"
  }
]

POST /api/events

Push an event. Requires authentication.

Body:

Response 201:

{
  "id": 42,
  "projectId": "q4q8nb18qc2i",
  "category": "orders",
  "title": "Order Placed",
  "description": "Order **#1234** placed by **Maria**",
  "icon": "🛍️",
  "tags": "{\"email\":\"[email protected]\",\"amount\":\"$89.99\"}",
  "url": "https://shop.example.com/admin/orders/1234",
  "userId": "user-456",
  "notify": false,
  "favorited": false,
  "createdAt": "2026-02-27T08:12:03.000Z"
}

Errors:

Examples by Use Case

User signup:

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{
    "project": "q4q8nb18qc2i",
    "category": "signups",
    "title": "User Registered",
    "description": "New user **[email protected]** signed up via Google OAuth",
    "icon": "👤",
    "user_id": "usr_abc123",
    "tags": {"email": "[email protected]", "source": "google", "plan": "free"}
  }'

Payment received:

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{
    "project": "q4q8nb18qc2i",
    "category": "payments",
    "title": "Payment Received",
    "description": "**$49.99** payment from user-456 for Pro plan",
    "icon": "💰",
    "url": "https://dashboard.stripe.com/payments/pi_abc123",
    "user_id": "user-456",
    "notify": true,
    "tags": {"amount": "49.99", "currency": "USD", "plan": "pro"}
  }'

Deploy completed:

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{
    "project": "q4q8nb18qc2i",
    "category": "deploys",
    "title": "Deploy Succeeded",
    "description": "Version **v2.4.1** deployed to production in 43s",
    "icon": "🚀",
    "tags": {"version": "v2.4.1", "environment": "production", "duration": "43s"}
  }'

Error alert:

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{
    "project": "q4q8nb18qc2i",
    "category": "errors",
    "title": "500 Internal Server Error",
    "description": "Unhandled exception in **/api/checkout**: NullPointerException",
    "icon": "🔴",
    "url": "https://sentry.io/issues/ERR-78901",
    "notify": true,
    "tags": {"endpoint": "/api/checkout", "status": "500", "count": "12"}
  }'

Subscription change:

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{
    "project": "q4q8nb18qc2i",
    "category": "billing",
    "title": "Plan Upgraded",
    "description": "**Maria** upgraded from Free to **Pro** plan",
    "icon": "⬆️",
    "user_id": "user-456",
    "tags": {"from": "free", "to": "pro", "mrr_change": "+49.99"}
  }'

Minimal event (only required fields):

curl -X POST http://localhost:4321/api/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{"project": "q4q8nb18qc2i", "category": "logs", "title": "Cron job completed"}'

GET /api/events

Query events for a project. Supports filtering, search, and cursor-based pagination.

Query parameters:

Get all events:

curl "http://localhost:4321/api/events?project=q4q8nb18qc2i"

Filter by category:

curl "http://localhost:4321/api/events?project=q4q8nb18qc2i&category=payments"

Search events:

curl "http://localhost:4321/api/events?project=q4q8nb18qc2i&search=maria"

Paginate through results:

# First page
curl "http://localhost:4321/api/events?project=q4q8nb18qc2i&limit=10"
# Response includes "nextCursor": 35

# Next page
curl "http://localhost:4321/api/events?project=q4q8nb18qc2i&limit=10&cursor=35"
# Response includes "nextCursor": 22

# Keep going until nextCursor is null

Response 200:

{
  "events": [
    {
      "id": 42,
      "projectId": "q4q8nb18qc2i",
      "category": "signups",
      "title": "User Registered",
      "description": "New user **[email protected]** signed up",
      "icon": "👤",
      "tags": "{\"email\":\"[email protected]\",\"source\":\"google\"}",
      "userId": "usr_abc123",
      "notify": false,
      "createdAt": "2026-02-27T08:12:03.000Z"
    }
  ],
  "nextCursor": 41
}

nextCursor is null when there are no more results.

Errors:

POST /api/events/:eventId/delete

Delete an event by ID. No authentication required.

Example:

curl -X POST http://localhost:4321/api/events/42/delete

Response 200:

{ "id": 42, "deleted": true }

Errors:

POST /api/events/:eventId/favorite

Toggle the favorite status of an event. No authentication required.

Example:

curl -X POST http://localhost:4321/api/events/42/favorite

Response 200:

{ "id": 42, "favorited": true }

Errors:

POST /api/insight

Create or update an insight card (a KPI metric displayed on the dashboard). Requires authentication.

Insights are upserted by project + title: if an insight with the same title already exists, its value is updated. This makes it easy to keep metrics current by re-posting with the latest value.

Body:

Examples:

# Total revenue
curl -X POST http://localhost:4321/api/insight \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{"project": "q4q8nb18qc2i", "title": "Total Revenue", "value": "$12,340", "icon": "💰"}'

# Active users
curl -X POST http://localhost:4321/api/insight \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{"project": "q4q8nb18qc2i", "title": "Active Users", "value": 1284, "icon": "👥"}'

# Conversion rate
curl -X POST http://localhost:4321/api/insight \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{"project": "q4q8nb18qc2i", "title": "Conversion Rate", "value": "3.2%", "icon": "📈"}'

# Update an existing insight (same title = update)
curl -X POST http://localhost:4321/api/insight \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ev_your-key" \
  -d '{"project": "q4q8nb18qc2i", "title": "Total Revenue", "value": "$13,500", "icon": "💰"}'

Response 200:

{ "ok": true }

Errors:

POST /api/insight/:insightId/delete

Delete an insight by ID. No authentication required. Redirects (303) to the insight-grid partial.

Example:

curl -X POST http://localhost:4321/api/insight/5/delete?project=q4q8nb18qc2i

Errors:

GET /api/charts

Get event counts grouped by category and day. Used to render bar charts on the dashboard.

Query parameters:

Examples:

# All categories, last 30 days
curl "http://localhost:4321/api/charts?project=q4q8nb18qc2i"

# Last 7 days
curl "http://localhost:4321/api/charts?project=q4q8nb18qc2i&days=7"

# Single category
curl "http://localhost:4321/api/charts?project=q4q8nb18qc2i&category=signups"

Response 200:

{
  "orders": [
    { "day": "2026-02-25", "count": 5 },
    { "day": "2026-02-26", "count": 8 },
    { "day": "2026-02-27", "count": 3 }
  ],
  "signups": [
    { "day": "2026-02-25", "count": 2 },
    { "day": "2026-02-26", "count": 4 },
    { "day": "2026-02-27", "count": 1 }
  ]
}

Errors:

Language Examples

JavaScript / Node.js

const API_URL = "http://localhost:4321";
const API_KEY = "ev_your-key-here";

// Push an event
const res = await fetch(`${API_URL}/api/events`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    project: "q4q8nb18qc2i",
    category: "signups",
    title: "User Registered",
    description: "New user **[email protected]** signed up",
    icon: "👤",
    user_id: "user-123",
    tags: { plan: "pro", source: "google" },
  }),
});

const event = await res.json();
console.log("Created event:", event.id);

// Query events
const res = await fetch(
  `${API_URL}/api/events?project=q4q8nb18qc2i&category=signups&limit=10`
);
const { events, nextCursor } = await res.json();

// Update an insight
await fetch(`${API_URL}/api/insight`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    project: "q4q8nb18qc2i",
    title: "Total Users",
    value: 1284,
    icon: "👥",
  }),
});

Python

import requests

API_URL = "http://localhost:4321"
API_KEY = "ev_your-key-here"
HEADERS = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}",
}

# Push an event
response = requests.post(f"{API_URL}/api/events", json={
    "project": "q4q8nb18qc2i",
    "category": "payments",
    "title": "Payment Received",
    "description": "**$49.99** from user-456",
    "icon": "💰",
    "user_id": "user-456",
    "tags": {"amount": "49.99", "currency": "USD"},
}, headers=HEADERS)

event = response.json()
print(f"Created event: {event['id']}")

# Query events
response = requests.get(f"{API_URL}/api/events", params={
    "project": "q4q8nb18qc2i",
    "category": "payments",
    "limit": 20,
})
data = response.json()
for event in data["events"]:
    print(f"{event['title']} - {event['createdAt']}")

# Update an insight
requests.post(f"{API_URL}/api/insight", json={
    "project": "q4q8nb18qc2i",
    "title": "Monthly Revenue",
    "value": "$12,340",
    "icon": "💰",
}, headers=HEADERS)

PHP

$apiUrl = "http://localhost:4321";
$apiKey = "ev_your-key-here";

// Push an event
$ch = curl_init("$apiUrl/api/events");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer $apiKey",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "project" => "q4q8nb18qc2i",
        "category" => "orders",
        "title" => "Order Placed",
        "description" => "Order **#1234** for **$89.99**",
        "icon" => "🛍️",
        "user_id" => "user-456",
        "tags" => ["amount" => "89.99", "product" => "Widget Pro"],
    ]),
]);

$response = curl_exec($ch);
$event = json_decode($response, true);
curl_close($ch);

Ruby

require "net/http"
require "json"

api_url = "http://localhost:4321"
api_key = "ev_your-key-here"

uri = URI("#{api_url}/api/events")
http = Net::HTTP.new(uri.host, uri.port)

request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer #{api_key}"
request.body = {
  project: "q4q8nb18qc2i",
  category: "signups",
  title: "User Registered",
  description: "New user **[email protected]** signed up",
  icon: "👤",
  user_id: "user-789",
  tags: { email: "[email protected]", plan: "starter" }
}.to_json

response = http.request(request)
event = JSON.parse(response.body)
puts "Created event: #{event['id']}"

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "project":     "q4q8nb18qc2i",
        "category":    "deploys",
        "title":       "Deploy Succeeded",
        "description": "Version **v2.4.1** deployed to production",
        "icon":        "🚀",
        "tags":        map[string]string{"version": "v2.4.1", "env": "production"},
    })

    req, _ := http.NewRequest("POST", "http://localhost:4321/api/events", bytes.NewBuffer(payload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer ev_your-key-here")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Status:", resp.StatusCode)
}

Integration Patterns

Track signups from your auth system

Call the API after a user registers:

async function onUserRegistered(user) {
  await fetch("http://localhost:4321/api/events", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer ev_your-key",
    },
    body: JSON.stringify({
      project: "q4q8nb18qc2i",
      category: "signups",
      title: "User Registered",
      description: `**${user.email}** signed up`,
      icon: "👤",
      user_id: user.id,
      tags: { email: user.email, provider: user.authProvider },
    }),
  });
}

Track payments from Stripe webhooks

app.post("/webhooks/stripe", async (req, res) => {
  const event = req.body;

  if (event.type === "checkout.session.completed") {
    const session = event.data.object;
    await fetch("http://localhost:4321/api/events", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer ev_your-key",
      },
      body: JSON.stringify({
        project: "q4q8nb18qc2i",
        category: "payments",
        title: "Payment Received",
        description: `**$${(session.amount_total / 100).toFixed(2)}** from **${session.customer_email}**`,
        icon: "💰",
        notify: true,
        user_id: session.client_reference_id,
        tags: {
          amount: (session.amount_total / 100).toFixed(2),
          currency: session.currency,
          stripe_session: session.id,
        },
      }),
    });
  }

  res.sendStatus(200);
});

Track deploys from CI/CD

Add to your GitHub Actions workflow:

- name: Track deploy
  run: |
    curl -X POST ${{ secrets.EVENTS_DASHBOARD_URL }}/api/events \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${{ secrets.EVENTS_API_KEY }}" \
      -d '{
        "project": "${{ secrets.EVENTS_PROJECT_ID }}",
        "category": "deploys",
        "title": "Deploy to Production",
        "description": "Commit **${{ github.sha }}** by **${{ github.actor }}**",
        "icon": "🚀",
        "tags": {
          "commit": "${{ github.sha }}",
          "branch": "${{ github.ref_name }}",
          "actor": "${{ github.actor }}",
          "run": "${{ github.run_id }}"
        }
      }'

Update dashboard KPIs on a schedule

Run a cron job to keep insight cards current:

#!/bin/bash
API_KEY="ev_your-key-here"
URL="http://localhost:4321"

# Fetch counts from your database and post as insights
TOTAL_USERS=$(psql -t -c "SELECT count(*) FROM users")
MRR=$(psql -t -c "SELECT sum(amount) FROM subscriptions WHERE status='active'")

curl -s -X POST "$URL/api/insight" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d "{\"project\": \"q4q8nb18qc2i\", \"title\": \"Total Users\", \"value\": \"$TOTAL_USERS\", \"icon\": \"👥\"}"

curl -s -X POST "$URL/api/insight" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d "{\"project\": \"q4q8nb18qc2i\", \"title\": \"MRR\", \"value\": \"\$$MRR\", \"icon\": \"💰\"}"

Notes

• Categories are auto-created. The first time you push an event with a new category name, the category is created automatically. No setup needed.
• Insights upsert by title. Posting an insight with the same title updates the existing value instead of creating a duplicate.
• Tags are stored as JSON. They're searchable via the search parameter on GET /api/events.
• Descriptions support markdown. Use **bold** and [link text](url) in descriptions for richer display in the dashboard.
• Pagination is cursor-based. Use nextCursor from the response as the cursor parameter in the next request. This is more reliable than offset-based pagination.
• Rate limits: None. This is a self-hosted app, so you control the infrastructure.

The CLI is at cli/index.js. The init, push, and insight commands require the dashboard server to be running. The export and load commands talk directly to the SQLite database and work without the server.

node cli/index.js <command> [options]

Server-dependent commands accept --url <url> to point to a different server (default: http://localhost:4321).

Commands

init

Create a new project.

node cli/index.js init --api-key ev_your-key --name "my-store"

push

Push an event to a project.

node cli/index.js push \
  --api-key ev_your-key \
  --project q4q8nb18qc2i \
  --category orders \
  --title "Order Placed" \
  --description "Order **#1234** by John" \
  --icon "📦" \
  --user-id "user-123" \
  --tags '{"email":"[email protected]"}'

insight

Create or update an insight KPI card.

node cli/index.js insight \
  --api-key ev_your-key \
  --project q4q8nb18qc2i \
  --title "Online Users" \
  --value 28 \
  --icon "🔴"

export

Export all data (projects, categories, events, insights) to a JSON file. Does not require the server to be running — reads directly from SQLite.

node cli/index.js export --file backup.json

load

Load data from a JSON file. Replaces all existing data by default. Does not require the server — writes directly to SQLite. Restart the dev server after loading.

node cli/index.js load --file demos/ecommerce.json

Demo Scenarios

Pre-built demo scenarios are in demos/. Each contains realistic data spanning 30 days.

# Load all demo data
node cli/index.js load --file demos/all-scenarios.json

# Load just one scenario
node cli/index.js load --file demos/ecommerce.json

# Regenerate random demo data
node demos/generate.js

See demos/WALKTHROUGH.md for a full presentation script.

Examples

Track an e-commerce order flow:

API_KEY="ev_your-key"
PROJECT="q4q8nb18qc2i"

node cli/index.js push --api-key $API_KEY --project $PROJECT --category signups --title "User Registered" --icon "👤" --user-id "user-42"
node cli/index.js push --api-key $API_KEY --project $PROJECT --category orders --title "Order Placed" --description "Order **#1001**" --icon "🛍️" --user-id "user-42"
node cli/index.js push --api-key $API_KEY --project $PROJECT --category shipping --title "Order Shipped" --icon "🚚"
node cli/index.js push --api-key $API_KEY --project $PROJECT --category shipping --title "Order Delivered" --icon "📦"

node cli/index.js insight --api-key $API_KEY --project $PROJECT --title "24h Sales" --value "\$1,449" --icon "☀️"
node cli/index.js insight --api-key $API_KEY --project $PROJECT --title "Orders Processing" --value 23 --icon "🏭"

Track CI/CD deploys:

node cli/index.js push --api-key $API_KEY --project $PROJECT --category deploys --title "Deploy Succeeded" --description "v2.4.1 to production" --icon "🚀"
node cli/index.js insight --api-key $API_KEY --project $PROJECT --title "Deploys Today" --value 5 --icon "📊"

Events Logger uses Astro, HTMX, Alpine.js, SQLite, Drizzle ORM, and Commander.

Main areas

• src/pages/api/ receives and validates incoming events.
• src/pages/ renders dashboards and HTMX partials.
• src/db/ and Drizzle files own the schema and persistence.
• cli/ provides terminal commands for creating projects and pushing events.

Change flow

Start from the user-facing route or command, follow its call into the domain or data module, change the narrowest responsible layer, and verify the result with the commands in README.md. Keep external-service calls behind existing server or integration boundaries.