eclipse-score · ryan-steel · Jul 15, 2026 · Jul 15, 2026 · Jul 16, 2026
diff --git a/README.md b/README.md
@@ -1,114 +1,220 @@
+# Time
 
-# C++ & Rust Bazel Template Repository
+Unified time service library and distributed time synchronization infrastructure for automotive ECU software.
 
-This repository serves as a **template** for setting up **C++ and Rust projects** using **Bazel**.
-It provides a **standardized project structure**, ensuring best practices for:
+[![Documentation](https://img.shields.io/badge/docs-time-blue)](https://eclipse-score.github.io/time)
 
-- **Build configuration** with Bazel.
-- **Testing** (unit and integration tests).
-- **Documentation** setup.
-- **CI/CD workflows**.
-- **Development environment** configuration.
+## Overview
+
+Portable and high-performance implementation of time services for the S-CORE project.
+
+This repository contains source code for time clocks, time distribution infrastructure, and PTP synchronization. The Time module is implemented in C++ and provides working examples demonstrating usage patterns.
+
+High-level functionality provided by the Time module:
+
+- **Clock Domains**: Four time sources accessed through unified `Clock<Tag>` API
+  - **SystemTime**: Wall-clock time (Unix epoch) for timestamps and user-visible time displays
+  - **SteadyTime**: Monotonic time for duration measurements and timeouts
+  - **HighResSteadyTime**: High-precision monotonic time for precise timing applications
+  - **VehicleTime**: PTP-synchronized time for distributed automotive applications requiring initialization
+- **Unified API**: Type-safe `Clock<Tag>::GetInstance().Now()` returns `ClockSnapshot<TimePoint, Status>` with atomic time + metadata reads
+- **Event Subscription**: `Subscribe<EventType>()` / `Unsubscribe<EventType>()` for status changes and PTP protocol data
+- **Time Infrastructure**
+  - **TimeDaemon**: Plugin-based time distribution daemon with IPC message broker
+  - **TimeSlave**: PTP protocol implementation with offset calculation and rate adjustment
+- **Test Utilities**: Mock backends and `ScopedClockOverride` for comprehensive testing
+
+All clock domains support nanosecond precision and compile-time domain selection preventing cross-domain timing errors.
+
+---
+
+## 📋 Public API
+
+### Clock Domains
+
+#### SystemTime
+
+| Target | Purpose |
+|--------|---------|
+| `//score/time/system_time` | Wall-clock time (Unix epoch) for timestamps |
+| `//score/time/system_time:system_time_mock` | Mock backend for SystemTime testing |
+| `//score/time/system_time:interface` | Header-only interface (no backend) |
+
+#### SteadyTime
+
+| Target | Purpose |
+|--------|---------|
+| `//score/time/steady_time` | Monotonic time for duration measurement |
+| `//score/time/steady_time:steady_time_mock` | Mock backend for SteadyTime testing |
+| `//score/time/steady_time:interface` | Header-only interface (no backend) |
+
+#### HighResSteadyTime
+
+| Target | Purpose |
+|--------|---------|
+| `//score/time/high_res_steady_time` | High-precision monotonic time |
+| `//score/time/high_res_steady_time:high_res_steady_time_mock` | Mock backend for HighResSteadyTime testing |
+| `//score/time/high_res_steady_time:interface` | Header-only interface (no backend) |
+
+#### VehicleTime
+
+| Target | Purpose |
+|--------|---------|
+| `//score/time/vehicle_time` | PTP-synchronized vehicle time |
+| `//score/time/vehicle_time:vehicle_time_mock` | Mock backend for VehicleTime testing |
+| `//score/time/vehicle_time:interface` | Header-only interface (no backend) |
+
+### Time Infrastructure
+
+| Target | Purpose |
+|--------|---------|
+| `//score/time_daemon:time_daemon` | TimeDaemon binary for time distribution |
+| `//score/time_slave:time_slave` | TimeSlave binary for PTP synchronization |
+
+### Test Utilities
+
+| Target | Purpose |
+|--------|---------|
+| `//score/time/clock:clock_test_utils` | ScopedClockOverride and ClockTestFactory utilities |
+
+---
+
+## ⚙️ Using as Dependency
+
+Add to your `MODULE.bazel`:
+
+```python
+bazel_dep(name = "score_time", version = "x.x.x")
+```
+
+Check available versions in the [S-CORE Bazel Registry](https://eclipse-score.github.io/bazel_registry_ui/modules/score_time).
+
+### Using Unreleased Versions
+
+To depend on an unreleased version (for development or testing), use a git override in your `MODULE.bazel`:
+
+```python
+git_override(
+    module_name = "score_time",
+    commit = "abc123...",
+    remote = "https://github.com/eclipse-score/time.git",
+)
+```
+
+Replace the `commit` value with the specific git hash you want to use.
 
 ---
 
-## 📂 Project Structure
-
-| File/Folder                         | Description                                       |
-| ----------------------------------- | ------------------------------------------------- |
-| `README.md`                         | Short description & build instructions            |
-| `src/`                              | Source files for the module                       |
-| `tests/`                            | Unit tests (UT) and integration tests (IT)        |
-| `examples/`                         | Example files used for guidance                   |
-| `docs/`                             | Documentation (Doxygen for C++ / mdBook for Rust) |
-| `.github/workflows/`                | CI/CD pipelines                                   |
-| `.vscode/`                          | Recommended VS Code settings                      |
-| `.bazelrc`, `MODULE.bazel`, `BUILD` | Bazel configuration & settings                    |
-| `project_config.bzl`                | Project-specific metadata for Bazel macros        |
-| `LICENSE.md`                        | Licensing information                             |
-| `CONTRIBUTION.md`                   | Contribution guidelines                           |
+## 📖 Documentation
+
+- **[Time Feature Documentation](https://eclipse-score.github.io/score/main/features/time/index.html)**: High-level feature overview and S-CORE platform integration
+- **[Time Module Documentation](https://eclipse-score.github.io/time)**: Detailed API documentation, architecture, and requirements
+
+Generate module documentation locally:
+
+```bash
+bazel run //:docs
+```
 
 ---
 
 ## 🚀 Getting Started
 
+This section contains information on how to build and use the Time module.
+
 ### 1️⃣ Clone the Repository
 
-```sh
-git clone https://github.com/eclipse-score/YOUR_PROJECT.git
-cd YOUR_PROJECT
+```bash
+git clone https://github.com/eclipse-score/time.git
+cd time
 ```
 
-### 2️⃣ Build the Examples of module
+### 2️⃣ Prerequisites
 
-> DISCLAIMER: Depending what module implements, it's possible that different
-> configuration flags needs to be set on command line.
+- **C++ Compiler**: gcc/clang with C++17 support
+- **Build System**: Bazel 8+ (managed via Bazelisk)
+- **Operating System**: Linux (Ubuntu 24.04+)
+- **Dependencies**: S-CORE Baselibs, Google Test
+- **For QNX targets**: QNX 8.0 SDP
 
-To build all targets of the module the following command can be used:
+### 3️⃣ Development Environment
 
-```sh
-bazel build //src/...
-```
+Follow the [S-CORE Development Environment Guide](https://eclipse-score.github.io/score/main/contribute/development/development_environment.html) for Linux host setup requirements.
 
-This command will instruct Bazel to build all targets that are under Bazel
-package `src/`. The ideal solution is to provide single target that builds
-artifacts, for example:
+### 4️⃣ Building the Project
 
-```sh
-bazel build //src/<module_name>:release_artifacts
+Build all components for **Linux x86_64** by running:
+
+```bash
+bazel build //...
 ```
 
-where `:release_artifacts` is filegroup target that collects all release
-artifacts of the module.
+Run all tests:
 
-> NOTE: This is just proposal, the final decision is on module maintainer how
-> the module code needs to be built.
+```bash
+bazel test //...
+```
 
-### 3️⃣ Run Tests
+#### Other Platforms
 
-```sh
-bazel test //tests/...
+**Linux AArch64**:
+```bash
+bazel build --config=time-arm64-linux //...
+bazel test --config=time-arm64-linux //...
 ```
 
----
+**QNX x86_64**:
+```bash
+bazel build --config=time-x86_64-qnx //...
+bazel test --config=time-x86_64-qnx //...
+```
 
-## 🛠 Tools & Linters
+**QNX AArch64**:
+```bash
+bazel build --config=time-aarch64-qnx //...
+bazel test --config=time-aarch64-qnx //...
+```
+
+#### Testing with Sanitizers
 
-The template integrates **tools and linters** from **centralized repositories** to ensure consistency across projects.
+To test with AddressSanitizer, UBSan, and LeakSanitizer enabled:
 
-- **C++:** `clang-tidy`, `cppcheck`, `Google Test`
-- **Rust:** `clippy`, `rustfmt`, `Rust Unit Tests`
-- **CI/CD:** GitHub Actions for automated builds and tests
+```bash
+bazel test --config=time-x86_64-linux --config=asan_ubsan_lsan --build_tests_only //...
+```
 
 ---
 
-## 📖 Documentation
+## 💡 Examples
 
-- A **centralized docs structure** is planned.
+Working examples demonstrating clock usage patterns, testing approaches, and integration techniques. See [examples/](examples/) for complete usage examples.
 
 ---
 
-## ⚙️ `project_config.bzl`
+## 📂 Repository Structure
 
-This file defines project-specific metadata used by Bazel macros, such as `dash_license_checker`.
+```
+├── score/
+│   ├── time/                    # Clock domains (SystemTime, SteadyTime, etc.)
+│   ├── time_daemon/             # Time distribution daemon
+│   ├── time_slave/              # PTP synchronization implementation
+│   └── ts_client/               # Time status utilities (internal)
+├── examples/                    # Usage examples and patterns
+├── docs/                        # Module documentation
+└── tools/                       # Build and development utilities
+```
 
-### 📌 Purpose
+---
 
-It provides structured configuration that helps determine behavior such as:
+## 🤝 Contributing
 
-- Source language type (used to determine license check file format)
-- Safety level or other compliance info (e.g. ASIL level)
+See our [Contributing Guide](CONTRIBUTION.md) for contribution guidelines and development workflow.
 
-### 📄 Example Content
+---
 
-```python
-PROJECT_CONFIG = {
-    "asil_level": "QM",  # or "ASIL-A", "ASIL-B", etc.
-    "source_code": ["cpp", "rust"]  # Languages used in the module
-}
-```
+## 🔗 Support
 
-### 🔧 Use Case
+### Community
 
-When used with macros like `dash_license_checker`, it allows dynamic selection of file types
- (e.g., `cargo`, `requirements`) based on the languages declared in `source_code`.
+- **Issues**: Report bugs and request features via [GitHub Issues](https://github.com/eclipse-score/time/issues)
+- **Discussions**: Join time [Slack Channel](https://sdvworkinggroup.slack.com/archives/C0ADTA4SKUH)