DOCSEARCHbyAlgolia
Submit Docs

Digital Lock On Documentation

website·Indexed 30 days ago

https://digital-lock-on-docs.netlify.app

Technical specifications and requirements for the KiwiRail Digital Lock On platform. Includes API contracts for Handover, Admin, and JWT Token Validation; UI specifications for authentication flows and protector handover; and verification matrices for plant operations, worker sign-on, and PWA connectivity.

Tokens
54.6K
Snippets
92
Records
366
Agent score
73%

What's inside Digital Lock On

  1. Overview of Digital Lock On Connectivity Domain

    The Connectivity domain manages data synchronization, offline capability, connection management, and conflict resolution. It is designed for challenging railway operational environments where network connectivity is intermittent. The primary goal is to ensure consistent, up-to-date information across all devices to support safety-critical decision making, ensuring updates from other users are delivered automatically without manual intervention.

  2. Overview of Digital Lock On System Administration

    System Administration provides the foundational data and configuration for the Digital Lock On platform. It is managed via a dedicated, fully online Admin Platform (separate from the operational platform) and is primarily used by System Administrators and KiwiRail IT Staff. The scope includes the creation and lifecycle management of users, projects, worksites, and plant equipment.

  3. Implement Worker ID Photo Storage and Distribution

    Worker ID photos must be managed using a combination of cloud storage and content delivery networks to ensure global availability and performance. Photos are required during the creation of both authenticated and unauthenticated users. The system must validate that uploaded files are in JPEG or PNG format and within configured size limits.

    Infrastructure Requirements:

    • Persistence: Azure Blob Storage
    • Distribution: Azure Front Door CDN

  4. Audit Trail Implementation Strategies for Digital Lock On

    The Digital Lock On platform requires an audit trail strategy to track user creation, project/worksite management, and meet regulatory compliance. Four architectural options are under consideration:

    1. Database-Level Audit Logging: Uses triggers or built-in DB features. Provides comprehensive, tamper-resistant coverage but lacks business context and can impact performance.
    2. Application-Level Audit Service: A dedicated service at the app layer. Captures rich business context and user intent, but requires consistent manual implementation by developers.
    3. Event-Driven Audit System: Uses event sourcing or domain events. Ideal for event-driven architectures and analytics, but involves high complexity and significant architectural changes.
    4. Hybrid Approach: Combines application-level logging for business actions and database-level logging for data integrity. Offers the most comprehensive coverage but has the highest maintenance and implementation overhead.

  5. PostHog Product Analytics Architecture Overview

    The PostHog JavaScript SDK is integrated into the React PWA to provide automatic tracking of pageviews (including virtual pageviews for modals), button clicks, form interactions, and link clicks. It also supports custom event tracking for modal workflows, user identification, session recordings for UX analysis, feature flags for controlled rollouts, and offline event queuing with automatic synchronization upon reconnection.

  6. Understand Digital Lock On Platform Architecture

    The system is split into two primary interfaces with external integrations:

    • Admin Platform: A fully online interface used for managing system entities (users, projects, worksites, plant).
    • Digital Lock On Platform: The main operational platform where protection and work activities are executed.
    • Integrations: The system integrates with the Clerk authentication service for credential management and external KiwiRail systems for bulk data import and synchronization.

  7. Understand the User Entity model

    The system categorizes users into two primary entities based on their ability to access the platform:

    1. AuthUser (Authenticated User): Users with system credentials who manage, oversee, and view protection activities. They can log in to the application.
    2. WorkerUser (Unauthenticated User): Personnel present at a worksite for safety and auditing purposes. They cannot log in to the platform; their presence is recorded when they are 'locked on' to a worksite.

  8. Create an Architecture Decision Record (ADR) using the standard template

    Use the ADR template to document technical decisions. The record should include the status (Completed/Superseded), date, stakeholders (Deciders, Consulted, Informed), the context motivating the change, the decision itself, the rationale, and the consequences (Positive, Negative, and Neutral). It also includes sections for implementation steps, alternatives considered (with pros/cons), and links to related requirements, specifications, and previous decisions.
    # ADR-[NUMBER]: [Decision Title]

**Status**: Completed/Superseded  
**Date**: [YYYY-MM-DD]  
**Deciders**: [List of decision makers]  
**Consulted**: [List of people consulted]  
**Informed**: [List of people informed]

## Context
What is the issue that we're seeing that is motivating this decision or change?

## Decision
What is the change that we're proposing or have agreed to implement?

## Rationale
Why did we choose this option over alternatives?

## Consequences
What becomes easier or more difficult to do and any risks introduced by this change?

### Positive Consequences
### Negative Consequences
### Neutral Consequences

## Implementation
How will this decision be implemented?

* [ ] Code changes required
* [ ] Documentation updates
* [ ] Team training
* [ ] Process changes

## Alternatives Considered
### Alternative 1: [Name]
* **Description**:
* **Pros**:
* **Cons**:
* **Reason for rejection**:

## Related Requirements
* REQ-XXX: Requirement Name

## Related Specifications
* SPEC-XXX: Specification Name

## Related Decisions
* ADR-XXX: Previous Decision

## References
* External documentation

  9. Understand Digital Lock On core concepts

    The Digital Lock On platform replaces paper-based sign-on and padlock procedures with digital registration. Key concepts include:

    • Protection: Procedures that prevent trains from entering areas where humans and equipment are present.
    • Protected Work Area (PWA): A designated section of track protected for safe work. Note: In this documentation, 'PWA' may refer to either a Protected Work Area or a Progressive Web App depending on context.
    • Lock-On: The act of a worker, operator, or site protector registering their presence and intention to enter the rail corridor, creating a 'digital lock' on the dashboard.
    • Lock-Off: The process of registering departure from the rail corridor, which must be done before leaving the work area.

  11. Implement Access Control for Digital Lock On

    The Access Control domain manages secure system access through two primary mechanisms: Authentication and Authorization.

    Authentication focuses on identity verification and session lifecycle, including:

    • User identity verification
    • Login and logout flows
    • Session management
    • Route protection (restricting frontend access based on authentication status)

    Authorization implements Role-Based Access Control (RBAC) to manage permissions, including:

    • Resource-level permissions
    • Action-level security
    • Enforcement of role hierarchies

  12. Understand the Digital Lock-On requirements domain structure

    The system requirements are organized by operational domains to align with system architecture and ensure traceability to high-level functional requirements. Each domain folder contains an index.md (overview and scope), a requirements/ folder (detailed functional requirements in EARS format), and a verification/ folder (test specifications and matrices).
    requirements/
├── 00-system-administration/    # User management, configuration, setup
├── 01-access-control/           # Authentication, authorisation, sessions
├── 02-protection-management/    # PWA lifecycle, worksite protection
├── 03-worker-operations/        # Lock-on/off, roles, safety verification
├── 04-plant-operations/         # Plant lock-on/off, handover, tracking
├── 05-connectivity/             # Data synchronisation, offline capability, connection management
├── 06-reporting-analytics/      # Audit trails, compliance, dashboards
└── shared/                      # Common entities, glossary, standards