Internal Architecture Guide

June 11, 2026 · View on GitHub

This guide covers TypeBridge's internal type system, architecture decisions, and implementation details.

Internal Type System
Modern Python Type Hints
Type Checking and Static Analysis
Keyword-Only Arguments
Modular Architecture
Connection Architecture
Descriptor Contract
Deprecated APIs

Internal Type System

ModelAttrInfo Dataclass

The codebase uses ModelAttrInfo (defined in models/utils.py) as a structured type for attribute metadata:

@dataclass
class ModelAttrInfo:
    typ: type[Attribute]  # The attribute class (e.g., Name, Age)
    flags: AttributeFlags  # Metadata (Key, Unique, Card)

IMPORTANT: Always use dataclass attribute access, never dictionary-style access:

# ✅ CORRECT
owned_attrs = Entity.get_owned_attributes()
for field_name, attr_info in owned_attrs.items():
    attr_class = attr_info.typ
    flags = attr_info.flags

# ❌ WRONG - Never use dict-style access
attr_class = attr_info["type"]   # Will fail!
flags = attr_info["flags"]       # Will fail!

AttributeFlags

The AttributeFlags dataclass stores attribute metadata:

@dataclass
class AttributeFlags:
    is_key: bool = False
    is_unique: bool = False
    card_min: int | None = None
    card_max: int | None = None
    has_explicit_card: bool = False
    name: str | None = None  # Override attribute type name
    case: TypeNameCase | None = None  # Case formatting for type name

Usage in code:

# Check if attribute is a key
if attr_info.flags.is_key:
    # Handle key attribute

# Get cardinality
if attr_info.flags.card_min is not None or attr_info.flags.card_max is not None:
    # Handle cardinality constraints

# Override attribute type name
class Name(String):
    flags = AttributeFlags(name="person_name")

# Use case formatting
class UserEmail(String):
    flags = AttributeFlags(case=TypeNameCase.SNAKE_CASE)  # -> user_email

TypeFlags

The TypeFlags dataclass stores entity/relation metadata:

@dataclass
class TypeFlags:
    type_name: str | None = None
    abstract: bool = False
    case: str = "snake_case"  # Or "kebab-case", "camelCase", etc.

Usage patterns:

# Define entity with TypeFlags
class Person(Entity):
    flags = TypeFlags(name="person")

# Define abstract entity
class Animal(Entity):
    flags = TypeFlags(abstract=True)

# Custom type name casing
class MyEntity(Entity):
    flags = TypeFlags(name="my-entity", case="kebab-case")

Attribute Metadata Collection

TypeBridge automatically collects attribute metadata during class definition:

class Entity:
    def __init_subclass__(cls):
        """Automatically collects TypeFlags and owned attributes from type annotations."""
        # 1. Collect TypeFlags
        cls._flags = getattr(cls, "flags", TypeFlags())

        # 2. Collect owned attributes from annotations
        cls._owned_attrs = {}
        for field_name, field_type in get_type_hints(cls).items():
            if is_attribute_type(field_type):
                # Extract attribute class and flags
                attr_class, flags = extract_attribute_info(field_type, field_name, cls)
                cls._owned_attrs[field_name] = ModelAttrInfo(typ=attr_class, flags=flags)

This enables automatic schema generation without explicit configuration.

Modern Python Type Hints

The project follows modern Python typing standards (Python 3.12+):

1. PEP 604: Union Type Syntax

Use X | Y instead of Union[X, Y]:

# ✅ Modern (Python 3.10+)
age: int | str | None

# ❌ Deprecated
from typing import Union, Optional
age: Optional[Union[int, str]]

Application in TypeBridge:

# Optional fields
class Person(Entity):
    name: Name = Flag(Key)
    age: Age | None = None  # PEP 604 syntax

2. PEP 695: Type Parameter Syntax

Use type parameter syntax for generics:

# ✅ Modern (Python 3.12+)
class EntityManager[E: Entity]:
    def __init__(self, entity_class: type[E]):
        self.entity_class = entity_class

    def insert(self, entity: E) -> E:
        ...

# ❌ Old style (still works but verbose)
from typing import Generic, TypeVar
E = TypeVar("E", bound=Entity)
class EntityManager(Generic[E]):
    def __init__(self, entity_class: type[E]):
        self.entity_class = entity_class

    def insert(self, entity: E) -> E:
        ...

Benefits:

Cleaner syntax
Better IDE support
Matches modern Python standards

3. No Linter Suppressions

Code should pass ruff and pyright without needing # noqa or # type: ignore comments:

# ✅ CORRECT: No suppressions needed
def process_entity(entity: Entity) -> str:
    return entity.get_type_name()

# ❌ WRONG: Avoid suppressions
def process_entity(entity):  # type: ignore
    return entity.get_type_name()

Exception: Tests intentionally checking validation failures may show type warnings. These tests are in tests/unit/type-check-except/ and excluded from type checking via pyrightconfig.json.

Type Checking and Static Analysis

@dataclass_transform Decorators

TypeBridge uses PEP-681 @dataclass_transform decorators on Entity and Relation classes to improve type checker support:

from typing import dataclass_transform

@dataclass_transform(kw_only_default=True)
class Entity(BaseModel):
    """Base class for all entities."""
    ...

Benefits:

Type checker recognition of Flag() as a valid field default
Automatic __init__ signature inference from class annotations
Better IDE autocomplete and type hints
Keyword-only arguments enforced (improved code clarity and safety)

Type Checker Support

TypeBridge is fully compatible with:

Pyright: Microsoft's static type checker (used in VS Code)
MyPy: Optional, but TypeBridge is MyPy-compatible
Pydantic's type system: Built on Pydantic v2

Current status:

✅ 0 type errors with Pyright
✅ 0 type warnings (except in type-check-except tests)
✅ Full type inference for managers and queries

Type Checking Limitations

TypeBridge achieves 0 type errors with Pyright, but there are some edge cases:

1. Optional Fields in Queries

When using field references with optional fields, Pyright may incorrectly infer the type:

class Person(Entity):
    score: PersonScore | None = None  # Optional field

# Pyright may warn about optional field access
high_scorers = manager.filter(Person.score.gt(PersonScore(90)))  # May show warning

Solution: Use attribute class methods instead of field references for optional fields:

# ✅ RECOMMENDED: Attribute class method (no warnings)
high_scorers = manager.filter(PersonScore.gt(PersonScore(90)))

# Also works, but may trigger type checker warnings
high_scorers = manager.filter(Person.score.gt(PersonScore(90)))

2. Validation Tests

Tests that intentionally check Pydantic validation behavior use raw values and are excluded from type checking via pyrightconfig.json:

{
  "exclude": ["tests/unit/type-check-except/**"]
}

These tests verify that runtime validation works correctly, even when type checkers would flag the code.

Minimal `Any` Usage

The project minimizes Any usage for type safety:

Where Any is used:

Flag() function: Accepts Any for parameters to handle type aliases like Key and Unique

def Flag(*args: Any) -> AttributeFlags:
    """Create attribute flags from Key, Unique, Card arguments."""
    ...

Flag() return type: Returns AttributeFlags (used as field default)

class Person(Entity):
    name: Name = Flag(Key)  # Flag() returns AttributeFlags

Pydantic core schema methods: Use proper TypeVars (StrValue, IntValue, etc.)

@classmethod
def __get_pydantic_core_schema__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> CoreSchema:
    ...

Where Any is NOT used:

✅ No other Any types in the core attribute system
✅ All managers are fully typed with generics
✅ All queries preserve type information
✅ All entity/relation operations are type-safe

Keyword-Only Arguments

TypeBridge enforces keyword-only arguments for Entity and Relation constructors using @dataclass_transform(kw_only_default=True).

Why Keyword-Only?

Clarity: Explicit field names make code self-documenting
Safety: Type checkers catch argument order mistakes
Maintainability: Adding fields doesn't break existing code
Prevention: Eliminates entire class of positional argument bugs

Usage Pattern

from type_bridge import Entity, TypeFlags, String, Integer, Flag, Key

class Name(String):
    pass

class Age(Integer):
    pass

class Person(Entity):
    flags = TypeFlags(name="person")
    name: Name = Flag(Key)
    age: Age | None = None  # Optional field requires explicit = None

# ✅ CORRECT: Keyword arguments required
person = Person(name=Name("Alice"), age=Age(30))
person2 = Person(name=Name("Bob"))  # age is optional

# ❌ WRONG: Positional arguments not allowed
person = Person(Name("Alice"), Age(30))  # Type error!

Optional Fields Require Explicit Defaults

Optional fields (marked with | None) must have an explicit = None default:

# ✅ CORRECT: Explicit defaults for optional fields
class Person(Entity):
    name: Name = Flag(Key)          # Required field
    age: Age | None = None           # Optional with explicit = None
    email: Email | None = None       # Optional with explicit = None

# ❌ WRONG: Missing defaults on optional fields
class Person(Entity):
    name: Name = Flag(Key)
    age: Age | None                  # Type error: missing default!
    email: Email | None              # Type error: missing default!

Why explicit = None?

Type checking: Pyright needs explicit defaults to distinguish optional from required fields
IDE support: Autocomplete works better with explicit optionality
Code clarity: Makes intent obvious at a glance
Runtime behavior: Matches static type annotations exactly

Implementation Details

The keyword-only enforcement is implemented via @dataclass_transform:

@dataclass_transform(
    kw_only_default=True,
    field_specifiers=(Flag,)
)
class Entity(BaseModel):
    """Base class for all entities."""
    ...

This tells type checkers:

All fields are keyword-only by default
Flag() is recognized as a valid field specifier
Constructor signature is inferred from class annotations

Modular Architecture

The codebase follows a modular architecture pattern to improve maintainability and reduce file sizes:

Models Module Structure

The models/ module (previously a single 1500+ line file) is organized as:

models/
├── __init__.py    # Public exports
├── base.py        # Base model functionality
├── entity.py      # Entity class
├── relation.py    # Relation class
├── role.py        # Role definitions
└── utils.py       # ModelAttrInfo and utilities

CRUD Module Structure

The crud/ module (previously a single 3000+ line file) is organized as:

crud/
├── __init__.py       # Backward compatible exports
├── base.py           # Type variables (E, R)
├── utils.py          # Shared utilities
├── entity/           # Entity operations
│   ├── manager.py    # EntityManager
│   ├── query.py      # EntityQuery
│   └── group_by.py   # GroupByQuery
└── relation/         # Relation operations
    ├── manager.py    # RelationManager
    ├── query.py      # RelationQuery
    └── group_by.py   # RelationGroupByQuery

Design Principles

Single Responsibility: Each module has a focused purpose
Shared Utilities: Common functions in utils.py to avoid duplication
Backward Compatibility: Top-level __init__.py maintains all public exports
Clear Boundaries: Entity and Relation operations are clearly separated
Manageable Size: Files are kept between 200-800 lines for maintainability

Import Patterns

# Public API
from type_bridge import TypeDBManager

# Or from crud module
from type_bridge.crud import TypeDBManager

# Shared utilities (internal use)
from type_bridge.crud.utils import format_value, is_multi_value_attribute

Connection Architecture

TypeBridge provides a unified connection handling system for flexible transaction management.

Connection Type

The Connection type alias allows managers to accept any connection type:

from type_bridge.session import Connection, Database, Transaction, TransactionContext

# Type alias for flexible connection handling
Connection = Database | Transaction | TransactionContext

# Managers accept any Connection type
person_manager = Person.manager(db)         # Database
person_manager = Person.manager(tx)         # Transaction
person_manager = Person.manager(tx_ctx)     # TransactionContext

TransactionContext

TransactionContext enables sharing transactions across multiple operations:

from typedb.driver import TransactionType

# Create a shared transaction context
with db.transaction(TransactionType.WRITE) as tx:
    person_mgr = Person.manager(tx)     # reuses tx
    artifact_mgr = Artifact.manager(tx)  # same tx

    person_mgr.insert(alice)
    artifact_mgr.insert(artifact)
    # Both commit together on context exit

Behavior:

Auto-commit on successful context exit (WRITE/SCHEMA transactions)
Auto-rollback on exception
READ transactions never commit (no writes)

ConnectionExecutor

The internal ConnectionExecutor class handles transaction delegation:

class ConnectionExecutor:
    """Unified query execution across connection types."""

    def __init__(self, connection: Connection):
        # Extracts database/transaction from connection

    def execute(self, query: str, tx_type: TransactionType) -> list[dict[str, Any]]:
        # Uses existing transaction or creates new one

    @property
    def has_transaction(self) -> bool:
        # True if using an existing transaction

    @property
    def database(self) -> Database | None:
        # Returns database if available (for creating new transactions)

Design principles:

Transparency: CRUD operations work identically regardless of connection type
Transaction reuse: Existing transactions are never duplicated
Auto-management: Database connections create transactions as needed
Atomic operations: Bulk operations use single transactions

Usage Patterns

# Pattern 1: Simple operations (auto-managed transactions)
db = Database(address="localhost:1729", database="mydb")
Person.manager(db).insert(alice)  # Opens and commits its own transaction

# Pattern 2: Shared transaction (atomic multi-operation)
with db.transaction(TransactionType.WRITE) as tx:
    Person.manager(tx).insert(alice)
    Company.manager(tx).insert(techcorp)
    Employment.manager(tx).insert(employment)
    # All commit together

# Pattern 3: Bulk operations (single transaction internally)
Person.manager(db).insert_many(people)  # One transaction for all
Person.manager(db).update_many(people)  # One transaction for all

Every binding registers its models with the Rust core as descriptors (crates/orm/src/descriptor.rs). The registry stores descriptors as-is — it never resolves type inheritance — so each descriptor must be self-contained: runtime query building and hydration consume exactly the lists the binding provided.

Inherited members flatten into subtypes

For an entity or relation subtype, owned_attributes re-lists inherited attributes (parent declaration order first, then own). Relation roles follow the same rule with one refinement: the list is the effective role set —

plain-inherited parent roles are flattened in (parent order first),
own and specializing roles follow in declaration order,
a parent role overridden via relates child as parent is excluded.

Both bindings (Python _rust_runtime.relation_descriptor, TypeScript Relation().descriptor()) must emit byte-identical role lists; the cross-language parity suite (tests/integration/parity/) enforces this for parented and unparented types alike.

Why the effective set (engine evidence)

Decided for #139 against TypeDB 3.11.5 (probe transcript: contribution relates contributor, relates work / authoring sub contribution, relates author as contributor):

Probe	Engine verdict
`authoring` instance links a direct `contributor` player	REJECT (`INF11`: no compatible types for `links`)
`authoring` links `author` + plain-inherited `work`	ACCEPT
`match $r relates contributor`	rows: `contribution`, `authoring` (schema view keeps the edge)
`contribution` instance links `contributor` directly	ACCEPT (parent unaffected)
`match $r isa contribution, links (contributor: $x)`	rows include `authoring` (polymorphic read still works)

An overridden parent role is unplayable on subtype instances, so listing it (former TypeScript behavior) advertises a role the engine rejects; omitting plain-inherited roles (former Python behavior) starves query building and hydration of roles the engine accepts. The effective set is exactly what the engine permits at instance level.

Schema-level introspection still sees inherited relates edges (third probe row); the descriptor is an instance-facing contract, which is why playability governs.

Forward compatibility

Role specialization authoring (#140-A) extends RoleDescriptor with an overrides link. The effective-set shape composes with it: the specializing role carries overrides: <parent role>, from which the full schema picture (including the replaced parent role) is reconstructable without re-listing unplayable roles.

Abstract roles (engine evidence)

Decided for #140-A against TypeDB 3.11.5 (probe shapes: interaction @abstract, relates participant @abstract with collaboration sub interaction, relates collaborator as participant and a plain subtype chat sub interaction; plus a concrete relation meeting, relates attendee @abstract, relates room):

Probe	Engine verdict
`relates r @abstract` on an abstract relation	define ACCEPT
`relates r @abstract` on a concrete relation	define ACCEPT
Concrete relation instance links its own abstract role directly	REJECT (`INF11`)
Subtype that overrides the abstract role links it directly	REJECT (`INF11`, same as non-abstract override)
Subtype links the specializing role	ACCEPT
Plain-inheriting concrete subtype links the inherited abstract role	ACCEPT
`relates y as x @card(0..1)` (`as` before annotations)	define ACCEPT
`@abstract @card(...)` and `@card(...) @abstract` orders	both define ACCEPT

Two consequences:

Abstractness gates direct play only at the declaring type's own scope. A concrete subtype that plain-inherits an abstract role can play it, so inherited abstract roles stay in the subtype's effective role set. On the declaring relation itself the role is schema-present but unplayable on direct instances — the optional-role fetch partition already tolerates a permanently empty role.
Emission canon is free to pick one annotation order. The generator emits relates <name>[ as <parent>][ @abstract][ @card(...)]; the parser accepts either annotation order, so round-trip stability comes from the emitter's fixed canon.

plays_cardinality: authoring datum and ONE-LOWERING rule

RoleDescriptor.plays_cardinality (Option<(u32, Option<u32>)> in Rust, [number, number | null] | null in TypeScript, cardinality_tuple() result in Python) is an authoring datum on each role: it declares what cardinality the player's plays edge should carry in the generated schema.

Lifecycle:

Authoring. Each binding language writes plays_cardinality directly into the role entry in the descriptor dict. Python _rust_runtime.relation_descriptor calls cardinality_tuple(role.plays_cardinality) and places it after "cardinality" in the role dict. TypeScript roleDescriptors() copies spec.playsCardinality as plays_cardinality in the emitted role object. Both are serialized as null when absent.
Overlay construction. SchemaInfo::from_descriptors (Rust) processes plays_cardinality on each registered role and fans the value out to the plays_cardinalities map on each named player's entity/relation schema entry, keyed "{relation_type_name}:{role_name}". Foreign-parent nulling (types whose parent is absent from the registered set) is also handled here.
Emission. generate_define_block reads each player entry's plays_cardinalities map to emit @card(min..max) on the plays line.

ONE-LOWERING rule. Bindings never hand-project descriptor fields into SchemaInfo dicts. The registry path (PyDescriptorRegistry → schema_info()) is the single lowering path; the Rust from_descriptors is the single point where authoring data becomes IR. The Python attributes-section merge (per-model attribute_schema_entry loop + attribute_classes loop) is the one documented exception because attribute-class metadata (regex, range, allowed_values, etc.) is not represented in the descriptor layer and must be merged from the Python attribute class after schema_info() returns.

List interfaces (engine evidence)

Decided for #140-B against TypeDB 3.11.5 (probe shapes: owns nickname[], owns tag[] @distinct, owns pid[] @key, relation team, relates member[] @distinct, plus instance-level insert/fetch attempts):

Probe	Engine verdict
`owns attr[]`	define ACCEPT
`owns attr[] @distinct` (and `@distinct @card(0..5)`)	define ACCEPT
`owns attr[] @key`	define ACCEPT
`relates role[] @distinct`	define ACCEPT
Insert list values (`has attr[] [..]`)	REJECT (`REP256`: "List types are not yet implemented")
Fetch over a list binding (`has attr[] $n`)	REJECT (`REP256`)
List-form links insert (`links (role[]: [..])`)	REJECT (TypeQL parse error)
Plain links insert on a list-declared role (`links (role: $a, role: $b)`)	ACCEPT
Scalar match on a list-declared attribute	ACCEPT (returns no rows — no list instances can exist)

Consequence: list interfaces are schema-only on current TypeDB. The define/sync pipeline (authoring → IR → emission → generators) is fully supported and built; instance-level semantics — insertion-order preservation and @distinct duplicate rejection — are unimplemented engine-side (REP256), so the ORM cannot provide or test them. Runtime list-value support is deferred until the engine ships list instances; a live test pins the REP256 rejection so an engine upgrade that implements lists surfaces as a test failure prompting the deferred work.

Deprecated APIs

The following APIs are deprecated and should NOT be used:

Removed Type Aliases

❌ Long - Renamed to Integer to match TypeDB 3.x

# ❌ DEPRECATED
from type_bridge import Long
class Age(Long):
    pass

# ✅ USE INSTEAD
from type_bridge import Integer
class Age(Integer):
    pass

Removed Cardinality Types

❌ Cardinal - Use Flag(Card(...)) instead

# ❌ DEPRECATED
from type_bridge import Cardinal
tags: Cardinal[2, None, Tag]

# ✅ USE INSTEAD
from type_bridge import Card, Flag
tags: list[Tag] = Flag(Card(min=2))

❌ Min[N, Type] - Use list[Type] = Flag(Card(min=N)) instead

# ❌ DEPRECATED
from type_bridge import Min
tags: Min[2, Tag]

# ✅ USE INSTEAD
from type_bridge import Card, Flag
tags: list[Tag] = Flag(Card(min=2))

❌ Max[N, Type] - Use list[Type] = Flag(Card(max=N)) instead

# ❌ DEPRECATED
from type_bridge import Max
tags: Max[5, Tag]

# ✅ USE INSTEAD
from type_bridge import Card, Flag
tags: list[Tag] = Flag(Card(max=5))

❌ Range[Min, Max, Type] - Use list[Type] = Flag(Card(min, max)) instead

# ❌ DEPRECATED
from type_bridge import Range
tags: Range[1, 5, Tag]

# ✅ USE INSTEAD
from type_bridge import Card, Flag
tags: list[Tag] = Flag(Card(1, 5))

Removed Type Hint Aliases

❌ Optional[Type] - Use Type | None (PEP 604 syntax) instead

# ❌ DEPRECATED
from typing import Optional
age: Optional[Age]

# ✅ USE INSTEAD (PEP 604)
age: Age | None = None

❌ Union[X, Y] - Use X | Y (PEP 604 syntax) instead

# ❌ DEPRECATED
from typing import Union
result: Union[int, str]

# ✅ USE INSTEAD (PEP 604)
result: int | str

Removed Flag Aliases

❌ EntityFlags - Use TypeFlags instead

# ❌ DEPRECATED
from type_bridge import EntityFlags
class Person(Entity):
    flags = EntityFlags(name="person")

# ✅ USE INSTEAD
from type_bridge import TypeFlags
class Person(Entity):
    flags = TypeFlags(name="person")

❌ RelationFlags - Use TypeFlags instead

# ❌ DEPRECATED
from type_bridge import RelationFlags
class Employment(Relation):
    flags = RelationFlags(name="employment")

# ✅ USE INSTEAD
from type_bridge import TypeFlags
class Employment(Relation):
    flags = TypeFlags(name="employment")

Migration Guide

If you're updating code that uses deprecated APIs:

Step 1: Update imports

# Before
from type_bridge import Long, Optional, EntityFlags, RelationFlags, Cardinal

# After
from type_bridge import Integer, TypeFlags, Card, Flag

Step 2: Update type annotations

# Before
age: Optional[Age]
result: Union[int, str]

# After
age: Age | None = None
result: int | str

Step 3: Update cardinality

# Before
tags: Cardinal[2, None, Tag]

# After
tags: list[Tag] = Flag(Card(min=2))

Step 4: Update flags

# Before
flags = EntityFlags(name="person")
flags = RelationFlags(name="employment")

# After
flags = TypeFlags(name="person")
flags = TypeFlags(name="employment")

Why These Changes?

These deprecations provide a cleaner, more consistent API following modern Python standards:

PEP 604: Native union syntax (X | Y) is now standard in Python 3.10+
PEP 695: Type parameter syntax is cleaner in Python 3.12+
Unified API: TypeFlags works for both entities and relations
Explicit cardinality: Flag(Card(...)) is more explicit than type aliases
TypeDB 3.x alignment: Integer matches TypeDB's renamed long type

For API usage, see the User Guide.

For development guidelines, see setup.md.