CleverCase

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)

ChannelDirectionAuth
RSP Gateway https://gateway.rakontevr.ai/v1CleverCase → RakontevrRAKONTEVR_SERVICE_KEY (service PAT)
@rakontevr/sdk (vendored in vendor/rakontevr/sdk/)CleverCase → Rakontevrsame service key, set at SDK init
necromancy@0.5.x (CodeArtifact npm)CleverCase docs/extractCodeArtifact auth via AWS profile
BuilderHub telemetry POST /api/builderhub/apps/{appId}/telemetryCleverCase → Rakontevrsame service key
Iorek inference /v1/iorek/askCleverCase → Rakontevrsame service key
CleverCase REST API CLEVERCASE_API_URLRakontevr → CleverCaseRAK_CLEVERCASE_SERVICE_KEY

What is NOT allowed:

  • Importing from rakontevr source packages (no ../../../../src/, no workspace file:../../../)
  • Shelling out to the rakontevr monorepo (rak necromancy, ~/Code/rakontevr) — use CodeArtifact packages instead
  • Calling raw localhost:1234 / localhost:11434 inference (use Iorek via Gateway)
  • Hardcoding rakontevr internal URLs — all from .rakontevr/tenant.json or env

See REPO-BOUNDARIES.md for the full contract and npm run check:boundaries.

Environment variables (CleverCase side)

VarPurpose
RAKONTEVR_SERVICE_KEYPAT for calling RSP Gateway / BuilderHub APIs
RAKONTEVR_GATEWAY_URLOverride gateway (default: https://gateway.rakontevr.ai/v1)
RAKONTEVR_TENANT_IDCleverCase tenant UUID for metering attribution
NEXT_PUBLIC_RAKONTEVR_APP_IDBuilderHub app registration ID

These are provisioned by:

rak client provision-full --email <dev@> --client clevercase   # writes .env.local block

Integration layers in this repo

LayerPathPurpose
SDKvendor/rakontevr/sdk/src/telemetry.tscreateTelemetryClient() — reports service calls
API wrappersrc/lib/clevercase/platform/with-cc-api.tsPer-route tenant context + non-blocking telemetry
Middlewaresrc/middleware.tsBridges x-cc-trace-id ↔ X-Trace-Id
Tenant config.rakontevr/tenant.jsontenantId, gatewayUrl, serviceKeyRef

Every CleverCase API route:

  1. Accepts or generates X-Trace-Id
  2. Resolves tenant context (resolveTenantContext)
  3. Calls handler via withCcApi() wrapper
  4. Reports non-blocking telemetry to rakontevr (taskType: clevercase-api)
  5. Returns x-trace-id + x-span-id on every response

Development quick start

# Keys already provisioned
clevercase setup       # MCP + .env.local
clevercase whoami      # verify service key + tenant
npm run dev            # app on :3001

Packages in this repo

PackageDescription
packages/rak-plugin-clevercaseDomain logic (cases, matters, clients, conflicts) — was ejected from rakontevr subtree
packages/cursor-plugin-clevercaseCursor 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_ID

MCP 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 DB

Security

See docs/RUSAKOV-SHIELD-TENANT.md for sealed env, response sanitization, and PHI/ABA compliance posture.

On this page