GümüşTheCat

Project Summary

GümüşTheCat is a private family task-competition app built around the daily care routine of a household cat. It turns recurring care tasks into friendly competitions, scoreboards, histories, and notifications, so responsibilities are visible and the routine feels lighter.

The project combines a small Node.js backend, a vanilla JavaScript single-page frontend, SQLite persistence, role-based administration, multilingual labels, and Progressive Web App support. It is designed to run as a self-hosted web app, with the frontend installed on phones like a lightweight app.

The interesting part is the cycle engine behind the tasks. Each task has a duration, activation time, score, care category, and competition context. The app calculates when a task is currently claimable, who claimed it, when it becomes available again, and how scores should roll up into competitions and championships.

This is a practical household automation project rather than a public SaaS product. The public notes describe the architecture and behavior, but omit private network details, real users, credentials, and server-specific deployment paths.

Project Pages

What It Does Today

  1. A user logs in or registers through an invite code.
  2. The app loads available competitions, championships, roles, task states, scoreboards, and notifications.
  3. Competitors can claim active recurring tasks during the current task window.
  4. The backend records each claim with the task, user, and cycle start date, preventing duplicate claims for the same cycle.
  5. Scoreboards combine task claims and manual score adjustments.
  6. Admin users can create competitions, clone tasks, manage users, assign roles, create championships, update translations, reset passwords, and manage household members.
  7. The frontend shows dashboards, competition lists, player history, score cards, charts, cat-care status, and settings.
  8. The Progressive Web App caches core assets and can be installed on mobile devices for a more app-like experience.

Current Features

  • Invite-code registration tied to a household.
  • JWT-based login and authenticated API calls.
  • Admin and non-admin user roles.
  • Competition and championship management.
  • Competitor and spectator roles per competition.
  • Recurring task cycles with duration, activation time, score value, and availability windows.
  • Task claiming with duplicate-claim protection per active cycle.
  • Undo and admin annulment paths for claims.
  • Manual score injection for corrections or bonuses.
  • Current competition scoreboards.
  • Historical competition and player activity views.
  • Line and radar chart data for competition progress and care-category breakdowns.
  • Championship scoreboards with wins-based or collective scoring.
  • Household member management and administrative password reset.
  • Multilingual interface labels for English, Turkish, and Dutch.
  • System timezone setting.
  • Cat-care status messages based on recent care activity.
  • Browser notifications and custom in-app cat-themed toast messages.
  • Theme support and mobile-friendly layout.
  • PWA manifest, service worker, app icons, and installability support.

Architecture

Mobile or desktop browser -> PWA single-page frontend -> Express JSON API -> authentication and admin middleware -> task cycle, scoring, notification, and history logic -> SQLite database Admin console -> competition, task, user, role, score, championship, household, i18n, and system settings APIs

The app is intentionally compact. The backend is a single Express service that serves static frontend assets and exposes JSON API routes. SQLite stores users, households, invites, competitions, roles, tasks, claims, manual scores, settings, championships, championship links, and notifications.

The frontend is a vanilla HTML, CSS, and JavaScript application. It talks to the API through a small wrapper that prefixes requests for the app subpath and adds the saved JWT when available. Chart.js is used for visual score history and care-category charts.

The deployment model is self-hosted and container-oriented. The project has separate development and release environments, but public documentation keeps the hostnames, private addresses, and exact server paths out of scope.

Main Components

  • Express Server: Serves the frontend, exposes JSON routes, initializes the database, and coordinates backend behavior.
  • SQLite Database: Stores users, households, invite codes, competitions, roles, tasks, claims, score adjustments, settings, championships, and notifications.
  • Authentication Layer: Uses password hashing and signed tokens for login, registration, profile access, password changes, and admin checks.
  • Task Cycle Engine: Calculates whether each task is currently active, the current cycle start, and the next available cycle.
  • Competition Service: Loads competitions, roles, task state, scoreboards, winners, remaining points, notifications, and graph data.
  • Championship Service: Groups competitions into longer-running championships and calculates combined results.
  • Admin Console: Provides management screens for competitions, tasks, users, roles, manual scores, translations, households, championships, and system settings.
  • PWA Frontend: Browser-based interface with installability, cached core assets, responsive layout, local settings, and mobile-friendly navigation.
  • i18n System: Stores and serves translation strings for English, Turkish, and Dutch, with an admin editing route.
  • Notification Layer: Stores backend notifications and shows browser or in-app alerts for task events, leadership changes, and care reminders.
  • Deployment Script: Selects the target environment from the current branch and rebuilds the matching containerized service.

Services And Technologies Used

Current services and technologies:

  • Node.js.
  • Express.
  • SQLite.
  • bcryptjs for password hashing.
  • JSON Web Tokens for authenticated API access.
  • Day.js with UTC and timezone plugins.
  • Vanilla HTML, CSS, and JavaScript.
  • Chart.js.
  • Progressive Web App manifest and service worker.
  • Docker-based deployment.
  • Reverse-proxy hosting for a subpath-based app.

Planned or possible refinements:

  • Split the server into smaller modules once the feature set stabilizes.
  • Add automated tests around task-cycle boundaries and scoring rules.
  • Replace first-run seeded development data with a safer setup wizard.
  • Add backup and restore tooling for household data.
  • Add more explicit audit history for admin score changes and claim annulments.
  • Improve offline behavior beyond static asset caching.

Design Principles

  • Keep daily care tasks quick to claim from a phone.
  • Make the scoreboard visible enough to motivate, but not heavy enough to become work.
  • Treat recurring tasks as time windows, not one-off checklist items.
  • Keep household data in a small self-hosted database.
  • Give admins enough control to correct mistakes without editing the database manually.
  • Keep the frontend simple and dependency-light.
  • Support multiple languages because the household context is multilingual.
  • Avoid publishing private deployment details, real household data, credentials, or exact local paths.

Roadmap

  • Add focused automated tests for task cycle boundaries, duplicate claim prevention, and championship scoring.
  • Add a public-safe first-run setup flow that does not create default development users in production.
  • Create database backup and restore instructions.
  • Add richer audit views for manual scores, undone claims, and admin annulments.
  • Improve PWA offline states for unavailable network or API responses.
  • Add screenshots or short demo clips using neutral sample data.
  • Consider extracting backend route groups into separate modules as the codebase grows.
  • Add exportable summaries for completed competitions.

Project Status

GümüşTheCat is an active working household app. The current version supports login, invite registration, recurring task claims, competition scoreboards, championships, admin management, multilingual UI labels, cat-care status messages, browser notifications, and installable PWA behavior. The next milestone is hardening: tests, safer first-run setup, backup documentation, and polished public media using sample data.