Start here

This site documents the RecSys suite: a production-ready set of modules for building, shipping, and operating a recommendation system.

Quick paths

• Quickstart (minimal)
  Fastest path to a non-empty POST /v1/recommend + an exposure log.
• Minimum components by goal
  Decide DB-only vs artifact/manifest mode and what you need to run.
• Evaluation, pricing, and licensing (buyer guide)
  Recommended evaluation path + procurement-ready links.

Who this is for

• New evaluators of the RecSys suite
• Engineers who want the shortest path to a runnable local setup
• Stakeholders who need the “what do we get, what do we need?” overview

What you will get

• A recommended reading and execution path (tutorial → concepts → integration)
• Role-based entry points (lead dev, recsys engineer, stakeholder, SRE)
• Links to the canonical contracts, API, and operational runbooks

Recommended path

1. Run the suite locally end-to-end
2. Tutorial: local end-to-end (service → logging → eval)
3. If you want the fastest possible first success: Quickstart (minimal)

4. Optional: production-like artifacts + ship/rollback: production-like run (pipelines → object store → ship/rollback)

5. Understand the architecture and data flow

6. Diagram: Suite Context
7. One-page mental model: How it works: architecture and data flow
8. Explanation: Suite architecture
9. Repo layout: Repo layout and Go module paths

10. Known limitations: Known limitations and non-goals (current)

11. Integrate, operate, and validate

12. Integrate the API: How-to: integrate recsys-service into an application
13. Operate pipelines: How-to: operate recsys-pipelines
14. Run evaluation and ship decisions: How-to: run evaluation and make ship decisions

Role-based entry points

Developer / platform engineer

• Suite architecture and contracts:
• Suite architecture
• Data contracts
• Configuration reference
• OpenAPI spec (YAML)
• Security overview: Security, privacy, and compliance (overview)

Recommendation engineer / ML engineer

Start here: RecSys engineering hub

• Ranking core:
• recsys-algo
• Pipelines outputs:
• Output layout (local filesystem)

Product / business stakeholder

• What the suite is and what it takes to pilot:
• What the RecSys suite is (stakeholder overview)
• Pilot plan (2–6 weeks)
• ROI and risk model
• Responsibilities (RACI): who owns what
• Operational reliability and rollback
• Security and privacy overview: Security, privacy, and compliance (overview)
• Licensing and pricing: Licensing

• Support model: Support

• What to expect from evaluation and decisions:

• Interpreting results: how to go from report to decision
• Metrics: what we measure and why

SRE / on-call

• Operational runbooks:
• Runbook: Service not ready
• Runbook: Empty recs
• Runbook: Roll back config/rules
• Security overview: Security, privacy, and compliance (overview)
• Runbook: Pipeline failed
• Runbook: Validation failed
• Runbook: Limit exceeded
• Runbook: Stale artifacts

Read next

• Local end-to-end tutorial: local end-to-end (service → logging → eval)
• Stakeholder overview: What the RecSys suite is (stakeholder overview)
• Suite architecture: Suite architecture