While building GILLZY, a digital goods marketplace, I ended up working on a problem that appears in almost every sufficiently large marketplace:
How do you turn behavioral events and catalog candidates into explainable, safe, and reproducible recommendation decisions?
At first, recommendation logic tends to be simple.
Fetch some products.
Calculate a score.
Sort them.
Return the top N.
But as a marketplace grows, the pipeline quickly becomes more complicated:
- multiple candidate sources;
- feature signals;
- deterministic ranking;
- model-assisted scoring;
- diversity constraints;
- business and safety guardrails;
- exploration;
- fallbacks;
- telemetry attribution;
- explainability;
- experimentation.
The problem is that these systems often become tightly coupled to one product and one private database schema.
So I extracted the reusable parts into an independent Apache-2.0 open-source project:
GMF Core
GMF Core is an open-source recommendation, ranking, telemetry, and decisioning engine designed for marketplaces and discovery products.
GitHub:
https://github.com/Muhail01/GMF-Core
Current release: v0.1.0
The pipeline
Event Ingest
↓
Candidate Providers
↓
Feature Signals
↓
Deterministic Baseline Ranking
↓
Optional Model Scoring
↓
Diversity Rerank
↓
Policy / Guardrails
↓
Controlled Exploration
↓
Explainable Decision
↓
Decision Log + Transactional Outbox
↓
Impression / Click / Outcome Telemetry
The core idea is that a recommendation should not be treated as just a sorted list.
It is a decision.
**Every response gets a stable decision_id,** which allows downstream impression, click, and outcome events to be connected back to the exact decision that produced the result.
What is included in v0.1.0
The current release already includes:
standalone Go API;
pluggable candidate providers;
deterministic weighted ranking;
stable tie-breaking;
optional model-assisted scoring;
deterministic model rollout;
automatic fallback to baseline ranking;
diversity-aware reranking;
policy and guardrails;
controlled exploration;
explainable score breakdowns;
persisted decision lookup;
PostgreSQL storage;
in-memory storage;
transactional outbox;
reference outbox worker;
idempotent telemetry ingestion;
TypeScript telemetry SDK;
OpenAPI 3.1;
Docker Compose;
property and fuzz tests;
benchmarks;
privacy-safe observability hooks;
automated CI and public-boundary checks.
**The project intentionally does not contain private marketplace data**, production ranking coefficients, fraud logic, payment systems, KYC, paid advertising billing, credentials, or proprietary model configuration.
The public core is vendor-neutral.
Run the full stack
The reference stack includes GMF Core, PostgreSQL, and the outbox worker.
git clone https://github.com/Muhail01/GMF-Core.git
cd GMF-Core
docker compose up --build
Check that the API is alive:
curl -s http://localhost:8080/healthz
Request recommendations:
curl -s -X POST http://localhost:8080/v1/recommendations \
-H 'Content-Type: application/json' \
-d '{
"surface":"home",
"session_id":"demo-session",
"limit":4,
"context":{"category":"games"}
}'
The response contains a decision_id, ranked items, scores, reason codes, and score breakdowns.
You can then retrieve the persisted decision:
curl -s http://localhost:8080/v1/decisions/<decision-id>
And send telemetry linked to that exact decision:
curl -s -X POST http://localhost:8080/v1/events \
-H 'Content-Type: application/json' \
-d '{
"event_id":"evt-1",
"event_type":"recommendation_impression",
"session_id":"demo-session",
"decision_id":"<decision-id>",
"item_id":"game-1",
"surface":"home"
}'
This gives you a full chain:
**recommendation request**
→ decision
→ ranked items
→ score breakdown
→ persisted decision
→ impression
→ click
→ outcome
Why deterministic ranking still matters
One design decision I wanted to preserve is that the system must remain useful even without an external model.
The baseline ranking path is deterministic.
Optional model scoring can be enabled on top of it, but model failure does not make the recommendation system unavailable.
The intended behavior is:
baseline ranking
↓
optional model scorer
↓
model available? ── yes → hybrid result
│
no
↓
safe baseline fallback
This makes it possible to experiment with learned ranking without turning the model provider into a single point of failure.
Explainability
Each returned item can include a score breakdown and reason code.
Instead of returning only:
item A
item B
item C
the system can preserve information about why those items were selected and how the final ranking was produced.
That becomes useful for:
debugging;
experiments;
model comparison;
ranking regressions;
policy analysis;
telemetry attribution.
Transactional outbox
**Decisions and telemetry** events can be persisted together with outbox messages.
The reference worker is intentionally provider-neutral.
A deployment can connect it to systems such as:
Kafka;
NATS;
webhooks;
queues;
analytical pipelines.
The core itself does not require one specific messaging vendor.
What I am looking for now
The project is still early, and I would especially appreciate technical feedback on:
the decision pipeline;
API boundaries;
ranking and reranking abstractions;
model fallback semantics;
feature-store integration;
telemetry contracts;
transactional outbox design;
observability.
I have also opened contribution-sized issues for things such as:
Go client SDK;
Python SDK;
React telemetry hooks;
Redis decision cache;
Prometheus integration;
OpenTelemetry integration;
Kafka outbox sink;
NATS outbox sink;
ClickHouse telemetry storage;
feature-store provider interface;
benchmark documentation.
Some are intentionally marked as good first issue so that contributors do not need to understand an entire marketplace codebase before making a useful first contribution.
Repository
⭐ GMF Core:
https://github.com/Muhail01/GMF-Core
**The project is licensed under Apache-2.0.**
I am particularly interested in criticism from people who have worked on recommendation systems, ranking infrastructure, marketplaces, experimentation platforms, or large-scale telemetry systems.
What would you change in this architecture before building a v0.2?
Top comments (1)
I appreciate how GMF Core emphasizes the importance of treating a recommendation as a decision, rather than just a sorted list, by assigning a stable decision_id to each response. This approach allows for more accurate telemetry attribution and explainability, as shown in the example where you can retrieve a persisted decision and send telemetry linked to that exact decision. The inclusion of deterministic baseline ranking and optional model-assisted scoring also provides a robust foundation for making informed decisions. Have you considered exploring the use of reinforcement learning to further optimize the decisioning process, particularly in the context of controlled exploration and diversity-aware reranking?