Shared Model Contracts: A Simpler Approach to Distributed Architecture

There's a moment in every software project when you realise you've been approaching a problem entirely backwards. For Ooloi, that moment came whilst implementing the frontend gRPC client. What I'd anticipated would be a tedious exercise in data transformation and type marshalling turned out to be something rather more straightforward: we could simply share the models themselves.

Most applications suffer from what I've come to think of as 'linguistic impedance mismatch': the same business concept gets expressed differently in TypeScript interfaces, JSON schemas, database models, and API contracts. Each translation introduces potential for drift, bugs, and the sort of maintenance headaches that make senior developers reach for the gin before lunch.

The Usual Compromises

When I began implementing Ooloi's frontend, I expected to follow the well-trodden path of recreating backend data models for the client, probably with a good deal of manual conversion between Clojure's rich data types and whatever could survive the journey through gRPC.

A Simpler Path Forward

But then something rather straightforward happened. Our unified gRPC architecture, built around a custom OoloiValue message format, was preserving not just the data but the semantic fidelity of Clojure structures. Ratios remained ratios. Keywords stayed keywords. Nested collections maintained their exact shape and type information.

The implications were rather obvious once I thought about it: if the data was surviving the round trip with perfect fidelity, the code could make the same journey. The broader lesson here applies beyond Clojure: when your serialisation layer preserves semantic fidelity, you can often eliminate entire categories of translation logic.

Shared Models in Practice

What we ended up with is shared model contracts across distributed systems. Not just shared schemas or interface definitions, but shared implementation: the same defrecord structures, the same predicates, the same multimethod dispatch logic working identically in frontend and backend.

For example, here's client code that uses the exact same model logic as the server:

​This isn't just syntactic sugar. The frontend literally cannot represent a state that the backend would reject, because they're using identical validation logic. Entire categories of bugs, the sort that usually emerge only in production when client and server expectations diverge, simply cannot exist.

For an open source project like Ooloi, this architectural decision has profound implications for contributor experience. New developers don't need to learn separate model definitions for frontend and backend. The cognitive load of understanding the system drops considerably when there's only one way to represent musical structures, regardless of which part of the codebase you're working in.

Architecture in Practice

What started as a practical decision to move some data models has led to a clearer architectural arrangement:

• The Shared Project contains the entire Ooloi engine: all domain models, interfaces, predicates, traits, and core business logic. This is where musical knowledge lives.
• The Backend Project is essentially a server wrapper: a thin layer that exposes the shared engine through gRPC, handles persistence, and manages component lifecycle.
• The Frontend Project is a UI wrapper: JavaFX components, user interaction handling, visual rendering.

Both frontend and backend have become lightweight adapters around a shared core, rather than independent systems that happen to communicate.

For those interested in the technical details, the complete architectural decision record is available in our ADR-0023: Shared Model Contracts.

Why This Approach Is Uncommon

Most teams face barriers that make shared models impractical: different programming languages between frontend and backend, runtime environment constraints, the natural tendency for teams to optimise for their specific context rather than maintaining shared abstractions.

We've managed to sidestep these issues through a combination of technological choices (Clojure everywhere, gRPC with custom serialisation) and architectural discipline (resisting the urge to optimise locally at the expense of global coherence). For open source projects, this consistency becomes particularly valuable: contributors can focus on domain logic rather than navigating translation layers between different parts of the system.

What This Means for Multi-Language Support

Importantly, this shared model architecture doesn't create barriers for non-Clojure clients. Python, JavaScript, or WebAssembly clients continue to work through the standard gRPC interface, using generated protobuf classes and standard API patterns. The shared models represent a Clojure-specific enhancement layer that sits atop the universal gRPC interface rather than replacing it.

Think of it as offering two levels of integration: the universal protobuf API that any language can consume, and the native Clojure API that provides richer semantics for those who can take advantage of it.

Alternative Frontend Approaches

This architecture actually makes it easier for others to build alternative frontends. Someone wanting to create a React-based web interface or a WebAssembly client has a clearly defined gRPC API to work against, with well-documented behaviour established through our shared contracts. They'd handle their own data model representations (the normal situation for any gRPC client) whilst benefiting from a well-defined backend.

We're not digging a moat here. Alternative approaches remain viable whilst the shared contracts make the Clojure experience particularly seamless.

The Broader Picture

There's something here that extends beyond the specific technical details of Ooloi. We've found that perfect type fidelity across network boundaries, combined with clear thinking about what constitutes core business logic versus infrastructure concerns, can enable patterns that many teams dismiss as impractical.

This doesn't mean every project should adopt this approach. The organisational and technical discipline required is considerable. But for projects where the complexity is justified (particularly open source projects where reducing cognitive load for contributors is crucial) the benefits are substantial.

Looking Forward

Going forward developing Ooloi's frontend, the shared model contracts have become foundational to how we think about the system. Features that might have required careful coordination between teams now flow naturally from shared understanding. The system has become more coherent and, importantly for an open source project, more approachable for new contributors.

The surprise wasn't that shared models worked; it was how much friction simply disappeared once we stopped duplicating concepts. Sometimes architectural progress comes not through invention, but through subtraction. Shared model contracts weren't a goal we set out to achieve. They emerged from following our technical choices to their logical conclusion and having the discipline not to complicate what worked.