Hackatime

Hackatime uses a hybrid architecture where Rails manages routing, authorization, and data writes, while Svelte handles presentation and local UI state.

1. Routing & Controllers: Routes dispatch to Rails controllers. Browser controllers inherit from ApplicationController (handling session, lockout, time zones, etc.). Inertia controllers inherit from InertiaController, which provides shared layout props (navigation, theme, CSRF, etc.).
2. Inertia Boundary: Controllers use render inertia: "Directory/Page", props: .... The props object is the serialized boundary between the server and the client.
3. Frontend Resolution: app/javascript/entrypoints/inertia.ts resolves page names to .svelte files and wraps them in AppLayout.svelte.
4. Client-side Navigation: Use Inertia <Link>, <Form>, or router calls. Rails remains the owner of routing and authorization.

Important Rule for URLs: Do not hand-build URLs on the client. Use js_from_routes. Mark routes with export: true in config/routes.rb, regenerate, and import the controller module from app/javascript/api. Use .path() to generate paths/query parameters.

# config/routes.rb
# Mark routes to be exported to JS
get '/some_path', to: 'some_controller#action', export: true

// app/javascript/pages/SomePage.svelte
import { SomeController } from 'app/javascript/api';

const path = SomeController.path({ param: 'value' });

Scopes define the level of access your application has to user data. If no scopes are specified, only profile is granted.

Admin Scope Restrictions

• Approval Required: Using the admin scope requires explicit approval from Hack Club HQ.
• User Roles: Only admin+ users (admin, superadmin, ultraadmin) can attach the admin scope. Viewers and admin+ users can authorize approved apps requesting this scope, but the token's power is limited to the user's actual role.
• Security: Apps using the admin scope must be configured as confidential (server-side).

Hackatime uses ApplicationJob as the base class for all background jobs, providing shared error reporting and handling deserialization/concurrency failures.

Background Jobs (GoodJob)

• Configuration: config/initializers/good_job.rb is the source of truth for queue and cron settings.
• Environments: Development uses async threads; non-development environments expect external workers; cron is enabled in production only.
• Best Practice: Do not perform slow remote work in request controllers. Use queues based on latency and ownership requirements.

Email (Action Mailer)

• Configuration: Production SMTP and the latency_10s deliver_later queue are configured in config/environments/production.rb.
• Pattern: Some jobs call deliver_now inside an already-queued job. Maintain this boundary unless you are intentionally changing retry or queue semantics.

Slack Integration

• Ingress: Signed commands enter via SlackController (app/controllers/slack_controller.rb).
• Security: Outside of development, commands must have a valid Slack HMAC signature and a timestamp within five minutes.
• Logic: Remote API calls, token management, and rate-limiting are handled in the SlackIntegration concern (app/models/concerns/slack_integration.rb). Controllers should focus on authenticating, validating, and enqueuing work.

Hackatime distinguishes between primary data (Sources of Truth) and data that is calculated or cached (Derived/Disposable State).

Key Principle: Never write a rollup, duration, profile statistic, or cache as if it were primary data. If data is incorrect, change the input or the derivation logic, invalidate the existing state, and let the system rebuild it.

Hackatime manages the relationship between user activity and code repositories through two main models:

• ProjectRepoMapping: Owned by the user. It maps a heartbeat project name to a repository and manages archive/sharing states. Ingestion asynchronously attempts to map new project names by searching the user's GitHub profile/organizations.
• Repository: A shared resource identified by its URL. It contains host/owner/name and synchronized metadata (stars, languages, etc.).

Key Distinction: A mapping is user-specific, but a repository is shared. Do not store user preferences on the Repository model.

Extending Repository Hosts: Currently, only GitHub is supported via GithubService. To add a new host:

1. Implement a service following BaseService.
2. Update RepoHost::ServiceFactory to include the new host.
3. Update jobs that contain host-specific discovery or event logic.

Hackatime relies heavily on user-specific time zones for calendar-based logic (streaks, activity, etc.).

Time Zone Management

• Heartbeat Data: The time field in heartbeats is stored as Unix epoch time.
• Calendar Logic: Concepts like 'today', 'week', and 'streak' use the validated User#timezone.
• Context: Browser requests are wrapped in Time.use_zone(current_user.timezone).
• Warning: Services or background jobs that do not run in a request context must use Time.use_zone explicitly to ensure correct calendar math.
• Side Effects: Changing a user's timezone invalidates both old/new activity cache keys and rollups.

Concurrency and Data Integrity

• Correctness: Use database constraints/upserts for cross-process correctness and transactions for multi-row replacement.
• Derived Work: Use after_commit hooks for work triggered by database changes.
• Performance: Use GoodJob concurrency and cache coalescing for expensive, idempotent refreshes.
• Race Conditions: Ensure heartbeat deduplication is race-safe and rollup replacement is atomic. Note that the Rails cache is an optimization, not a source of truth or a lock.

All coding activity is recorded as Heartbeat rows. All writes should flow through the HeartbeatIngest service to ensure normalization, deduplication, and proper scheduling of rollups.

Heartbeat Ingestion (HeartbeatIngest)

• Handles input normalization, epoch validation, and language/user-agent inference.
• Performs bulk insertion with deduplication.
• Schedules rollup refreshes and project mapping after successful inserts.
• Soft Deletion: Uses deleted_at. Use soft_delete or restore methods, which also trigger rollup invalidation.

Duration Calculation

Durations are not stored; they are derived from ordered heartbeat timestamps via the Heartbeatable concern.

• Timeout: The default timeout is 120 seconds (2 minutes).
• Logic:
  • The first heartbeat in a sequence contributes zero duration.
  • Each subsequent heartbeat contributes min(current_time - previous_time, 120s).
  • If a gap exceeds 120s, a new span is started.
• Ordering: Calculations rely on deterministic ordering by time, id.