Platform Integration Contract
How CleverCase communicates with Rakontevr — approved channels, environment variables, and integration layers.
CleverCase V2 — Platform Integration
CleverCase is a standalone service — it has been ejected from the rakontevr git subtree. The two repos talk only via approved, authenticated channels. No workspace imports. No shared code.
Integration contract (enforced)
| Channel | Direction | Auth |
|---|---|---|
RSP Gateway https://gateway.rakontevr.ai/v1 | CleverCase → Rakontevr | RAKONTEVR_SERVICE_KEY (service PAT) |
@rakontevr/sdk (vendored in vendor/rakontevr/sdk/) | CleverCase → Rakontevr | same service key, set at SDK init |
necromancy@0.5.x (CodeArtifact npm) | CleverCase docs/extract | CodeArtifact auth via AWS profile |
BuilderHub telemetry POST /api/builderhub/apps/{appId}/telemetry | CleverCase → Rakontevr | same service key |
Iorek inference /v1/iorek/ask | CleverCase → Rakontevr | same service key |
CleverCase REST API CLEVERCASE_API_URL | Rakontevr → CleverCase | RAK_CLEVERCASE_SERVICE_KEY |
What is NOT allowed:
- Importing from
rakontevrsource packages (no../../../../src/, no workspacefile:../../../) - Shelling out to the rakontevr monorepo (
rak necromancy,~/Code/rakontevr) — use CodeArtifact packages instead - Calling raw
localhost:1234/localhost:11434inference (use Iorek via Gateway) - Hardcoding rakontevr internal URLs — all from
.rakontevr/tenant.jsonor env
See REPO-BOUNDARIES.md for the full contract and npm run check:boundaries.
Environment variables (CleverCase side)
| Var | Purpose |
|---|---|
RAKONTEVR_SERVICE_KEY | PAT for calling RSP Gateway / BuilderHub APIs |
RAKONTEVR_GATEWAY_URL | Override gateway (default: https://gateway.rakontevr.ai/v1) |
RAKONTEVR_TENANT_ID | CleverCase tenant UUID for metering attribution |
NEXT_PUBLIC_RAKONTEVR_APP_ID | BuilderHub app registration ID |
These are provisioned by:
rak client provision-full --email <dev@> --client clevercase # writes .env.local blockIntegration layers in this repo
| Layer | Path | Purpose |
|---|---|---|
| SDK | vendor/rakontevr/sdk/src/telemetry.ts | createTelemetryClient() — reports service calls |
| API wrapper | src/lib/clevercase/platform/with-cc-api.ts | Per-route tenant context + non-blocking telemetry |
| Middleware | src/middleware.ts | Bridges x-cc-trace-id ↔ X-Trace-Id |
| Tenant config | .rakontevr/tenant.json | tenantId, gatewayUrl, serviceKeyRef |
Every CleverCase API route:
- Accepts or generates
X-Trace-Id - Resolves tenant context (
resolveTenantContext) - Calls handler via
withCcApi()wrapper - Reports non-blocking telemetry to rakontevr (
taskType: clevercase-api) - Returns
x-trace-id+x-span-idon every response
Development quick start
# Keys already provisioned
clevercase setup # MCP + .env.local
clevercase whoami # verify service key + tenant
npm run dev # app on :3001Packages in this repo
| Package | Description |
|---|---|
packages/rak-plugin-clevercase | Domain logic (cases, matters, clients, conflicts) — was ejected from rakontevr subtree |
packages/cursor-plugin-clevercase | Cursor rules + skills for CleverCase development |
Build: npm run build:rak-plugin
RSP pipeline (tenant-scoped)
Tenant-scoped RSP runs record tenantId when RAK_TENANT_ID is set:
rak stories list --tenant clevercase # requires DATABASE_URL + RAK_TENANT_IDMCP rsp_stories respects RAK_TENANT_ID from .cursor/mcp.json env.
Migrations
SQL migrations live in packages/rak-plugin-clevercase/migrations/.
Run against the CleverCase DB (clevercase_staging) — never against the platform DB.
clevercase db migrate # applies pending migrations to CleverCase DBSecurity
See docs/RUSAKOV-SHIELD-TENANT.md for sealed env, response sanitization, and PHI/ABA compliance posture.