Architecture

Module Overview

clotho-core
  Zero Spring dependency.
  All mapping, session, registry, and query logic.

clotho-spring-boot-starter
  Spring Boot 3.x autoconfiguration.
  Thin layer: creates beans, bridges @Transactional, scans @ClothoRepository.
  Depends on clotho-core.

clotho-dev-app
  Minimal Spring Boot application.
  Connected to a live ArcadeDB instance.
  Used throughout development for real-DB testing.
  Not a production artifact; not published.

clotho-core Component Map

ClothoSessionFactory  (entry point)
  │  Holds: DriverRemoteConnection, TypeRegistry, global config
  │
  ├── TypeRegistry
  │     Built once at startup from classpath scan.
  │     Maps: ArcadeDB label → Class<? extends ClothoEntity>
  │     Knows: Java + ArcadeDB inheritance hierarchy, additionalParents
  │
  └── ClothoSession  (unit of work, one per transaction/request)
        │  Holds: identity map (ARID → ClothoEntity instance)
        │
        ├── load(Class<T>, ARID) → T
        │     └── SubgraphLoader
        │           Uses: TypeRegistry, ObjectMapper
        │           Executes Gremlin traversal for root vertex + @Include boundary
        │           Cycle detection via visited-ARID set
        │
        ├── save(entity)
        │     └── SubgraphPersistor
        │           Upserts root vertex/edge + all @Include elements recursively
        │           Uses ArcadeDB @version for optimistic locking
        │           @SubgraphType: iterates all ClothoEntity fields, saves each
        │
        ├── delete(entity)
        │     Removes root vertex/edge from graph
        │     Does NOT cascade deletion to @Include elements
        │
        └── query(Class<T>, queryName, params) → List<T>
              └── QueryExecutor
                    Resolves named @Query, binds params, executes, maps results
                    Also drives @ClothoRepository proxy methods

ObjectMapper  (used by SubgraphLoader and QueryExecutor)
  Gremlin Vertex/Edge → ClothoEntity subclass
  Always uses most-specific registered class (TypeRegistry lookup by label)
  Sets @Property fields, @OutVertex/@InVertex fields on edges

SubgraphTypeAssembler  (used by QueryExecutor for @SubgraphType returns)
  Maps Gremlin select() result map → @SubgraphType fields
  Binding: field name or @Alias → select key
  Each bound value is mapped via ObjectMapper

Data Flow: Loading a Composite Object

Developer:  session.load(Order.class, arid)
    │
    ▼
SubgraphLoader
  1. g.V(arid.asString())                → TinkerPop Vertex (Order)
  2. ObjectMapper.map(vertex)            → Order instance (most-specific class)
  3. Register in identity map
  4. For each @Include field on Order:
       @Include @Via("HAS_LINE") List<OrderLine> lines
       ┌──────────────────────────────────────────┐
       │ g.V(arid).out("HAS_LINE")               │
       │   → [TinkerPop Vertex, Vertex, ...]      │
       │   for each: ObjectMapper.map(v)          │
       │     → OrderLine (or subtype by label)    │
       │   recurse: load OrderLine @Include fields│
       └──────────────────────────────────────────┘
  5. Assemble Order.lines = [OrderLine, ...]
  6. Return fully assembled Order

Data Flow: Saving a Composite Object

Developer:  session.save(order)
    │
    ▼
SubgraphPersistor
  1. Upsert root Order vertex
       if order.getId() == null → create vertex with label "Order"
       else                    → update vertex, check @version (optimistic lock)
  2. For each @Include field on Order:
       Field type is @VertexType (e.g., List<OrderLine>):
         for each element → recursively save (SubgraphPersistor.save(orderLine))
         ensure edge "HAS_LINE" exists from Order to OrderLine
       Field type is @EdgeType (e.g., List<WorksAt>):
         save edge properties; ensure @OutVertex and @InVertex are already persisted
  3. Identity map deduplication: elements already saved in this call are skipped
  4. Removed elements: NOT deleted automatically

Data Flow: `@Query` on a `@ClothoRepository`

Developer:  employeeQueries.findByDepartment("Engineering")
    │
    ▼
ClothoRepository proxy (generated by QueryExecutor at startup)
  1. Read @Query gremlin string from method annotation
  2. Bind @Param values: replace :dept with "Engineering"
  3. Execute: g.V().hasLabel('Employee').has('dept','Engineering')
  4. For each result vertex:
       ObjectMapper.map(vertex) → most-specific Employee subclass
  5. Return List<Employee>

For @SubgraphType return:

  3. Execute query with select() → List of Maps
  4. For each Map:
       SubgraphTypeAssembler.assemble(EmployeeProfile.class, map)
         → bind map keys to fields by name / @Alias
         → ObjectMapper.map() each value
  5. Return List<EmployeeProfile>

Session Identity Map

The identity map is the session's in-memory cache of loaded vertices and edges.

Key: ARID
Value: ClothoEntity instance

Rules:

First load of an ARID → fetch from DB, map to Java, store in map, return
Subsequent load of same ARID → return existing instance (no DB call)
save() does NOT clear the identity map; the instance is mutated in place
close() clears the map and releases the Gremlin connection

The map operates at the individual vertex/edge level. Multiple composite objects (e.g., an Order and an EmployeeProfile) may both hold references to the same Address instance if their traversals reached the same ARID.

TypeRegistry Startup Validation

At ClothoSessionFactory.build() time, the TypeRegistry validates:

Every @VertexType class extends ClothoVertex
Every @EdgeType class extends ClothoEdge
No two classes claim the same label
additionalParents labels are resolvable to registered classes
parentLabel values are resolvable to registered classes
Every @Include field is paired with @Via
@OutVertex / @InVertex field types are @VertexType classes

Startup failure with a descriptive message is strongly preferred over silent misconfiguration that produces confusing runtime errors.

Package Structure

com.binarygolem.clotho
  .model
    ClothoEntity
    ClothoVertex
    ClothoEdge
    ARID
    UnknownTypeBehavior

  .annotation
    VertexType
    EdgeType
    SubgraphType
    RID
    Property
    Include
    Via
    Direction
    OutVertex
    InVertex
    Alias
    Query
    Queries          (container for @Repeatable @Query)
    Param
    ClothoRepository

  .session
    ClothoSession
    ClothoSessionFactory
    ClothoSessionFactoryBuilder

  .registry
    TypeRegistry
    TypeRegistryBuilder
    TypeDescriptor     (holds metadata for one registered type)

  .mapping
    ObjectMapper
    SubgraphLoader
    SubgraphPersistor
    SubgraphTypeAssembler

  .query
    QueryExecutor
    QueryDescriptor    (holds parsed @Query metadata for one method)
    ParameterBinder

  .exception
    ClothoException
    UnknownTypeException
    OptimisticLockException
    ClothoConfigurationException

// clotho-spring-boot-starter
com.binarygolem.clotho.spring
  .config
    ClothoAutoConfiguration
    ClothoProperties
  .tx
    ClothoTransactionManager
    ClothoTransactionObject
  .repository
    ClothoRepositoryScanner
    ClothoRepositoryProxyFactory

7.5 KiB Raw Blame History