From 8670c509e879da0b539242e0888a41e3fecd782e Mon Sep 17 00:00:00 2001
From: micha <micha.hoiting@gmail.com>
Date: Sat, 21 Feb 2026 00:16:38 +0100
Subject: [PATCH] Added README.md file.

---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c9f00fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# triplex
+
+`triplex` is a deterministic, reversible serial number engine for
+high-integrity identifiers. It maps a compact 32-bit integer space to a
+human-readable serial format:
+
+```
+LLL-NNN-LC
+```
+
+Where:
+- `L` = data letter (`A`–`Z`)
+- `N` = number (`100`–`999`)
+- `C` = checksum letter (`A`–`Z`)
+
+## What it provides
+
+- 4 data letters
+- 3 numeric digits (`100`–`999`)
+- 1 checksum letter
+- Optional forbidden-triplet filtering on the first three letters
+- Reversible integer encoding/decoding
+- Deterministic checksum generation
+
+Total index capacity: **386,942,400** (`26^4 * 900`)
+
+## Features
+
+- Reversible mapping: `Encode(code) ↔ Decode(index)`
+- Deterministic checksum: `C = 'A' + (index % 26)`
+- Compact index space: fits in `uint32`
+- Human-readable serial format
+- Useful for manufacturing, logistics, SaaS identifiers, and audit-safe systems
+
+## Example
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"git.hoiting.org/micha/triplex/serial"
+)
+
+func main() {
+	idx := uint32(123456)
+
+	code, err := serial.Decode(idx)
+	if err != nil {
+		panic(err)
+	}
+
+	idx2, err := serial.Encode(code)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(code)
+	fmt.Println(idx == idx2) // true
+}
+```
+
+## Notes
+
+- The current serial format is `LLL-NNN-LC`.
+- Forbidden-triplet logic is centralized in `serial.IsForbiddenTriplet` and can be tailored to project rules.
+
+## API
+
+- `serial.Encode(code string) (uint32, error)`
+	- Parses and validates `LLL-NNN-LC`, checks checksum, and returns the deterministic index.
+- `serial.Decode(idx uint32) (string, error)`
+	- Converts a valid index back to `LLL-NNN-LC`.
+- `serial.RandomCode(isInUse ...func(uint32) bool) (string, uint32, error)`
+	- Generates a random valid `LLL-NNN-LC` code and its corresponding index.
+	- If provided, the callback is used to skip indices already in use by the client.
+
+Exported errors:
+
+- `serial.ErrInvalidFormat`
+- `serial.ErrInvalidLetters`
+- `serial.ErrForbiddenLetterTriplet`
+- `serial.ErrInvalidNumber`
+- `serial.ErrNumberOutOfRange`
+- `serial.ErrInvalidChecksum`
+- `serial.ErrIndexOutOfRange`
+- `serial.ErrRandomGenerationFailed`
+
+## Testing
+
+Run all tests:
+
+```bash
+go test ./...
+```