Technical Guide

This page is the working manual for how OpenSpaces currently behaves. It explains what the app records, what it enforces now, and which rules are guidance for drivers and managers.

Core Purpose

• OpenSpaces is a driver work-time and logbook tool.
• It records work events in time order so a driver can build a usable daily log.
• It is designed to allow honest corrections for normal human mistakes, while still keeping the record understandable.
• It is not meant to help hide non-compliance. Managers and enforcement may compare logbook entries with other records.

How A Day Is Tracked

• Start Work opens a shift entry inside the wider workday and work period record.
• Start Break marks the start of a break.
• Start Work during a break resumes work (this saves an end_break event).
• End Shift closes the active shift entry, but the wider workday and work period still depend on the full sequence of work and rest.
• Vehicle On, Vehicle Off, and Change Vehicle track the active vehicle and Odo/Hubbo values when supplied.
• Note creates a logbook remark entry tied to a time.

Break Rules

• A worker must have a break after 5.5 hours (330 minutes) of work time.
• The current dashboard counts down to that break from the last qualifying break or the start of the current shift.
• A qualifying break is treated as at least 30 minutes.
• If a driver ends a break early, the app warns first. If they confirm, the unfinished break is discarded instead of being kept as a qualifying break.
• This means the app supports practical real-world corrections while still protecting the 30-minute break rule in the working record.

Work Period

• A work period is the cumulative work time a worker can do, up to 70 hours, before they must show a 24-hour uninterrupted break.
• A worker can take that 24-hour uninterrupted break earlier than 70 hours. For example, they may stop after 25 cumulative hours.
• Once that 24-hour uninterrupted break is taken, the next work activity starts a new work period.
• The app should be read as a continuous line of work time and rest time, not just isolated shift entries.

Workday And 10-Hour Break

• A workday is a rolling 24-hour period. It is not tied to named calendar days like Monday, Tuesday, or Sunday.
• Each workday must include a 10-hour uninterrupted break.
• Because this is a digital system, a driver can work across midnight, such as starting at 8:00 pm and finishing at 6:00 am the next day, while the record still remains one continuous line of work and rest.
• The logbook day view can still default to midnight for display and review, but that display choice does not change the underlying continuous record.
• The current app does not yet hard-enforce every 70-hour, 24-hour, and 10-hour compliance decision in code. Some of that is still handled by the driver, manager, and later review.

Locations

• When GPS is available, the app stores latitude and longitude with the event.
• It reverse-geocodes that position into a readable place label for the logbook.
• If GPS is unavailable, the app still lets the driver save the event and marks the location as GPS unavailable.
• This is intentional: missing GPS should not stop the driver from recording the event itself.

Notes And Corrections

• Drivers can add notes to explain a job, stop, issue, or correction.
• Notes can also be used to record the location or reason for a break in plain language.
• Drivers can also adjust the event time when they forgot to log it at the right moment.
• This supports real-world cases such as forgetting to start work, forgetting to start or end a break, or forgetting to end shift until later.
• The goal is to let the logbook reflect what actually happened, even if the entry is made later.

48-Hour Edit Window

• Drivers currently have a 48-hour window to correct an event.
• Within that window, the driver can edit the time, change the note, or remove the event from the active logbook.
• The edited time must still stay within the last 48 hours.
• After 48 hours, the event is locked from driver edits, note changes, and deletes.
• This keeps the app practical for day-to-day mistakes while reducing later history rewriting.

What The App Enforces Right Now

• Only one active work period at a time.
• No break can start unless work is already active.
• No second break can start while a break is already open.
• A break should be at least 30 minutes to count as a qualifying break.
• Vehicle sign-on and sign-off rules must stay in sensible order.
• Event times cannot overlap other events or jump past the previous or next event.
• Break edits must still keep the break in the correct order and at least 30 minutes long.
• Events older than 48 hours are locked from driver correction.

Driver Identity And Onboarding

• The daily logbook should stay focused on the legal work and rest record, but onboarding can hold extra identity details for validation.
• This helps employers, managers, and enforcement confirm that the record belongs to the correct driver.
• It also makes the system harder to fake than a simple name-only account.

Core daily logbook record

• Driver name
• Work and rest event times
• Locations and remarks
• Vehicle rego
• Odo/Hubbo or RUC readings where required

Identity and validation layer

• Full legal name
• Driver licence number
• Driver licence version
• Employer or operator name
• TSL or operator identifier where needed
• Optional employee or internal reference number

Why this matters

• Employers are expected to keep the employer record copy for at least 12 months.
• Read-only employer access for the previous 12 months is a likely future requirement.
• Driver licence details can help validate that the driver, the employer record, and the logbook all match.
• Enforcement can use this identity layer to help verify that a logbook is genuine and tied to a real driver.

Privacy and security

• Licence details should be treated as sensitive information.
• Access should be role-based and visible only to the right people.
• Viewing and changing identity details should eventually be auditable.

Access, Billing, And Roles

• The driver-facing app is planned as a free product to make onboarding and adoption easy.
• Paid access is aimed at transport owners, operators, and other admin users who need oversight, alerts, reports, and retained records.
• Owner-drivers may need both roles: a free driver login plus paid operator/admin access.
• Ads may be acceptable in low-risk screens such as onboarding or account pages, but should stay away from the live driving dashboard and critical compliance actions.

Planned roles

• Driver: creates and maintains the live logbook.
• Operator/Admin: paid read-only oversight, reports, alerts, exports, and compliance review.
• Enforcement: temporary read-only inspection access only.

Operator Linking Model

• An operator should be able to create an invite key or join code.
• A driver can enter that key during onboarding or later in account settings to join the operator.
• This link should activate read-only access for the operator over that driver's records.
• A driver may need more than one linked operator or admin, so the design should support more than one active read-only relationship.
• If a driver leaves an employer, revoking access should stop future records only. Historic records should remain available for retained compliance access.

Planned link structure

• One driver can be linked to multiple operators.
• One operator can be linked to multiple drivers.
• Each link should carry a status such as pending, active, or revoked.
• Each link should also store when access started and ended.

Planned Onboarding Data Model

• Driver onboarding should collect enough information to identify the driver and prevent duplicate or fake records.
• Driver licence number and driver licence version are planned as core validation fields.
• The combination of driver licence number and licence version should be treated as unique for validation.
• If a licence already exists in the system, the app should prevent a duplicate active driver profile from being created against the same identity.

Planned driver fields

• Full legal name
• Driver licence number
• Driver licence version
• Employer or operator name (optional at first, then linkable later)
• TSL or operator identifier where needed
• Optional employee/internal reference

Uniqueness and validation

• Licence number should be normalized before storage and comparison.
• Licence version should be stored in a normalized format for exact comparison.
• Uniqueness should be enforced at the data layer as well as in the UI.
• Revalidation and admin review should be possible if identity details change later.

Planned onboarding flow

• The driver can create a free account, but onboarding should not complete until licence number and licence version are captured.
• The app should normalize the licence number, normalize the licence version, then check whether that identity already exists.
• If the identity is already active, the app should stop duplicate onboarding and direct the driver to sign in or recover the existing account.
• If the identity exists but is inactive or pending review, the app should hold the new onboarding and require admin review instead of creating a second active profile.
• If the identity is new, the driver profile can be created and later linked to one or more operators.

Planned validation rules

• Licence number and licence version together should define one active driver identity.
• Email address should still be unique for login, but email alone should not be trusted as the driver identity.
• Changing licence details later should require revalidation because it changes the identity record used by operators and enforcement.

Planned Implementation Path

• The current app does not yet store licence number or licence version in the live user table.
• The registration flow will need new fields, data validation, and a uniqueness check before the account is finalized.
• The database should eventually enforce uniqueness on the normalized licence identity so duplicate active profiles cannot be created by bypassing the UI.
• Operator linking and paid admin access should be built on top of that validated driver identity, not as a separate duplicate account model.

Enforcement Access

• A future inspection mode can provide temporary read-only access for enforcement.
• A practical model is a short-lived QR code plus a PIN.
• The driver would generate the inspection token from their own device when asked.
• That token should expire quickly and should never grant edit access.

Inspection access principles

• Read-only only
• Short-lived session
• Limited to the relevant record set
• Auditable so the system knows when inspection access was used

What Still Relies On Judgment

• The app does not replace legal responsibility.
• A driver is still responsible for entering a truthful record.
• A manager can still review whether a corrected record makes sense.
• The logbook day view is a reporting view. The real compliance story still comes from the continuous sequence of work and rest.
• Enforcement may still compare the logbook with other evidence such as job records, dispatch records, receipts, or other tracking.
• That is why the product stays flexible enough for honest corrections, but is moving toward tighter lock-down over time.

Planned Direction

• Keep the current 48-hour correction window for drivers.
• Keep older records locked by default.
• Add clearer audit history over time so edits are easier to review.
• Continue refining the compliance rules as the real-world workflow becomes clearer.

Back to Home