# gorse-io/gorse architecture

> Architecture diagram of the GitHub repository gorse-io/gorse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gorse-io/gorse
- Repository: https://github.com/gorse-io/gorse

## Overview

Gorse imports user, item, and feedback data, trains recommendation models on the master, computes offline recommendations on workers, and serves REST requests through server nodes. The README documents recommendation sources including latest, collaborative filtering, user-to-user, item-to-item, and LLM-based approaches. The graph combines those documented capabilities with source-index references and excerpts; several subsystem links are documented at a high level because their implementation files were not sampled.

Main entry points: [`logics/recommend.go`](https://github.com/gorse-io/gorse/blob/master/logics/recommend.go) (Recommendation logic), [`master/tasks.go`](https://github.com/gorse-io/gorse/blob/master/master/tasks.go) (Training tasks), [`worker/pipeline.go`](https://github.com/gorse-io/gorse/blob/master/worker/pipeline.go) (Offline pipeline), [`master/master.go`](https://github.com/gorse-io/gorse/blob/master/master/master.go) (Master service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cluster["Cluster services"]
  node_master["Master service<br/>[master.go]"]
  node_tasks["Training tasks<br/>[tasks.go]"]
  node_worker["Worker service<br/>[worker.go]"]
  node_pipeline["Offline pipeline<br/>[pipeline.go]"]
  node_server["REST server<br/>[server.go]"]
  node_rest["REST endpoints<br/>[rest.go]"]
end

subgraph group_recommend["Recommendation"]
  node_logic["Recommendation logic<br/>[recommend.go]"]
  node_itemitem["Item-to-item<br/>[item_to_item.go]"]
  node_collaborative["Collaborative filtering<br/>[model.go]"]
  node_ctr["CTR model<br/>[fm_xla.go]"]
  node_neural["Tensor operations<br/>[tensor.go]"]
  node_ann["Vector index<br/>[hnsw.go]"]
end

subgraph group_persistence["Data and storage"]
  node_data[("Data store<br/>[database.go]")]
  node_cache[("Recommendation cache<br/>[database.go]")]
  node_vectors[("Vector store<br/>[database.go]")]
  node_blob[("Blob storage<br/>[blob.go]")]
  node_meta[("Model metadata<br/>[database.go]")]
end

subgraph group_operations["Admin and interfaces"]
  node_admin["Admin CLI<br/>[main.go]"]
  node_adminclient["Admin client<br/>[admin.go]"]
end

node_consumer(("API consumer"))

node_consumer -->|"requests recommendations"| node_rest
node_rest -->|"served by"| node_server
node_server -->|"syncs metadata"| node_master
node_master -->|"runs training"| node_tasks
node_worker -->|"fetches metadata"| node_master
node_worker -->|"runs recommendations"| node_pipeline
node_pipeline -->|"uses recommenders"| node_logic
node_tasks -->|"generates recommendations"| node_logic
node_tasks -->|"trains model"| node_collaborative
node_tasks -->|"trains model"| node_ctr
node_tasks -->|"reads training data"| node_data
node_tasks -->|"stores model metadata"| node_meta
node_pipeline -->|"updates recommendations"| node_cache
node_pipeline -->|"loads items"| node_data
node_logic -->|"reads recommendation data"| node_data
node_logic -->|"reads cached results"| node_cache
node_logic -->|"uses vector storage"| node_vectors
node_logic -.->|"supports item similarity"| node_itemitem
node_logic -.->|"supports nearest neighbors"| node_ann
node_ctr -.->|"uses tensor operations"| node_neural
node_worker -->|"loads model artifacts"| node_blob
node_admin -->|"calls admin API"| node_adminclient
node_master -->|"connects configured store"| node_data

click node_master "https://github.com/gorse-io/gorse/blob/master/master/master.go"
click node_tasks "https://github.com/gorse-io/gorse/blob/master/master/tasks.go"
click node_worker "https://github.com/gorse-io/gorse/blob/master/worker/worker.go"
click node_pipeline "https://github.com/gorse-io/gorse/blob/master/worker/pipeline.go"
click node_server "https://github.com/gorse-io/gorse/blob/master/server/server.go"
click node_rest "https://github.com/gorse-io/gorse/blob/master/server/rest.go"
click node_logic "https://github.com/gorse-io/gorse/blob/master/logics/recommend.go"
click node_itemitem "https://github.com/gorse-io/gorse/blob/master/logics/item_to_item.go"
click node_collaborative "https://github.com/gorse-io/gorse/blob/master/model/cf/model.go"
click node_ctr "https://github.com/gorse-io/gorse/blob/master/model/ctr/fm_xla.go"
click node_neural "https://github.com/gorse-io/gorse/blob/master/common/nn/tensor.go"
click node_ann "https://github.com/gorse-io/gorse/blob/master/common/ann/hnsw.go"
click node_data "https://github.com/gorse-io/gorse/blob/master/storage/data/database.go"
click node_cache "https://github.com/gorse-io/gorse/blob/master/storage/cache/database.go"
click node_vectors "https://github.com/gorse-io/gorse/blob/master/storage/vectors/database.go"
click node_blob "https://github.com/gorse-io/gorse/blob/master/storage/blob/blob.go"
click node_meta "https://github.com/gorse-io/gorse/blob/master/storage/meta/database.go"
click node_admin "https://github.com/gorse-io/gorse/blob/master/cmd/gorse-cli/main.go"
click node_adminclient "https://github.com/gorse-io/gorse/blob/master/client/admin.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_master,node_tasks,node_worker,node_pipeline,node_server,node_rest toneBlue
class node_logic,node_itemitem,node_collaborative,node_ctr,node_neural,node_ann toneAmber
class node_data,node_cache,node_vectors,node_blob,node_meta,node_consumer toneMint
class node_admin,node_adminclient toneRose
```

## Components

### Cluster services

- [Master service](https://github.com/gorse-io/gorse/blob/master/master/master.go): `master/master.go`
- [Training tasks](https://github.com/gorse-io/gorse/blob/master/master/tasks.go): `master/tasks.go`
- [Worker service](https://github.com/gorse-io/gorse/blob/master/worker/worker.go): `worker/worker.go`
- [Offline pipeline](https://github.com/gorse-io/gorse/blob/master/worker/pipeline.go): `worker/pipeline.go`
- [REST server](https://github.com/gorse-io/gorse/blob/master/server/server.go): `server/server.go`
- [REST endpoints](https://github.com/gorse-io/gorse/blob/master/server/rest.go): `server/rest.go`

### Recommendation

- [Recommendation logic](https://github.com/gorse-io/gorse/blob/master/logics/recommend.go): `logics/recommend.go`
- [Item-to-item](https://github.com/gorse-io/gorse/blob/master/logics/item_to_item.go): `logics/item_to_item.go`
- [Collaborative filtering](https://github.com/gorse-io/gorse/blob/master/model/cf/model.go): `model/cf/model.go`
- [CTR model](https://github.com/gorse-io/gorse/blob/master/model/ctr/fm_xla.go): `model/ctr/fm_xla.go`
- [Tensor operations](https://github.com/gorse-io/gorse/blob/master/common/nn/tensor.go): `common/nn/tensor.go`
- [Vector index](https://github.com/gorse-io/gorse/blob/master/common/ann/hnsw.go): `common/ann/hnsw.go`

### Data and storage

- [Data store](https://github.com/gorse-io/gorse/blob/master/storage/data/database.go): `storage/data/database.go`
- [Recommendation cache](https://github.com/gorse-io/gorse/blob/master/storage/cache/database.go): `storage/cache/database.go`
- [Vector store](https://github.com/gorse-io/gorse/blob/master/storage/vectors/database.go): `storage/vectors/database.go`
- [Blob storage](https://github.com/gorse-io/gorse/blob/master/storage/blob/blob.go): `storage/blob/blob.go`
- [Model metadata](https://github.com/gorse-io/gorse/blob/master/storage/meta/database.go): `storage/meta/database.go`

### Admin and interfaces

- [Admin CLI](https://github.com/gorse-io/gorse/blob/master/cmd/gorse-cli/main.go): `cmd/gorse-cli/main.go`
- [Admin client](https://github.com/gorse-io/gorse/blob/master/client/admin.go): `client/admin.go`

### Other components

- **API consumer**

## Connections

- API consumer → REST endpoints: requests recommendations (evidence: `README.md`)
- REST endpoints → REST server: served by (evidence: `server/server.go`)
- REST server → Master service: syncs metadata (evidence: `server/server.go`)
- Master service → Training tasks: runs training (evidence: `README.md`)
- Worker service → Master service: fetches metadata (evidence: `worker/worker.go`)
- Worker service → Offline pipeline: runs recommendations (evidence: `worker/worker.go`)
- Offline pipeline → Recommendation logic: uses recommenders (evidence: `worker/pipeline.go`)
- Training tasks → Recommendation logic: generates recommendations (evidence: `master/tasks.go`)
- Training tasks → Collaborative filtering: trains model (evidence: `master/tasks.go`)
- Training tasks → CTR model: trains model (evidence: `master/tasks.go`)
- Training tasks → Data store: reads training data (evidence: `master/tasks.go`)
- Training tasks → Model metadata: stores model metadata (evidence: `master/tasks.go`)
- Offline pipeline → Recommendation cache: updates recommendations (evidence: `worker/pipeline.go`)
- Offline pipeline → Data store: loads items (evidence: `worker/pipeline.go`)
- Recommendation logic → Data store: reads recommendation data (evidence: `logics/recommend.go`)
- Recommendation logic → Recommendation cache: reads cached results (evidence: `logics/recommend.go`)
- Recommendation logic → Vector store: uses vector storage (evidence: `logics/recommend.go`)
- Recommendation logic → Item-to-item: supports item similarity
- Recommendation logic → Vector index: supports nearest neighbors
- CTR model → Tensor operations: uses tensor operations
- Worker service → Blob storage: loads model artifacts (evidence: `worker/worker.go`)
- Admin CLI → Admin client: calls admin API (evidence: `cmd/gorse-cli/main.go`)
- Master service → Data store: connects configured store
