From 63b9611887d247b4c62c4a65bac96ab86838e093 Mon Sep 17 00:00:00 2001 From: Writer Date: Sun, 4 Oct 2026 18:58:01 +0200 Subject: [PATCH 1/2] The README draws the services that run today The architecture diagram still showed the timeline as a component of its own and the connectors as a generic box, while the timeline is a package inside the engine and the first connector is its own repository. It also left out service-conventions and the schema each service owns, and the status line called the project early development while the organization page marks every phase done. The diagram now shows connector-apaleo calling the engine's REST API with an X-API-Key header, each service on its own PostgreSQL schema as their application.yaml files name it, and both taking service-conventions at the release they vendor. The status says how the work is built and points to the organization page for what is done and what comes next, so it does not go stale as slices land. Verified: the diagram renders with mmdc, and sh conventions/conventions-check, sh conventions/conventions-format and sh conventions/conventions-sync check passed. Process: Delivery Phase: Implement Track: Prose Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1500640..e464e2a 100644 --- a/README.md +++ b/README.md @@ -34,24 +34,28 @@ Matching is one of six concepts with a reference document of its own, each answe ```mermaid flowchart TB subgraph commercial["Commercial — guestgraph.io (planned)"] - SAAS["Managed hosting · MCP server · console"] + SAAS["Managed hosting · MCP access · console"] end - subgraph oss["Open source — Apache 2.0 (this org)"] - CONN["Connectors — PMS, POS, booking ..."] - TL["Timeline — unified guest journey"] - CORE["Core — identity resolution engine
+ guest graph + REST API"] + subgraph oss["Open source — Apache 2.0"] + CONN["connector-apaleo
the first connector, more to come"] + CORE["engine
identity resolution, guest graph,
timeline, REST API"] + SVC["service-conventions
parent build, error shape,
architecture tests"] end - PG[("PostgreSQL")] - - SAAS --> CONN & TL - CONN --> CORE - TL --> CORE - CORE --> PG + CDB[("PostgreSQL
schema apaleo_connector")] + EDB[("PostgreSQL
schema engine")] + + SAAS --> CORE + CONN -- "REST · X-API-Key" --> CORE + CONN --- CDB + CORE --- EDB + CORE & CONN -- "vendored at a release" --> SVC ``` +The engine holds the guest graph and serves the API every other component is a client of; the timeline is a part of it, not a service beside it. A connector reaches one external system and submits what it finds to that API, so a deployment can run the engine alone or several connectors against one engine. Each service owns its schema and connects as a role that sees nothing else, and both take their parent build and shared rules from [service-conventions](https://github.com/guestgraph/service-conventions) at the release their `service-conventions.json` names. + ## Status -🚧 **Early development.** The core identity resolution service is being built spec-first — see [`docs/`](docs/) and [`.specify/`](.specify/) for the design and specs. +Built spec-first in the open, one slice at a time: each slice's specification is in [`specs/`](specs/), and the design behind them in [`docs/`](docs/) and [`.specify/`](.specify/). Which slices are done and what comes next is on the [guestgraph organization page](https://github.com/guestgraph), and what a slice left for a later one is in [`docs/roadmap-notes.md`](docs/roadmap-notes.md). ## Stack From 11cc18bd2992d43e7aaf9454401f6e7ce8168d23 Mon Sep 17 00:00:00 2001 From: Writer Date: Sun, 4 Oct 2026 19:10:45 +0200 Subject: [PATCH 2/2] The README links the services drawing instead of keeping one AGENTS.md of the organization's profile repository says which services run and what they talk to is owned by the profile alone, and that a component diagram copied into a repository README is drift. The corrected diagram is therefore taken out again: the section keeps what is the engine's own, that it serves the API every other component is a client of and holds the timeline, and links the profile's What runs for the rest. Verified: conventions-check and conventions-format pass. Process: Delivery Phase: Implement Track: Prose Co-Authored-By: Claude Opus 5.5 (1M context) --- README.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/README.md b/README.md index e464e2a..3abf4b9 100644 --- a/README.md +++ b/README.md @@ -31,27 +31,7 @@ Matching is one of six concepts with a reference document of its own, each answe ## How it fits together -```mermaid -flowchart TB - subgraph commercial["Commercial — guestgraph.io (planned)"] - SAAS["Managed hosting · MCP access · console"] - end - subgraph oss["Open source — Apache 2.0"] - CONN["connector-apaleo
the first connector, more to come"] - CORE["engine
identity resolution, guest graph,
timeline, REST API"] - SVC["service-conventions
parent build, error shape,
architecture tests"] - end - CDB[("PostgreSQL
schema apaleo_connector")] - EDB[("PostgreSQL
schema engine")] - - SAAS --> CORE - CONN -- "REST · X-API-Key" --> CORE - CONN --- CDB - CORE --- EDB - CORE & CONN -- "vendored at a release" --> SVC -``` - -The engine holds the guest graph and serves the API every other component is a client of; the timeline is a part of it, not a service beside it. A connector reaches one external system and submits what it finds to that API, so a deployment can run the engine alone or several connectors against one engine. Each service owns its schema and connects as a role that sees nothing else, and both take their parent build and shared rules from [service-conventions](https://github.com/guestgraph/service-conventions) at the release their `service-conventions.json` names. +The engine holds the guest graph and serves the API every other component is a client of; the timeline is a part of it, not a service beside it. Which services run, what each exposes and holds, and what they talk to is drawn once, under [What runs](https://github.com/guestgraph/.github/blob/main/profile/README.md#-what-runs) on the guestgraph organization page, and not repeated here. ## Status