[onutc]

Summary

Shared channel installs need a cleaner long-term model before Slack workspace installs grow more special cases.
This documents a provider-agnostic schema that separates the external provider install, internal connection, Spritz runtime backing, and per-channel route policy.
It also pins the naming decisions we discussed: provider = slack is valid in this domain, while core targetType, preset, runtime, and scopeType fields should not be part of the generic installation key.

What Changed

This adds one Spritz architecture doc for the channel installation data model.
The doc defines the recommended tables, routing behavior, UI/API shape, and migration path from the current combined installation row.

• Added channel_installation for the provider app installation.
• Added channel_connection for one or more internal connections under that install.
• Added spritz_channel_connection for Spritz-specific preset and runtime binding state.
• Added channel_route for per-channel routing and requireMention policy.
• Documented how Slack no-mention channels still work under workspace install mode.

Testing

This is a docs-only change.
I checked the staged markdown diff for whitespace errors.

• git diff --cached --check

Risks

Runtime behavior does not change in this PR.
The main risk is naming churn during implementation review, but the doc calls out the terms that should stay out of the generic schema.

[gitrank-connector]

👍 GitRank PR Analysis

Score: 20 points

Metric	Value
Component	Other (1× multiplier)
Severity	P2 - Medium (20 base pts)
Final Score	20 × 1 = 20

Eligibility Checks

Check	Status
Issue/Bug Fix	❌
Fix Implementation	✅
PR Documented	✅
Tests	✅
Lines Within Limit	✅

Impact Summary

This PR establishes a long-term data model for shared channel installations by separating provider installations, internal connections, Spritz runtime state, and per-channel routing policies. It includes three architecture documents (1,355 lines), new API endpoints for configuration and route management, Slack gateway enhancements for policy handling, and comprehensive test coverage. The changes enable future support for multiple connections per installation and per-channel mention policies without mixing provider-specific and deployment-specific concerns.

Analysis Details

Component Classification: This PR introduces architectural documentation and supporting code for a new data model, spanning multiple subsystems (API, Slack gateway, storage contracts). It doesn't fit neatly into a single component category, making OTHER the appropriate classification.

Severity Justification: This is a P2 (Medium) contribution. It adds significant new functionality (channel installation data model, configuration projection, route management) with comprehensive tests and documentation, but it is primarily architectural/foundational work rather than fixing a critical bug or addressing an immediate production issue.

Eligibility Notes: Tests are required and included: the PR adds 154 lines of test code in internal_bindings_test.go covering configuration projection, null handling, and default preservation, plus 110 lines in backend_client_test.go and 324 lines in gateway_test.go. The fix_implementation check passes because code changes align with the architectural design documented in the PR. The pr_linked check passes due to comprehensive description and related documentation references. This is not a bug fix (issue=false) but rather a feature/architecture implementation.

---

Analyzed by GitRank 🤖

[onutc]

Final validation report

• Merged to main: 1252162f0280e34b1f4dc4197109a98b8b95c6dc.
• Local validation passed: go test ./... in api, go test ./... in integrations/slack-gateway, and git diff --check.
• codex review --base main reran clean.
• Settings UI verified through staging gateway auth headers at /slack-gateway/settings/channels and /slack-gateway/settings/channels/installations/ci_1/connections/cc_1.
• Platform staging deploy succeeded: https://github.com/textcortex/platform/actions/runs/24918068165.
• Final Spritz staging deploy succeeded after the OpenClaw projection follow-up: https://github.com/textcortex/platform/actions/runs/24918631097.
• Live Slack smoke passed twice in C0ANJGDB4Q5 without mentioning the bot.