Services overview
| Service | Project | Port | One job | Owns |
|---|---|---|---|---|
| Taxonomy API | Kaleido.Taxonomy.Api | 8080 | Catalogue, taxonomy, tagging, similarity, MCP, and the front door for GRE | public schema, raw HTML |
| Activity | Kaleido.Gre.Activity | 8081 | Store every transaction and session idempotently; serve per-game signals | activity schema |
| Simulator | Kaleido.Gre.Simulator | 8082 | Invent customers, replay or stream their play, measure accuracy | simulator schema |
| Profile | Kaleido.Gre.Profile | 8083 | Turn activity into per-customer, per-game affinities (batch) | profile schema |
| Recommender | Kaleido.Gre.Recommender | 8084 | Blend signals into a ranked, explained list; obey player protection | recommender schema, in-memory catalogue |
| Ingest | Kaleido.Gre.Ingest | 8085 | Keep live per-customer state in Redis from Kafka | Redis c:*, cfg:ingest:* |
Shared libraries (Contracts, Hosting, Telemetry, Stream) are described in Shared libraries, and the React front end in Web app.
Common patterns
Every GRE service follows the same shape, which keeps them small and predictable.
| Pattern | How it shows up |
|---|---|
| Minimal API host | Program.cs registers telemetry, the service key, the DbContext, typed HttpClients and hosted services, then maps endpoints. |
/health | Unauthenticated 200 ok on every service. |
| Auto-migrate | EF migrations run at start-up unless Db:AutoMigrate=false. |
| Settings as data | Tunables live in a one-row settings table with a Revision that increments on every PUT /settings. A build records the revision it used. |
| Draft settings | Endpoints that score accept an unsaved draft of the settings in the body, so the UI can compare before saving. Drafts are never cached. |
| Background builds | POST /builds returns 202 and enqueues an id on an in-process Channel. A BackgroundService works through builds one at a time. A second request while one is queued or running gets 409. |
| Build-tagged rows | Each build writes rows tagged with its id, then deletes rows from older builds at the end. Customers or links that disappeared drop out without a separate cleanup. |
| Restart safety | On start-up, builds left Running or Queued are marked Failed with "Interrupted by a restart." |
DELETE /data | Resets what the service learned, for the simulation. A real feed never calls it. |
| Paged bulk reads | Cursor paging by key (after=<last id>), never offsets, so pages stay fast and stable. |
Background workers
| Service | Worker | Trigger | Does |
|---|---|---|---|
| Taxonomy API | TaggingProcessor | Polls every 2 s (100 ms while busy) | Claims up to 3 queued tagging items and runs them against the AI provider |
| Taxonomy API | PipelineSampler | Every second while a viewer is connected | Samples GRE services and broadcasts over SignalR |
| Profile | BuildWorker | POST /builds | Rebuilds every customer's affinities |
| Recommender | BuildWorker | POST /builds or BuildScheduler | Catalogue build and crowd build |
| Recommender | BuildScheduler | Every Builds:CheckSeconds | Starts catalogue or crowd builds on their configured cadence |
| Recommender | CatalogueCache | Every 15 s | Reloads the in-memory catalogue when a build finished or the day changed |
| Recommender | SuppressionCache | Every 5 s | Reloads the player-protection list |
| Ingest | IngestSupervisor | Every 2 s | Starts, replaces or stops one SourceConsumer per enabled ingestion |
| Ingest | SourceConsumer | Continuous | Kafka batch to Redis to offset commit |
| Simulator | RunWorker | POST /runs | Generates customers and posts their activity |
| Simulator | StreamRunner | POST /streams | Publishes a simulated world to Kafka at a target rate |