Architecture clarification: OpenClaw (upstream) + Iskander Cooperative API (our Python code) = complementary layers

[Argocyte]

The relationship (clarified by Lola, 2026-04-12)

The upstream openclaw/openclaw (355k stars, TypeScript, MIT) is the runtime platform — it handles message routing across 25+ channels (Mattermost, Matrix, WhatsApp, Telegram, etc.), provides the Gateway architecture, and has a skill/plugin system.

Iskander's Python code at src/IskanderOS/openclaw/ is the cooperative governance API — the FastAPI service that provides the S3 governance tools (Loomio bridge, Glass Box audit, tension tracking, labour logging, member provisioning, meeting prep) that make a generic OpenClaw installation Iskander-specific.

Lola's explanation: "once openclaw is installed, Iskander inserts the agent skills and plugins to make the openclaw environment iskander specific. the python code acts at the interface/api."

The architecture

Member on Mattermost / Matrix / WhatsApp / etc.
        ↓
OpenClaw Gateway (upstream TypeScript — handles channels, routing, skill dispatch)
        ↓
Iskander Skills (installed into OpenClaw's skill system — TypeScript or bridge)
        ↓
Iskander Cooperative API (Python FastAPI — the src/IskanderOS/openclaw/ code)
        ↓
Loomio / Decision Recorder / Glass Box / Mattermost governance bridge

What this means

1. Rename proposal: src/IskanderOS/openclaw/ should be renamed to something that reflects its actual role — e.g. src/IskanderOS/cooperative-api/ or src/IskanderOS/iskander-api/. It is not OpenClaw; it is the API that OpenClaw's Iskander skills call into.

2. Deployment model: K3s runs both the upstream OpenClaw Gateway (Node.js container) AND the Iskander Cooperative API (Python container). Members interact with OpenClaw; OpenClaw calls the Iskander API for governance operations.

3. Testing model: Alyssa needs to test TWO things separately: (a) the upstream OpenClaw installation + channel configuration, and (b) the Iskander Cooperative API + its external service dependencies. Then integration: OpenClaw skill → Iskander API → Loomio/DR response.

4. D10 (OpenClaw agent review) reframing: the review isn't about refactoring the Python agents — it's about designing the Iskander skills that bridge OpenClaw's TypeScript skill system to the Python Cooperative API. The Clerk/Steward/Sentry agents become OpenClaw skills that call HTTP endpoints on the Cooperative API.

5. IskanderHearth deployment: the Hearth tiers now need to account for running BOTH Node.js (OpenClaw Gateway) and Python (Iskander API) runtimes. Tier 1 Seed needs enough RAM for both.

Open questions

• What's the best pattern for OpenClaw skills that call an external HTTP API? Does the upstream skill system support this natively, or do we need a bridge plugin?
• Should the Iskander skills be TypeScript (native to OpenClaw) calling the Python API via HTTP, or should we explore OpenClaw's Python bridge (if one exists)?
• Does the rename from openclaw/ to cooperative-api/ (or similar) need a PR, or should it wait until the D10 review lands the full architectural redesign?

---

Posted by Et under G5 Communications domain sovereignty. This is an architectural clarification, not a decision — the ADR comes from phase-b-architecture domain after the full D10 review.

[Argocyte]

Note: The three-question ADR that follows from this architectural clarification is tracked at Discussion #191. This discussion (#190) establishes the complementary-layers relationship; #191 scopes the specific decisions that follow from it. They are companion threads, not duplicates — #190 is the context, #191 is the decision. — Et