app-specific.md

App-specific guidance

Part of the OpenCrane agent guidance. See AGENTS.md for the index.

Read the package's own README.md before non-trivial work. General TypeScript rules (typescript.md), identity rules (architecture.md), and Kubernetes rules (k8s.md) apply throughout. Before changing an app's production or deployment contract, also read versioning.md and stamp the app to the current root version in the same slice. Documentation-only changes do not advance an app stamp.

Apps

App	Responsibility
apps/opencrane	Authenticated REST API, durable product authority, process composition, Prisma, and the server Helm unit.
apps/conversation-computer	Generation-fenced process image for an Agent Sandbox conversation computer.
apps/opencrane-ui	Angular web client for organisation and employee surfaces.
apps/memory-gateway	Private Cognee transport boundary that TokenReviews the server identity.
apps/agent-controller	Sole Kubernetes mutator for governed one-shot Jobs.
apps/mcp-executor	One-shot token-holding companion for OCI-backed MCP Jobs.
apps/mcp-file-generator	Thin process and OCI image for credentialless CSV generation; logic lives in its runtime library.
libs/backend/agents/runtime/mcp-file-generator/main	Strict CSV arguments, deterministic bytes and the loopback MCP endpoint.
apps/artifact-service	Governed artifact byte promotion and receipt service.
apps/artifact-preprocessor	Broker-only document extraction worker.
apps/artifact-scanner	Broker-only malware scanner for quarantined revisions.
apps/skill-authoring	Isolated candidate-skill Job plane.
apps/postgres	OpenCrane-owned PostgreSQL deployment and clean baseline bootstrap.
apps/_infra	Third-party deployment wrappers and the Kubernetes release composer.

Apps are thin composition roots. Reusable behaviour belongs in a library, and no app imports another app's source.

Backend libraries

Group	Responsibility
libs/backend/agents/personal/*	Persona, verified personal-memory selection, and configuration authorities owned by a person.
libs/backend/agents/execution/*	Immutable run inputs, run lifecycle, and runtime protocol admission.
libs/backend/agents/execution/elicitation	Recoverable participant input, exact response authority, and purpose-specific completion.
libs/backend/agents/runtime/*	Kubernetes Job projection, controller orchestration, and class-neutral workload claim contracts.
libs/backend/agents/skills/*	Governed skill authoring, workflow admission, and execution workloads.
libs/backend/artifacts/*	Artifact authorization, storage, preprocessing, and fenced malware scanning.
libs/backend/artifacts/preprocessor	PDF workflow controller, one-shot Job policy, and broker-only worker.
libs/backend/server	API capabilities grouped by agents, IAM, gateways, knowledge, reporting, and organisation scope.
libs/backend/server/iam/organization-members	Settings member directory and standalone invitation authority, or fail-closed delegation of the whole capability to Fleet billing.
libs/backend/server/iam/audit-writer	Transaction-scoped append-only authorization decision evidence with no read or policy dependency.
libs/backend/server/agents/onboarding	Durable, session-owner-bound onboarding route state and exact persona/bootstrap references.
libs/backend/server/conversations	main owns participant authorization, metadata and computer commands; history owns encrypted ordered history; computers owns checked computer projections. Each has its own public entrypoint and dependency boundary.
libs/backend/server/conversation-assets	Participant upload, quarantine, scan, and message-attachment authority.
libs/backend/server/infra	OpenCrane server runtime, transport, identity, and external-I/O seams.
libs/backend/server/infra/history-store	KurrentDB stream reads, checked appends, and subscriptions for event-history owners.
libs/backend/server/infra/agent-sandbox	Kubernetes SandboxClaim realization and lease-bound Pod verification.
apps/_infra/kurrentdb	Private KurrentDB HistoryStore deployment with persistent TLS-only storage.
apps/_infra/agent-sandbox	Release-scoped Agent Sandbox templates, zero-replica warm pools, and claim admission boundaries.
libs/backend/server/infra/workflows	Workflow-engine task contract, guardrails, finite respawn chains, the Absurd adapter, and deterministic test support.
libs/backend/server/infra/oci-registry	Digest-checked OCI Distribution client used by image admission.
libs/backend/server/infra/organization-membership-gateway	HTTPS and projected-token transport to Fleet membership and billing authority.
libs/backend/observability	Cross-cutting structured logging and execution tracing.
libs/backend/memory-gateway/main	Private memory provider authentication and protocol handling, composed only by the memory-gateway app.
libs/backend/conversation-computer/review-surface	Sandbox-local, lease-authenticated file, command, preview, and Chromium review adapters.

The durable product authority is Conversation -> immutable KurrentDB entry stream. An agent_session may activate one generation-fenced conversation computer through Agent Sandbox. Direct and ordinary group messages create no computer activation. The computer receives a bounded bootstrap and proposes output; it never becomes a second conversation, approval, or artifact authority.

Server infrastructure

libs/backend/server/infra contains process-specific seams for HTTP, authentication, Kubernetes access, projected workload identity, the runtime stream, memory, credential custody, KurrentDB history, and sandbox execution. These packages contain no business-domain authority. libs/backend/server/infra/workflows adds the workflow-task seam without taking ownership of product scheduling or aggregate writes.

Frontend libraries

Angular libraries under libs/frontend/* feed apps/opencrane-ui:

• core and platform hold cross-cutting browser primitives;
• elements/* contains presentational components;
• features/* contains routed user-interface slices; and
• state/* contains gateway ports, live adapters, caches, and browser state.

The governed persona onboarding path is split deliberately:

• features/onboarding owns one routed shell with interview, tie-resolution, review, and ready state components;
• models/user-onboarding owns the validated first-chat projection and pure runtime parser;
• state/onboarding owns the transport-neutral port, route and conflict-envelope validation, and resumable orchestration without becoming a persistence authority;
• state/onboarding/projection exposes only the projection vocabulary to the onboarding feature; and
• state/persona/adapter is the typed adapter over the generated signed-in-owner API.

Recoverable conversation input follows the same ownership direction:

• elements/elicitation owns the four typed draft controls;
• features/conversation-elicitation owns the recoverable card and separate submit intent;
• features/conversation-activity owns safe failure disclosure and canonical deep-link intents; and
• state/conversation/elicitation owns the generated-client gateway, command state, reconciliation, and derived Activity rows.

elements/conversation owns shared message, composer, and status presentations. The 0.11 workspace renders immutable conversation history directly; the retired relational Agent-thread projection has no separate child route.

Read-only reporting follows the same dependency direction:

• features/governance owns audit and usage child routes, route-local read state and separate result components;
• state/governance owns generated read contracts, validation and a narrow port; and
• state/governance/adapter implements the existing protected reads. The app binds the adapter and reader identity and composes the Settings shell, member routes and reporting routes. No browser role hint grants read authority.

The normal conversation workspace keeps transport, state, and presentation separate:

• features/conversation-workspace owns chat child routes, route coordination, and browser-safe presentation composition;
• state/conversation/workspace owns snapshot-tail selection, immutable creation choices, controlled drafts, access purge, and separate run command state;
• state/conversation/workspace/adapter maps the generated signed-in API into that port; and
• state/conversation/stream owns the transport-neutral browser stream port; the workspace reuses its state/conversation/adapter implementation for direct, group, and Agent-session conversations instead of creating another stream path.

Organisation membership uses the same browser authority boundary:

• features/settings owns the settings shell, member directory presentation, invitation form, and public acceptance route;
• state/organization/members owns the transport-neutral directory, create, resend, and acceptance stores and gateway port; and
• state/organization/members/adapter maps the generated signed-in API into that port without interpreting Fleet payment policy.

Legacy frontend packages use scope:web; new capability slices use bounded ownership scopes. The persona onboarding feature, state port, and adapter use scope:persona-onboarding plus role tags that enforce feature → state and adapter → state/core direction. Cross-cutting core and UI elements use scope:shared. The pure first-chat projection and validator live in models/user-onboarding under scope:user-onboarding; both onboarding state and conversation workspace may consume that model, without gaining access to each other's stores or commands. The onboarding feature consumes only the narrow state/onboarding/projection facade, so the general feature role does not gain access to arbitrary model packages. The UI is an API client, never a privileged product authority.

API-first rule

Every product capability must be usable through the authenticated OpenCrane API. The web client, generated clients, and custom integrations are peers over the same contract.

Package navigation

Every app, library, and grouping directory has a README.md. When a package is added, moved, or deleted, update its own README, its parent map, and this page in the same change. Follow package-docs.md.