Skip to content

AGENTS.md

Latest commit

 

History

History
81 lines (65 loc) · 4.19 KB

AGENTS.md

File metadata and controls

81 lines (65 loc) · 4.19 KB

AGENTS.md

Project Overview

This project is the Tronbyt Server, a Go-based application which manages Tronbyt devices (flashed Tidbyts) locally, providing a web UI and API for app management and rendering.

The core functionality involves serving WebP images to devices, generated by rendering Pixlet apps (Starlark scripts). The server integrates with the native Go pixlet library.

Key Technologies

  • Language: Go 1.26+
  • Web Framework: Standard Library net/http with ServeMux (Go 1.22+ routing features).
  • Database: SQLite/Postgres/MySQL with GORM (ORM). Data is stored in a relational schema (Users, Devices, Apps).
  • Templating: html/template (standard library).
  • Rendering: Native Go integration with github.com/tronbyt/pixlet.
  • Authentication: Session-based (secure cookies via gorilla/sessions) with Argon2id password hashing. WebAuthn/passkey support via go-webauthn.
  • Internationalization: go-i18n (JSON translation files).
  • Monitoring: Prometheus metrics via prometheus/client_golang (application metrics + GORM database stats).

Project Structure

  • cmd/boot/: Entry point for containers.
  • cmd/server/: Main entry point for the server binary.
  • cmd/migrate/: Tool to migrate legacy SQLite databases to the new schema.
  • internal/apps/: App metadata and discovery.
  • internal/auth/: Authentication logic (password hashing).
  • internal/config/: Configuration loading (env vars).
  • internal/data/: Data models and GORM setup.
  • internal/firmware/: Device firmware generation.
  • internal/gitutils/: Utilities for git operations (apps repositories).
  • internal/legacy/: Helpers for reading legacy Python-based data structures.
  • internal/migration/: Migration tooling from earlier versions.
  • internal/renderer/: Pixlet rendering integration.
  • internal/server/: HTTP handlers, middleware, routing, and business logic.
  • internal/sync/: Event hub for websockets.
  • internal/version/: Version information.
  • web/i18n/: Translation files (e.g., de.json).
  • web/static/: Static assets (CSS, JS, images).
  • web/templates/: HTML templates.

Building and Running

Local Development

  1. Dependencies: Ensure Go 1.26+ and C build tools (gcc) are installed.
  2. Run with go run (for development): 
    go run ./cmd/server -db data/tronbyt.db -data .
  3. Build and Run (for production/deployment): 
    go build -o tronbyt-server ./cmd/server
./tronbyt-server -db data/tronbyt.db -data .

Testing

  1. go test ./...

Docker

  1. Build: 
    docker build -t tronbyt-server .
  2. Run: 
    docker run -p 8000:8000 -v $(pwd)/data:/app/data tronbyt-server

Development Conventions

  • Formatting: Use go fmt ./... for Go and djlint --profile=golang --reformat for HTML templates.
  • Linting: Use golangci-lint run for Go and djlint --profile=golang --lint for HTML templates.
  • Pre-commit hooks: The repository uses pre-commit hooks that automatically run go fmt, go test, golangci-lint, and djlint on commit.
  • Logging: Use log/slog for structured logging.
  • Templates: Use {{ t .Localizer "MessageID" }} for translated strings.
  • Database: Use GORM for DB interactions. Ensure migrations are updated in cmd/migrate or auto-migrated in server.go if appropriate.
    • Generics API: Strongly prefer the new Generics API (e.g., gorm.G[data.User](db).First(...)) over the old interface-based API (db.Model(&data.User{}).First(...)) for better type safety and clarity.
    • Updates Pattern: When updating single columns or a subset of fields on a model that has preloaded associations (like Device.Apps), ALWAYS use a lightweight struct with only the ID: s.DB.Model(&data.Device{ID: device.ID}).Update(...). Passing the fully populated struct s.DB.Model(&device) can trigger GORM to unintentionally re-save preloaded associations, potentially causing race conditions (e.g., deleted apps reappearing).
  • Testing: Use the testify library (assert and require) in unit tests.