Architecture Overview

​

Three-Layer Architecture Diagram

​

Architecture Layers

​

Layer 1: StashClient (GraphQL Transport)

• Execute GraphQL queries and mutations
• Handle HTTP/WebSocket transports
• Manage retries and connection pooling
• Deserialize responses to Pydantic models

from stash_graphql_client import StashContext

async with StashContext(conn={...}) as client:
    # Direct GraphQL operations
    scenes = await client.find_scenes()
    performer = await client.create_performer(Performer(name="Alice"))
    job_id = await client.metadata_scan()

​

Layer 2: Pydantic Types (Schema/ORM Layer)

• UNSET Pattern - Three-state fields distinguish “set to value”, “set to null”, and “never touched”
• UUID4 Auto-generation - New objects get temporary IDs replaced with server IDs on save
• Bidirectional Relationships - Automatic sync between related entities
• Tracked Fields - __tracked_fields__ and __field_conversions__ for change detection
• Relationship Metadata - __relationships__ documents query strategies and inverse fields

from stash_graphql_client.types import Scene, UNSET

# Create with partial data - UUID4 auto-generated
scene = Scene(title="My Scene", rating100=85)
print(f"New object ID: {scene.id}")  # UUID4 hex string (32 chars)
print(f"Is new: {scene.is_new()}")   # True

# Save sends only non-UNSET fields
await scene.save(client)
print(f"Server ID: {scene.id}")      # Server-assigned ID
print(f"Is new: {scene.is_new()}")   # False

# Update tracks changes
scene.rating100 = 90
changed = scene.get_changed_fields()  # {"rating100": 90}
await scene.save(client)  # Only sends changed fields

​

Layer 3: StashEntityStore (Identity Map & Caching)

• Identity Map - Same entity ID → same object reference
• Read-Through Caching - Fetch from cache or query on miss
• TTL Support - Optional cache expiration
• Field-Aware Population - Load missing fields on demand
• Django-Style Filtering - field__modifier kwargs
• Lazy Iteration - Paginate large result sets efficiently
• Thread-Safe - Uses RLock for concurrent access

from stash_graphql_client import StashEntityStore
from stash_graphql_client.types import Scene, Performer

store = StashEntityStore(client, default_ttl=300)

# Read-through caching
performer = await store.get(Performer, "123")

# Django-style filtering
top_rated = await store.find(Scene, rating100__gte=80)
unrated = await store.find(Scene, rating100__null=True)

# Field-aware population
await store.populate(performer, fields=["scenes", "images"])

# Get-or-create pattern
tag = await store.get_or_create(Tag, name="Action")

​

When to Use Each Layer

​

Use StashClient when:

• ✅ Making one-off queries
• ✅ Need direct control over GraphQL queries
• ✅ Working with entity types that don’t need caching
• ✅ Executing mutations that return complex results

​

Use Pydantic Types when:

• ✅ Creating new entities with validation
• ✅ Need ORM-like .save() / .delete() methods
• ✅ Working with entity relationships
• ✅ Need change tracking for partial updates

​

Use StashEntityStore when:

• ✅ Need object identity across queries
• ✅ Making repeated queries for same entities
• ✅ Using Django-style filtering
• ✅ Need field-aware population
• ✅ Processing large result sets with pagination

​

Related Documentation

• Identity Map Architecture - Deep dive on wrap validators and caching
• Library Comparisons - How this compares to alternatives
• Bidirectional Relationships - Relationship sync implementation
• Overview Guide - General overview and design philosophy