Time Recording – Architectural Intent

Purpose

This is a summary of the architectural intent for introducing time recording capabilities in Sztab, based on email discussions.

The goal is to establish stable domain primitives and extensibility points that allow time tracking to evolve gradually (including premium and billing-related features), without prematurely committing to UI, workflow, or invoicing logic.

Time recording is treated as structured historical data, not as a UI mechanism (e.g., timers or timesheets).

---

Functional Scope

Recording Scope

• Time is recorded against issues only.
• Time is not recorded directly on pull requests.
  • Pull requests are considered results of work performed on issues.
  • If PR review or approval requires significant effort, it should be tracked via a related issue.
• Projects and users do not have time entries directly; instead, they are supported via reports and summaries derived from issue-level records.

---

Functional Definition

In Sztab, time recording means:

• A user explicitly records time spent working on an issue.
• Recorded time represents actual effort spent, expressed as a duration.
• Time entries are historical records and are preserved over time.
• Each entry is attributable to a user and timestamped.
• Recorded time can be aggregated and reported:
  • per issue
  • per project (across issues)
  • per user (across projects)
• Visibility and mutability of time entries are controlled via permissions.
• Time entries may become immutable once locked (e.g., after approval or for billing purposes).

Automated timers, timesheets, and billing workflows are explicitly out of scope for the initial implementation.

---

Core Domain Concept

TimeEntry (Domain Primitive)

A TimeEntry represents a single declaration of time spent by a user on an issue.

Key characteristics:

• Owned by a user
• Associated with exactly one issue
• Stores duration as a scalar value (e.g., minutes or hours)
• Created explicitly via manual entry
• Optionally annotated with a short note
• Designed to support future approval and locking semantics

Time entries are conceptually similar to audit or event records and favor traceability over unrestricted mutability.

---

Mutability and Corrections

Time entry behavior is policy-driven:

• Editing or correcting time entries is permission-based.
• The system should support future workflows where:
  • time entries are approved by a manager
  • approved entries are locked and become immutable
• In trusted or small teams, such workflows may be disabled.

The data model must allow locking semantics even if not initially enforced.

---

Permissions and Visibility

Time recording and visibility are governed by explicit permissions.

Expected defaults:

• Team members can view time records for their projects.
• Customers with access to a project do not see time records.
• Administrative or managerial roles may have broader visibility and control.

Permission rules must be flexible to support different organizational models.

---

Reporting and Aggregation

The system must support efficient aggregation of recorded time to enable the following reports:

1. Project report

   • For a given project and time period
   • Aggregated across all issues
   • Grouped by user
   • Intended for customer billing and project accounting

2. User report

   • For a given user and time period
   • Aggregated across all projects
   • Grouped by project
   • Intended for internal invoicing and personal reporting

Reports are considered projections over stored time entries and are not part of the core time recording domain.

---

Time Recording vs Estimation vs Cost

These concepts are intentionally separated:

• Time recording
  Actual effort spent on an issue, recorded by users.

• Time estimation
  Expected effort (in hours) provided by the developer working on the issue.

• Cost estimation
  Monetary value derived from time estimation and a project-level hourly rate contracted with the customer.

Future enhancements may include project-level hourly rate configuration and automatic cost calculation, but these are outside the initial scope.

---

Billing and Invoicing Direction

Long-term intent includes connecting recorded time to billing and invoicing.

Possible future capabilities include:

• generating invoices based on recorded time
• automatic invoice creation and delivery
• integration with approval and locking workflows

The initial design must not prevent these extensions but does not implement them.

---

Explicit Non-Goals (Initial Phase)

The following are intentionally excluded from the initial implementation:

• Automated timers
• Timesheet-style daily or weekly reporting requirements
• Billing, invoicing, or payment processing
• Payroll integration
• Estimation or planning workflows
• UI design beyond basic manual entry

---

Summary

This design establishes time recording in Sztab as an issue-centric, auditable, and permission-controlled domain capability.

It prioritizes simplicity, correctness, and extensibility, enabling incremental delivery while keeping the path open for reporting, approval workflows, and future billing-related features.