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.

Summary of user experience

Developer UX for Time Recording

Primary Flow — Logging Time on an Issue The entry point is the issue detail page. A developer is looking at an issue they've been working on and wants to log time. On the issue detail page: A "Time" section appears below the main issue content (similar to how comments or activity sit). It shows:

Time Tracking

─────────────────────────────────────────
Logged: 3h 45m                [+ Log Time]
─────────────────────────────────────────
  Rk        Today        1h 30m   Fixed auth bug
  Rk        Feb 28       2h 15m   Initial investigation

Clicking + Log Time opens a small inline form or modal:

Log Time      
────────────────────────────
Date        [ Today ▾ ]
Duration    [ 1h 30m   ]
Note        [ optional  ]
                    [Cancel] [Save]

Three fields. Submit and the entry appears in the list immediately.

Duration Input The Duration field accepts natural formats: 1h 30m => 1 hour 30 minutes 2h => 2 hours 90m => 90 minutes 45 => ambiguous — reject or treat as minutes, decide upfront Inline validation as they type. If the format isn't recognized, show a hint: e.g. 1h 30m, 2h, 45m

Editing and Deleting Each time entry row has a context menu (three dots or hover actions) for the entry owner:

  Rk   Today   1h 30m   Fixed auth bug   [···]
                                          ├ Edit
                                          └ Delete

Edit opens the same form pre-filled. Delete asks for confirmation. If the entry is locked, the menu is absent or the options are disabled with a tooltip: "This entry has been locked."

What a Developer Sees vs What a Manager Sees

Developer:

Sees all time entries on issues they have access to Can edit/delete their own unlocked entries only Cannot see entries from projects they're not on

Manager/Admin:

Sees all entries across the project Can edit or delete any entry Can lock entries

External user (customer):

The Time Tracking section is not rendered at all. Not hidden, not greyed out — simply absent. (Artur - please confirm if this is acceptable - would some partners want to see the schedule?)

The Reports Accessible from the project sidebar or a top-level menu item: Project Time Report — "How much has been spent on this project this month, broken down by person?"

Project: Sztab   Jan 2026 – Feb 2026   [Change range]
──────────────────────────────────────
User          Hours
──────────────────────────────────────
Rk            42h 15m
Artur         18h 00m
──────────────────────────────────────
Total         60h 15m
User Time Report — "What have I worked on this month across all projects?"
My Time   Jan 2026 – Feb 2026   [Change range]
──────────────────────────────────────
Project       Hours
──────────────────────────────────────
Sztab         42h 15m
Internal      6h 00m
──────────────────────────────────────
Total         48h 15m

Both reports are filterable by date range. No export in MVP, but the data structure supports adding it later without changes.

Items deliberately punted in this version:

• No timer / stopwatch
• No "estimate" field on the log time form (that's issue-level, separate)
• No approval UI
• No export button
• No timesheet view

Two types of reports:

1. User report — an individual pulls it to see their own time spread across projects. Personal accountability and internal invoicing (e.g. Artur wants to know how much of Rk's time went to which project this month). So in userReport(), "user" = the person whose time you're summarizing. Usually themselves, which is why the service enforces actor.getId().equals(userId) unless the caller is a manager or admin.
2. Project report — manager/admin pulls it to see how much each person logged on a project. Customer billing perspective.

Queries for these types of reports are implemented using JPA in com.sztab.repository.TimeEntryRepository

I request adding time recording feature to the Sztab. It may work in a similar way as it works in OneDev. It would most likely be a premium paid feature.

Artur,

Do you also need UI for generating per-develop and per-project time reports in this issue? Or can. tat be treated as a follow up effort?

You did say in the issue statement that this should be comparable to what OneDev does. OneDev supports:

• Time logging per issue
• A dedicated Timesheet view showing hours per user per day/week
• Aggregated totals per milestone and project
• Filtering by user and date range

What I've implemeted covers the core of what OneDev does — logging, aggregation, per-project and per-user reports — just without the timesheet UI and without the visual charts. The backend data model supports adding those later without any schema changes.

If you want parity with OneDev reporting, the next step would be the report UI pages — a date range picker with a table, one page per report type. I will track it in a separate issue.

Please confirm.

Artur,

I am punting the war on time record report generation to https://tigase.dev/sztab/~issues/113 Right now I am starting on enhancing Sztab to do GitHub style fine grained authZ: https://tigase.dev/sztab/~issues/92

Doing end to end tests with reports tested using REST API