Component List

Application Components

  • Express application: Main Node.js process that serves static assets and handles the JSON API.
  • Static frontend: Vanilla HTML, CSS, and JavaScript interface served from the public directory.
  • API wrapper: Frontend helper that prefixes requests for the app subpath and attaches the saved authentication token.
  • Authentication middleware: Verifies signed tokens and blocks protected routes when the user is not authenticated.
  • Admin middleware: Restricts management routes to admin users.
  • Task cycle engine: Calculates task availability from competition start date, activation time, duration, timezone, and active state.
  • Database helpers: Promise-based wrappers around SQLite run, get, and all calls.
  • Service worker: Caches the core app shell and avoids intercepting API requests.
  • PWA manifest: Defines the installed app name, icons, theme colors, start URL, and standalone display mode.

Data Model

  • Users: Household members with names, emails, password hashes, admin flags, and household links.
  • Households: Grouping layer for family or household membership.
  • Invites: Single-use registration codes generated by admins.
  • Competitions: Named time-bounded or open-ended task competitions.
  • Roles: Per-competition assignment of users as competitors or spectators.
  • Tasks: Recurring claimable units with score, duration, activation time, active state, and optional care category.
  • Claims: Records of a user claiming a task in a specific cycle.
  • Manual scores: Admin-added score adjustments with optional reason text.
  • Settings: Runtime configuration such as system timezone.
  • Championships: Longer-running groups of competitions with configurable scoring rules.
  • Championship links: Join table connecting championships to competitions.
  • Notifications: Stored events for task completions, leadership changes, and related alerts.

Frontend Areas

  • Authentication view: Login and invite-based registration.
  • Competition selection: List of competitions and championships available to the current user.
  • Dashboard: Active task cards, scoreboards, care status, and notifications.
  • Player history: Completed competitions and user activity history.
  • Score card: Score and progress views for competitions.
  • Settings: Language, notifications, theme, password changes, and system preferences.
  • Admin console: Multi-section management interface for competitions, tasks, users, scores, championships, translations, households, and system settings.

Backend API Areas

  • Auth routes: Login, registration, current user profile, and password change.
  • Competition routes: Competition lists, tasks, claims, scoreboards, graph data, radar data, notifications, and history.
  • Championship routes: Championship lists, scoreboards, and graph data.
  • Admin routes: Competition, task, role, score, setting, translation, claim, user, household, and championship management.
  • i18n routes: Public translation loading and admin translation saving.

Runtime Dependencies

  • Express: Web server and API routing.
  • sqlite3: Local persistence.
  • bcryptjs: Password hashing.
  • jsonwebtoken: Signed authentication tokens.
  • dayjs: Date, UTC, and timezone calculations.
  • dotenv: Local environment configuration.
  • Chart.js: Frontend charts.

Public Release Notes

  • Public documentation should not include real users, private household data, local host addresses, exact server paths, SSH targets, invite codes, or credentials.
  • Screenshots should use neutral sample accounts and sample task names.
  • Production deployments must set a strong token-signing secret through the environment.
  • First-run development seed data should be treated as local-only sample data, not a public setup recommendation.