Skip to content

docs: rewrite README in the style of major open-source projects #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xuandung38 merged 1 commit into from
Oct 12, 2026
Merged

docs: rewrite README in the style of major open-source projects #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 43 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,43 @@ English | [Tiếng Việt](README.vi.md)

# handlive-shared

This repository runs no app. It holds the test vectors, JSON Schemas, design tokens and UI string catalog that Android, Apple and the relay share. The other repositories read it through `../shared`.
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

Sources: `../docs/detailed-design/00-common-specs.md` and `../docs/design-system/` in the hub repository. The Python tools in `tools/` generate and check these files. See this repository's `CLAUDE.md`.
Shared protocol schemas, cryptographic test vectors, design tokens, and UI localization strings for the HandLive ecosystem. This repository contains no standalone application; client apps (Android, Apple) and the relay depend on it via `../shared`.

## Overview

- **Single source of truth:** Centralizes wire formats, JSON schemas (2020-12), cryptographic test vectors, design tokens, and the bilingual UI string catalog across all platforms.
- **Specification alignment:** Built directly from [`docs/detailed-design/00-common-specs.md`](https://github.com/HandLive/handlive/blob/main/docs/detailed-design/00-common-specs.md) and [`docs/design-system/`](https://github.com/HandLive/handlive/tree/main/docs/design-system) in the hub repository.
- **Automated validation:** Dedicated Python toolchains verify test vectors, validate JSON schemas against hub documentation examples, and enforce strict UI localization rules.

## Workspace context

This repository is one component of the HandLive workspace:
- Hub repository [`handlive`](https://github.com/HandLive/handlive) (docs, plans) is the parent directory.
- Cloned alongside [`handlive-android`](https://github.com/HandLive/handlive-android), [`handlive-apple`](https://github.com/HandLive/handlive-apple), and [`handlive-relay`](https://github.com/HandLive/handlive-relay).
- Clone the full workspace from the hub using `tools/workspace.sh clone <group-url>`. See [`CLAUDE.md`](CLAUDE.md) for local workspace workflows.

## Components

| Folder | Contents | Docs |
|--------|----------|------|
| `test-vectors/` | 20 vector files (RFC and generated, including `push-envelope.json` and `relay-frame.json`) plus the cross-platform `envelope-roundtrip{,-apple}.json` | `test-vectors/README.md` |
| `schemas/` | JSON Schema 2020-12: envelope, payload, ack, error, `session-*`, `capability-*`, `pair-*`, `ping-ping`, `clipboard-*`, `sms-*`, `call_event-*`, `call-notification`; the relay's `relay-*` frames and `relay-rest` bodies; `push` bodies | `schemas/README.md` |
| `design-tokens/` | `tokens.json` (byte-identical to `../docs/design-system/tokens.json`), `type-extras.json` | `design-tokens/README.md` |
| `strings/` | `ui-strings.json`: every user-facing string in English and Vietnamese, with its JSON Schema | `strings/README.md` |
| `tools/vectors/` | `generate_vectors.py` (`--check`), `verify_vectors.py` | `tools/vectors/README.md` |
| `tools/schemas/` | `check_schemas.py` (schemas plus the examples in the hub docs; `HANDLIVE_DOCS_DIR`) | `tools/schemas/README.md` |
| `tools/strings/` | `check_strings.py` (catalog rules of 0.12.5; `--docs`, `--self-test`) | `strings/README.md` |
| `tools/bench/` | Clipboard latency, reconnect time, SMS latency (notification, reply to Sent) and call latency (state, panel, answer, decline from an iPhone notification, missed calls) from the `HLBENCH/1` logs; relay load test (`relay_load.py`, 1,000 fake devices); manual test on the device matrix | `tools/bench/README.md` |
| `tools/e2e/` | End-to-end harness: a fake Mac against the real Android app on an emulator (pairing, clipboard, SMS, calls), driven through adb; `self_test.py` runs in CI without an emulator | `tools/e2e/README.md` |
| `tools/e2e/relay_stack/` | The relay with PostgreSQL, Redis, a TLS front for the Android emulator and mock APNs and FCM that record every push; checks of registration, forwarding and push delivery; the Android build for it | `tools/e2e/relay_stack/README.md` |
| `test-vectors/` | 20 vector files (RFC and generated, including `push-envelope.json` and `relay-frame.json`) plus cross-platform `envelope-roundtrip{,-apple}.json` | [`test-vectors/README.md`](test-vectors/README.md) |
| `schemas/` | JSON Schema 2020-12: envelope, payload, ack, error, `session-*`, `capability-*`, `pair-*`, `ping-ping`, `clipboard-*`, `sms-*`, `call_event-*`, `call-notification`; relay `relay-*` frames and `relay-rest` bodies; `push` bodies | [`schemas/README.md`](schemas/README.md) |
| `design-tokens/` | `tokens.json` (byte-identical to `../docs/design-system/tokens.json`), `type-extras.json` | [`design-tokens/README.md`](design-tokens/README.md) |
| `strings/` | `ui-strings.json`: every user-facing string in English and Vietnamese, with its JSON Schema | [`strings/README.md`](strings/README.md) |
| `tools/vectors/` | `generate_vectors.py` (`--check`), `verify_vectors.py` | [`tools/vectors/README.md`](tools/vectors/README.md) |
| `tools/schemas/` | `check_schemas.py` (schemas plus examples in hub docs; `HANDLIVE_DOCS_DIR`) | [`tools/schemas/README.md`](tools/schemas/README.md) |
| `tools/strings/` | `check_strings.py` (catalog rules of 0.12.5; `--docs`, `--self-test`) | [`strings/README.md`](strings/README.md) |
| `tools/bench/` | Clipboard latency, reconnect time, SMS latency (notification, reply to Sent), call latency (state, panel, answer, decline from iPhone notification, missed calls) from `HLBENCH/1` logs; relay load test (`relay_load.py`, 1,000 simulated devices); manual test matrix | [`tools/bench/README.md`](tools/bench/README.md) |
| `tools/e2e/` | End-to-end harness: simulated Mac against real Android app on an emulator (pairing, clipboard, SMS, calls), driven via adb; `self_test.py` runs in CI without an emulator | [`tools/e2e/README.md`](tools/e2e/README.md) |
| `tools/e2e/relay_stack/` | Relay with PostgreSQL, Redis, TLS front for Android emulator, mock APNs and FCM recording every push; verifies registration, forwarding, and delivery | [`tools/e2e/relay_stack/README.md`](tools/e2e/relay_stack/README.md) |

## Requirements

- **Python:** Python 3 (with `venv` module and `pip`) for toolchains verifying vectors, schemas, and strings

## Commands

```sh
python3 -m venv tools/.venv && tools/.venv/bin/pip install -r tools/vectors/requirements.txt -r tools/schemas/requirements.txt -r tools/strings/requirements.txt
Expand All @@ -27,6 +48,15 @@ tools/.venv/bin/python tools/schemas/check_schemas.py # must print "XA
tools/.venv/bin/python tools/strings/check_strings.py # must print "OK"
```

## Documentation and community

- [System Architecture](https://github.com/HandLive/handlive/blob/main/docs/system-architecture.md) — System design and security model
- [Detailed Design](https://github.com/HandLive/handlive/tree/main/docs/detailed-design) — Protocols, formats, and specifications
- [Deployment Guide](https://github.com/HandLive/handlive/blob/main/docs/deployment-guide.md) — Packaging and distribution guidelines
- [CONTRIBUTING](https://github.com/HandLive/.github/blob/main/CONTRIBUTING.md) — PR workflow, small commits, and DCO sign-off (`git commit -s`)
- [SECURITY](https://github.com/HandLive/.github/blob/main/SECURITY.md) — Vulnerability reporting policy
- [CODE_OF_CONDUCT](https://github.com/HandLive/.github/blob/main/CODE_OF_CONDUCT.md) — Community standards

## License

Apache License 2.0 — see [LICENSE](LICENSE). Contributions follow [CONTRIBUTING](https://github.com/HandLive/.github/blob/main/CONTRIBUTING.md) (small commits under a real name, DCO sign-off with `git commit -s`); report vulnerabilities privately as described in [SECURITY](https://github.com/HandLive/.github/blob/main/SECURITY.md).
Apache License 2.0 — see [LICENSE](LICENSE).
56 changes: 43 additions & 13 deletions README.vi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,43 @@

# handlive-shared

Kho này không chạy ứng dụng. Kho lưu test vector, JSON Schema, design token và catalog chuỗi giao diện. Android, Apple và relay dùng chung các file này. Các kho kia đọc qua `../shared`.
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

Nguồn: `../docs/detailed-design/00-common-specs.md` và `../docs/design-system/` trên kho hub. Công cụ Python trong `tools/` sinh và kiểm các file này. Xem `CLAUDE.md` trong kho này.
Lược đồ giao thức, test vector mật mã, design token và chuỗi bản địa hóa giao diện dùng chung cho hệ sinh thái HandLive. Kho này không chứa ứng dụng độc lập; các ứng dụng máy khách (Android, Apple) và relay phụ thuộc vào kho này qua đường dẫn `../shared`.

## Tổng quan

- **Nguồn chân lý duy nhất:** Tập trung các định dạng truyền tải, JSON schema (2020-12), test vector mật mã, design token và catalog chuỗi giao diện song ngữ (tiếng Anh và tiếng Việt) cho toàn bộ các nền tảng.
- **Bám sát đặc tả:** Được xây dựng trực tiếp từ [`docs/detailed-design/00-common-specs.md`](https://github.com/HandLive/handlive/blob/main/docs/detailed-design/00-common-specs.vi.md) và [`docs/design-system/`](https://github.com/HandLive/handlive/tree/main/docs/design-system) trong kho hub.
- **Kiểm tra tự động:** Bộ công cụ Python chuyên dụng xác thực test vector, kiểm tra tính hợp lệ của JSON schema với các ví dụ trong tài liệu hub, và thực thi các quy tắc bản địa hóa chuỗi giao diện nghiêm ngặt.

## Bối cảnh workspace

Kho lưu trữ này là một thành phần trong workspace HandLive:
- Kho hub [`handlive`](https://github.com/HandLive/handlive) (tài liệu, kế hoạch) là thư mục cha.
- Được clone cùng với [`handlive-android`](https://github.com/HandLive/handlive-android), [`handlive-apple`](https://github.com/HandLive/handlive-apple), và [`handlive-relay`](https://github.com/HandLive/handlive-relay).
- Clone toàn bộ workspace từ hub bằng lệnh `tools/workspace.sh clone <group-url>`. Xem [`CLAUDE.md`](CLAUDE.md) để biết quy trình làm việc trong workspace.

## Thành phần

| Thư mục | Nội dung | Tài liệu |
|---------|----------|----------|
| `test-vectors/` | 20 file vector (RFC + tự sinh, có `push-envelope.json` và `relay-frame.json`) và `envelope-roundtrip{,-apple}.json` liên nền tảng | `test-vectors/README.vi.md` |
| `schemas/` | JSON Schema 2020-12: envelope, payload, ack, error, `session-*`, `capability-*`, `pair-*`, `ping-ping`, `clipboard-*`, `sms-*`, `call_event-*`, `call-notification`; khung `relay-*` và thân `relay-rest` của relay; thân `push` | `schemas/README.vi.md` |
| `design-tokens/` | `tokens.json` (giống byte với `../docs/design-system/tokens.json`), `type-extras.json` | `design-tokens/README.vi.md` |
| `strings/` | `ui-strings.json`: mọi chuỗi hiển thị bằng tiếng Anh và tiếng Việt, kèm JSON Schema | `strings/README.vi.md` |
| `tools/vectors/` | `generate_vectors.py` (`--check`), `verify_vectors.py` | `tools/vectors/README.vi.md` |
| `tools/schemas/` | `check_schemas.py` (schema + ví dụ trong tài liệu hub; `HANDLIVE_DOCS_DIR`) | `tools/schemas/README.vi.md` |
| `tools/strings/` | `check_strings.py` (quy tắc catalog 0.12.5; `--docs`, `--self-test`) | `strings/README.vi.md` |
| `tools/bench/` | Độ trễ bảng nhớ tạm, thời gian kết nối lại, độ trễ SMS (thông báo, trả lời tới Đã gửi) và độ trễ cuộc gọi (trạng thái, panel, trả lời, từ chối từ thông báo iPhone, cuộc gọi nhỡ) từ log `HLBENCH/1`; thử tải relay (`relay_load.py`, 1 000 thiết bị giả); kiểm thử tay theo ma trận thiết bị | `tools/bench/README.vi.md` |
| `tools/e2e/` | Bộ kiểm thử đầu cuối: một Mac giả với app Android thật trên máy ảo (ghép nối, bảng nhớ tạm, SMS, cuộc gọi), điều khiển qua adb; `self_test.py` chạy trong CI, không cần máy ảo | `tools/e2e/README.vi.md` |
| `tools/e2e/relay_stack/` | Relay cùng PostgreSQL, Redis, TLS front cho máy ảo Android, APNs và FCM giả ghi lại mọi push; kiểm tra đăng ký, chuyển tiếp và giao push; bản build Android cho nó | `tools/e2e/relay_stack/README.vi.md` |
| `test-vectors/` | 20 file vector (RFC và tự sinh, bao gồm `push-envelope.json` và `relay-frame.json`) cùng `envelope-roundtrip{,-apple}.json` liên nền tảng | [`test-vectors/README.vi.md`](test-vectors/README.vi.md) |
| `schemas/` | JSON Schema 2020-12: envelope, payload, ack, error, `session-*`, `capability-*`, `pair-*`, `ping-ping`, `clipboard-*`, `sms-*`, `call_event-*`, `call-notification`; khung `relay-*` và thân `relay-rest` của relay; thân `push` | [`schemas/README.vi.md`](schemas/README.vi.md) |
| `design-tokens/` | `tokens.json` (giống từng byte với `../docs/design-system/tokens.json`), `type-extras.json` | [`design-tokens/README.vi.md`](design-tokens/README.vi.md) |
| `strings/` | `ui-strings.json`: mọi chuỗi hiển thị bằng tiếng Anh và tiếng Việt, kèm JSON Schema | [`strings/README.vi.md`](strings/README.vi.md) |
| `tools/vectors/` | `generate_vectors.py` (`--check`), `verify_vectors.py` | [`tools/vectors/README.vi.md`](tools/vectors/README.vi.md) |
| `tools/schemas/` | `check_schemas.py` (schema cùng các ví dụ trong tài liệu hub; `HANDLIVE_DOCS_DIR`) | [`tools/schemas/README.vi.md`](tools/schemas/README.vi.md) |
| `tools/strings/` | `check_strings.py` (quy tắc catalog 0.12.5; `--docs`, `--self-test`) | [`strings/README.vi.md`](strings/README.vi.md) |
| `tools/bench/` | Độ trễ bảng nhớ tạm, thời gian kết nối lại, độ trễ SMS (thông báo, trả lời tới Đã gửi), độ trễ cuộc gọi (trạng thái, bảng thông báo, trả lời, từ chối từ thông báo iPhone, cuộc gọi nhỡ) từ log `HLBENCH/1`; thử tải relay (`relay_load.py`, 1.000 thiết bị giả); ma trận kiểm thử tay | [`tools/bench/README.vi.md`](tools/bench/README.vi.md) |
| `tools/e2e/` | Bộ kiểm thử đầu cuối: Mac giả lập tương tác với app Android thật trên máy ảo (ghép nối, bảng nhớ tạm, SMS, cuộc gọi), điều khiển qua adb; `self_test.py` chạy trong CI không cần máy ảo | [`tools/e2e/README.vi.md`](tools/e2e/README.vi.md) |
| `tools/e2e/relay_stack/` | Relay cùng PostgreSQL, Redis, TLS front cho máy ảo Android, APNs và FCM giả lập ghi lại mọi push; kiểm tra đăng ký, chuyển tiếp và phân phối | [`tools/e2e/relay_stack/README.vi.md`](tools/e2e/relay_stack/README.vi.md) |

## Yêu cầu

- **Python:** Python 3 (kèm module `venv` và `pip`) cho các bộ công cụ kiểm thử vector, schema và chuỗi giao diện

## Lệnh

```sh
python3 -m venv tools/.venv && tools/.venv/bin/pip install -r tools/vectors/requirements.txt -r tools/schemas/requirements.txt -r tools/strings/requirements.txt
Expand All @@ -27,6 +48,15 @@ tools/.venv/bin/python tools/schemas/check_schemas.py # phải in "XAN
tools/.venv/bin/python tools/strings/check_strings.py # phải in "OK"
```

## Tài liệu và cộng đồng

- [Kiến trúc hệ thống](https://github.com/HandLive/handlive/blob/main/docs/system-architecture.vi.md) — Thiết kế hệ thống và mô hình bảo mật
- [Thiết kế chi tiết](https://github.com/HandLive/handlive/tree/main/docs/detailed-design) — Giao thức, định dạng và đặc tả kỹ thuật
- [Hướng dẫn triển khai](https://github.com/HandLive/handlive/blob/main/docs/deployment-guide.vi.md) — Đóng gói và phát hành ứng dụng
- [CONTRIBUTING](https://github.com/HandLive/.github/blob/main/CONTRIBUTING.vi.md) — Quy trình gửi PR, commit nhỏ và ký xác nhận DCO (`git commit -s`)
- [SECURITY](https://github.com/HandLive/.github/blob/main/SECURITY.vi.md) — Chính sách báo cáo lỗ hổng bảo mật
- [CODE_OF_CONDUCT](https://github.com/HandLive/.github/blob/main/CODE_OF_CONDUCT.vi.md) — Quy tắc ứng xử cộng đồng

## Giấy phép

Apache License 2.0 — xem [LICENSE](LICENSE). Đóng góp theo [CONTRIBUTING](https://github.com/HandLive/.github/blob/main/CONTRIBUTING.vi.md) (commit nhỏ, đứng tên người thật, ký DCO bằng `git commit -s`); báo lỗi bảo mật kín theo [SECURITY](https://github.com/HandLive/.github/blob/main/SECURITY.vi.md).
Apache License 2.0 — xem [LICENSE](LICENSE).
Loading