Star Tracker

A family star reward tracking app. Parents award stars to kids for good behavior, and kids redeem stars for rewards. Built with Go, SQLite, and server-rendered HTML templates.

Screenshots

Login	Dashboard

Reward Translations	User & Reason Translations

Features

• Star awarding with configurable reasons and star counts (positive or negative)
• Reward redemption system with cost tracking
• Multi-language support (English, Simplified Chinese, Traditional Chinese)
• User management with parent/kid roles
• Home Assistant TTS integration for announcements
• REST API for external integrations (e.g. Home Assistant automations)
• Data import/export as JSON
• Single binary deployment with embedded templates and static assets

Build & Run

go build -o star-app .
./star-app -port 8080 -db stars.db

Flags

Cross-compile for ARM64 Linux

GOOS=linux GOARCH=arm64 go build -o star-app-arm64 .

Default Accounts

On first run with an empty database, four accounts are seeded:

Set STAR_APP_DEFAULT_PASSWORD before first startup if you want one fixed bootstrap password for all seeded accounts.

Accounts can be added and removed from the admin panel.

Architecture

Single-package Go application:

Templates are in templates/ and static assets in static/, both embedded into the binary via Go's embed package.

Authentication

Three authentication methods:

API keys are generated from the admin panel. The raw key is shown once at creation; only the SHA256 hash is stored.

REST API

All API endpoints require authentication via the X-API-Key header.

GET /api/users

Returns all users with their star counts.

Response:

[
  {
    "Username": "theo",
    "DisplayNameEN": "Theo",
    "DisplayNameCN": "西奥",
    "DisplayNameTW": "西奧",
    "StarCount": 42,
    "CurrentStars": 15,
    "IsAdmin": false
  }
]

GET /api/stars

Returns star award history with fully resolved translations for reasons, usernames, and awarder names.

Query Parameters:

Response:

[
  {
    "id": 1,
    "user_id": 3,
    "username": "theo",
    "username_en": "Theo",
    "username_cn": "西奥",
    "username_tw": "西奧",
    "reason_id": 2,
    "reason_text": "",
    "reason_en": "Cleaned room",
    "reason_cn": "打扫房间",
    "reason_tw": "打掃房間",
    "stars": 1,
    "awarded_by": 1,
    "awarded_by_name": "dad",
    "awarded_by_name_en": "Dad",
    "awarded_by_name_cn": "爸爸",
    "awarded_by_name_tw": "爸爸",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST /api/stars

Award stars to a user. Supports both predefined reasons (by ID) and custom text reasons — consistent with the web UI.

Request Body (JSON):

{
  "username": "theo",
  "reason_id": 2,
  "reason": "Cleaned room",
  "stars": 2
}

When reason_id is provided:

• The reason's configured star count is used unless stars is explicitly set
• Translations are linked automatically
• HA announcements use the translated reason text

Response:

{
  "status": "ok",
  "counts": [{"Username": "theo", "CurrentStars": 17, ...}],
  "starId": 42
}

Errors:

GET /api/reasons

Returns all predefined star reasons with translations and usage counts.

Response:

[
  {
    "ID": 1,
    "Key": "cleaned_room",
    "Translations": {
      "en": "Cleaned room",
      "zh-CN": "打扫房间",
      "zh-TW": "打掃房間"
    },
    "Count": 15,
    "Stars": 1
  }
]

GET /api/rewards

Returns all configured rewards with translations.

Response:

[
  {
    "ID": 1,
    "Name": "Ice cream outing",
    "Cost": 8,
    "Icon": "🍦",
    "Translations": {
      "en": "Ice cream outing",
      "zh-CN": "冰淇淋外出",
      "zh-TW": "冰淇淋外出"
    }
  }
]

GET /api/redemptions

Returns redemption history.

Query Parameters:

Response:

[
  {
    "ID": 1,
    "UserID": 3,
    "Username": "theo",
    "UsernameEN": "Theo",
    "UsernameCN": "西奥",
    "UsernameTW": "西奧",
    "RewardName": "Ice cream outing",
    "RewardNameEN": "Ice cream outing",
    "RewardNameCN": "冰淇淋外出",
    "RewardNameTW": "冰淇淋外出",
    "Cost": 8,
    "CreatedAt": "2025-01-15T14:00:00Z"
  }
]

Admin Web API

These endpoints require session authentication with admin privileges. They are used by the admin panel's JavaScript and can also be called programmatically.

POST /star

Award a star from the web UI. Supports both form submission and JSON response.

Form Data:

Set Accept: application/json header to receive JSON instead of a redirect:

{
  "counts": [{"Username": "theo", "CurrentStars": 16, ...}],
  "awardedBy": "dad",
  "starId": 42
}

POST /redeem

Redeem a reward. Set Accept: application/json for JSON response.

Form Data:

JSON Response:

{
  "counts": [{"Username": "theo", "CurrentStars": 6, ...}],
  "rewardName": "Ice cream outing",
  "cost": 8
}

Errors: Returns plain text — "user not found", "reward not found", or "{name} doesn't have enough stars (has X, needs Y)".

DELETE /star/{id}

Remove a star record. Cannot delete your own stars.

Response: JSON array of updated user star counts.

DELETE /redemption/{id}

Remove a redemption record. Cannot delete your own redemptions.

Response: JSON array of updated user star counts.

PUT /admin/reason/{id}

Update a reason's translation or star count.

Form Data:

Response: {"status": "ok"}

DELETE /admin/reason/{id}

Delete a reason and all its translations.

Response: {"status": "ok"}

PUT /admin/reward/{id}

Update a reward's translation or cost.

Form Data:

Response: {"status": "ok"}

DELETE /admin/reward/{id}

Delete a reward.

Response: HTTP 200

PUT /admin/user/{id}

Update a user's display name translation.

Form Data:

Response: {"status": "ok"}

DELETE /admin/user/{id}

Delete a user and all associated data (stars, redemptions, sessions, translations). Cannot delete your own account.

Response: HTTP 200

POST /admin/toggle-announce

Toggle Home Assistant announcements on/off.

Response:

{"ha_enabled": "1"}

GET /admin/export

Download all application data as JSON.

Response: application/json file attachment (star-app-export.json).

Exported data includes: users (without password hashes), stars, reasons, rewards, redemptions, and settings.

POST /admin/import

Import previously exported JSON data. Replaces all existing stars, reasons, rewards, and redemptions.

Form Data: Multipart file upload with field name file (accepts .json).

Home Assistant Integration

Configure from the admin panel under "Home Assistant Announce":

1. Enable announcements
2. Set your Home Assistant TTS URL (e.g., https://home.example.com/api/services/tts/microsoft_say)
3. Set a Long-Lived Access Token (generate from HA user profile)
4. Set the media player entity (e.g., media_player.living_room)
5. Choose the announcement language

When a star is awarded, the app calls Home Assistant's TTS service to announce it. Positive and negative stars get different messages: