📌 TypeID-Python — 12-Month Roadmap (Parent Issue)

[akhundMurad]

This issue tracks the strategic roadmap for typeid-python and related ecosystem projects.

It is a parent issue: each concrete task should have its own sub-issue and be linked here.

---

🎯 Vision & Goals

High-level goal:
Turn typeid-python into the reference Python implementation of TypeID and the core of a small ecosystem (Django/SQLAlchemy/Pydantic/CLI), with solid performance, great DX, and clear guidance for real-world systems.

Concrete goals:

• ✅ Spec-compliant, well-tested, high-quality core library
• ✅ Modern dev experience (uv, Ruff, mypy, pre-commit, CI, benchmarks)
• ✅ First-class integrations (Django, SQLAlchemy, Pydantic, DRF, FastAPI)
• ✅ Tooling (CLI, playground, GitHub Action) that makes adoption easy
• ✅ Advanced performance & distributed-systems research track
• ✅ Clear documentation & branding so TypeID feels like a “default choice” in Python

---

🗓️ Timeline Overview (Flexible)

This is a target timeline, not a hard commitment. Actual timing may shift, but relative order of phases should stay.

• Phase 0 (Weeks 1–3) — Foundations & Cleanup
• Phase 1 (Month 1–2) — Core API Expansion
• Phase 2 (Month 2–4) — Ecosystem Integrations
• Phase 3 (Month 4–5) — CLI & Tooling
• Phase 4 (Month 5–7) — Advanced Features & Research
• Phase 5 (Month 7–12) — Full Ecosystem & Branding

---

📦 Scope & Non-Goals

In scope:

• typeid-python core library
• Satellite packages (e.g., django-typeid, sqlalchemy-typeid, CLI)
• Documentation, examples, and developer tooling
• Performance work and limited research/experiments

Out of scope (for now):

• Supporting every possible framework/ORM under the sun
• Non-Python implementations (can be future work, but not part of this roadmap)

---

🧱 Phase 0 — Foundations & Cleanup (Weeks 1–3)

Core goal: stabilize the library, modernize development workflow, and ensure full spec compliance.

Milestones

• Remove Poetry, update CONTRIBUTING, CI config, local dev instructions. #32
• Add Pre-commit hooks At minimum: Ruff, mypy, tests (or smoke tests). #33
  At minimum: Ruff, mypy, tests (or smoke tests).
• Add benchmarks (bench/) Compare UUIDv7, ULID, KSUID, TypeID under load and document results. #34
  Compare UUIDv7, ULID, KSUID, TypeID under load and document results.

---

⚙️ Phase 1 — Core API Expansion (Month 1–2)

Goal: expand the TypeID API to support practical usage patterns in modern systems.

Milestones

• Binary API
  - TypeID.bytes (16 bytes representation)
  - TypeID.from_bytes(prefix, b)
• Prefix factories - typeid_factory("user")() or similar API for ID generators with fixed prefix. #35
  - typeid_factory("user")() or similar API for ID generators with fixed prefix.
• Utility helpers - TypeID.is_valid(s), TypeID.try_parse(s), TypeID.prefix, TypeID.timestamp #36
  - TypeID.is_valid(s), TypeID.try_parse(s), TypeID.prefix, TypeID.timestamp
• Improved documentation - Clear API docs - “Why TypeID vs UUID/ULID” section - Basic migration tips for existing projects #37
  - Clear API docs
  - “Why TypeID vs UUID/ULID” section
  - Basic migration tips for existing projects

---

🌐 Phase 2 — Ecosystem Integrations (Month 2–4)

Goal: make TypeID a first-class citizen across popular Python frameworks.

Milestones

• Django integration - django-typeid package or typeid.contrib.django - TypeIDField (UUID-backed) - TypeIDModelMixin for typed PKs with prefixes - Example project in examples/django/ #38
  - django-typeid package or typeid.contrib.django
  - TypeIDField (UUID-backed)
  - TypeIDModelMixin for typed PKs with prefixes
  - Example project in examples/django/
• SQLAlchemy integration - Custom column type storing UUID in DB and TypeID in Python - Alembic autogeneration support - Example project (e.g., FastAPI + SQLAlchemy + Postgres) #39
  - Custom column type storing UUID in DB and TypeID in Python
  - Alembic autogeneration support
  - Example project (e.g., FastAPI + SQLAlchemy + Postgres)
• Pydantic integration - Pydantic-aware TypeID type with validation, JSON schema support - Works cleanly with FastAPI #40
  - Pydantic-aware TypeID type with validation, JSON schema support
  - Works cleanly with FastAPI
• Django REST Framework (DRF) support - Serializer field for TypeID - Integration with OpenAPI / API docs #41
  - Serializer field for TypeID
  - Integration with OpenAPI / API docs
• Examples in /examples - End-to-end examples showing how to wire everything together #42
  - End-to-end examples showing how to wire everything together

---

🛠️ Phase 3 — CLI & Tooling (Month 4–5)

Goal: deliver utilities that make TypeID easy to adopt and inspect.

Milestones

• Command-line tool (typeid)
  - typeid generate <prefix>
  - typeid validate <value>
  - typeid parse <value> --json
  - typeid info <value>
• Web playground
  - Simple UI to generate/parse IDs
  - Visualize K-sortable ordering (timeline)
• GitHub Action
  - Action to validate IDs in migrations/fixtures/data files
  - Documentation on how to integrate into CI

---

🧪 Phase 4 — Advanced Features & Research (Month 5–7)

Goal: improve performance, explore distributed systems use cases, and document findings.

Milestones

• High-throughput generator
  - Optimizations for async + multithreading
  - Document best practices under heavy load
• Performance & collision research
  - Evaluate behavior with real databases (e.g., B-tree fragmentation in Postgres)
  - Report on collision probabilities, ordering stability
• TypeID in ML/DS pipelines
  - Patterns for using TypeID as key for:
  - images (img_), masks (mask_), batches (batch_), runs (run_)
  - Example notebook/project showing reproducible pipelines

---

🌍 Phase 5 — Full Ecosystem & Branding (Month 7–12)

Goal: turn TypeID-Python into a cohesive ecosystem and recognized reference.

Milestones

• Umbrella ecosystem setup
  - Repos / structure for:
  - typeid-python
  - django-typeid
  - sqlalchemy-typeid
  - other contrib packages (optional)
• Documentation site (e.g., typeid.dev)
  - Docs, tutorials, API reference, examples
• Long-form guides & articles
  - “Why TypeID is the future of identifiers in Python”
  - “Using TypeID in Django/FastAPI/Postgres”
• Talks / community engagement
  - Blog posts, meetups, conference CFPs

---

🔗 How to Use This Issue

• This issue acts as a parent/umbrella for the roadmap.
• For each bullet/milestone above:
  • Create a dedicated GitHub issue
  • Link it back here using:
    • Parent: #<this issue number> in the body
    • And convert the corresponding checkbox to:

      - [x] **Task title**  (#<sub-issue>)

• Use labels like:
  • phase-0, phase-1, … phase-5
  • core, integration, tooling, docs, performance, research