> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# CRAFT Core Concepts
> Core concepts of CRAFT: organizations, projects, agents, data connections, schedules, and multi-tenancy.
# Key Concepts
This page introduces the foundational concepts you need to work with CRAFT. Understanding these concepts helps you build and operate any solution on the platform.
```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
erDiagram
Organization ||--o{ Project : "contains"
Organization ||--o{ User : "has members"
Project ||--o{ Agent : "registers"
Project ||--o{ DataConnection : "configures"
Project ||--o{ Schedule : "manages"
Project ||--o{ ContextPack : "contains"
Organization {
string org_id PK
string name
string keycloak_realm
}
Project {
string project_id PK
string org_id FK
string name
}
Agent {
string agent_id PK
string project_id FK
string protocol
}
DataConnection {
string connection_id PK
string project_id FK
string type
}
```
## Core Entities
An **organization** is the top-level tenant boundary in CRAFT. Every resource in the platform belongs to exactly one organization.
**Key characteristics:**
* Each organization maps to a single **Keycloak realm** (the realm ID equals the org ID)
* Organizations are created during the Governance service bootstrap process
* All users, projects, and resources are scoped to an organization
* Cross-organization data access is prevented at the database query level
**Identity flow:** When you authenticate, your JWT token contains the `org_id` derived from the Keycloak realm. All subsequent API calls are scoped to that organization automatically.
**Related:** [Organizations](/platform/organizations) | [Authentication](/platform/authentication)
A **project** is a logical grouping of resources within an organization. Projects enable teams to organize agents, data connections, and other assets into separate workspaces.
**Key characteristics:**
* Projects belong to an organization and inherit its permission structure
* The `project_id` is passed via the `X-Project-ID` HTTP header or as a path parameter -- it is never stored in the JWT
* Users can have different roles across different projects within the same organization
* All list queries filter by both `org_id` (from JWT) and `project_id` (from header)
**Permission inheritance:** Projects inherit permissions from their parent organization via OpenFGA. A user who is an `admin` of the organization automatically has admin-level computed permissions on all projects within it.
**Related:** [Projects](/platform/projects) | [Authorization](/platform/authorization) | [Authenticate Users (for solution developers)](/guides/solution-dev/authenticate-users)
An **agent** is a registered AI service that can be discovered, invoked, and monitored through the platform. CRAFT supports three agent ecosystems through a unified registry:
| Protocol | Description | Discovery |
| -------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **A2A** (Agent-to-Agent) | Open protocol for inter-agent communication using JSON-RPC 2.0 over SSE | Agent Cards at `/.well-known/agent-card.json` |
| **MCP** (Model Context Protocol) | Protocol for providing context to LLMs through tool definitions and resource access | MCP server metadata with tool/resource/prompt indexing |
| **agentskills.io** | Portable skill format for packaging agent capabilities | Skill packages linked to Agent Card registrations |
Agents are registered in the **Assets** service (port 8000) and can be searched across all three protocols with a single query.
**Agent lifecycle stages:** EXPERIMENTAL, STABLE, DEPRECATED, RETIRED
**Related:** [Agent Registry](/platform/agents) | [Data Insights Agents](/data-insights/overview)
A **data connection** is a configured link to an external data source registered in the platform. Solutions use data connections to access customer data without managing credentials directly.
**Key characteristics:**
* Registered in the Assets service (port 8000)
* Support databases, APIs, and file stores as data sources
* Credentials are managed through the platform Secrets API (Infisical or ESO + GCP Secret Manager)
* Scoped to an organization and project for multi-tenant isolation
* Used by Data Insights for querying customer databases
* Used by Data Governance for profiling and enrichment
**Security:** Data connection credentials are never exposed in API responses. They are stored via the platform Secrets API and injected at runtime only when a solution needs to establish a connection.
**Related:** [Data Connections](/platform/data-connections) | [Data Source Setup Guide](/guides/data-source-setup)
A **schedule** defines recurring execution of tasks such as data profiling runs, agent health checks, or report generation. Schedules are managed by the **Utils** service (port 8000).
**Key characteristics:**
* Cron-based scheduling with timezone support
* Scoped to an organization and project
* Integrated with the platform's permission system (requires `can_execute` permission)
* Execution history and status tracking
**Related:** [Schedules](/platform/schedules)
**Webhooks are planned for an upcoming release.** The webhook system will provide HTTP callbacks to notify external systems when platform events occur. Planned capabilities include HMAC-signed payloads, configurable event filters, automatic retry with exponential backoff, and SSRF protection.
**Related:** [Webhooks (Planned)](/platform/webhooks)
Multi-tenancy in CRAFT provides complete isolation between organizations while allowing flexible access control within each organization.
**Isolation model:**
* **Authentication isolation:** Each organization is a separate Keycloak realm with its own user directory, identity providers, and SSO configuration
* **Authorization isolation:** OpenFGA stores per-organization relationship tuples; cross-organization access is structurally impossible
* **Data isolation:** Each service owns its own database; all queries filter by `org_id` from the JWT token
* **Secrets isolation:** Secret access is scoped per organization (Infisical namespaces or GCP SM IAM bindings)
**Security invariants:**
* The `org_id` always comes from the authenticated JWT, never from request parameters
* List operations always filter by `org_id` AND `project_id` at the database level
* Write operations always stamp the `org_id` from the JWT onto new resources
* No cross-service foreign keys exist between databases
**Related:** [Multi-Tenancy](/platform/multi-tenancy) | [Security](/security/overview)
## Permission Model
The platform uses **Relationship-Based Access Control (ReBAC)** via OpenFGA. Permissions are computed from relationships rather than statically assigned.
### Roles
| Role | Description |
| ----------- | ------------------------------------------------------------------- |
| `owner` | Full control over the organization and all its resources |
| `admin` | Administrative access to manage users, projects, and settings |
| `member` | Standard access to project resources |
| `developer` | Access to create and modify agents, data connections, and workflows |
| `operator` | Access to deploy, schedule, and monitor resources |
| `viewer` | Read-only access to all resources |
### Computed Permissions
Permissions are derived from role relationships at query time:
| Permission | Description |
| -------------------- | ------------------------------------------------------- |
| `can_read` | View a resource and its metadata |
| `can_write` | Create or update a resource |
| `can_delete` | Remove a resource |
| `can_execute` | Run an agent, trigger a schedule, or execute a workflow |
| `can_manage_secrets` | Access and manage secrets for data connections |
### Inheritance
Permissions flow downward through the hierarchy:
```text theme={null}
Organization -> Project -> Resource (Agent, Data Connection, etc.)
```
A user with the `admin` role on an organization automatically receives `can_read`, `can_write`, and `can_delete` computed permissions on all projects and resources within that organization.
## CRAFT Modules
CRAFT is one product, composed of three modules. Module names are stable nomenclature; capitalize as shown.
| Module | Status | Purpose |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CRAFT Assess** | Available | Evaluates data and surfaces what blocks agent-readiness. Implemented today by the Data Insights and Data Governance solutions (data profiling, coverage analysis, policy compliance checks). |
| **CRAFT Enrich** | Available | Automatically enriches metadata, generates data quality rules, and classifies data assets. Implemented today by the Data Governance solution (LLM-powered metadata enrichment, DQ rule generation, classification). |
| **CRAFT Toolkit** | Planned | Verification certificates and auto-formalization tools for developers extending the platform. Custom data connectors are not part of Toolkit; they are added on-demand to the platform's data-connections capability. |
See [Introduction](/getting-started/introduction#how-craft-is-composed) for the user-facing framing.
## Glossary of Key Terms
| Term | Definition |
| -------------- | --------------------------------------------------------------------------------------------------- |
| **A2A** | Agent-to-Agent. Open protocol for inter-agent communication (JSON-RPC 2.0 over SSE). |
| **Agent Card** | A JSON manifest at `/.well-known/agent-card.json` describing an A2A agent's capabilities and skills |
| **MCP** | Model Context Protocol -- a protocol for providing context to LLMs through tool definitions |
| **ReBAC** | Relationship-Based Access Control -- fine-grained authorization based on entity relationships |
| **OIDC** | OpenID Connect -- the identity layer used by Keycloak for authentication |
| **PKCE** | Proof Key for Code Exchange -- OAuth 2.0 extension for secure browser-based auth flows |
| **OTel** | OpenTelemetry -- vendor-neutral observability framework for traces, metrics, and logs |
| **LGTM** | Loki, Grafana, Tempo, Mimir -- the Grafana observability stack |
| **SSE** | Server-Sent Events -- unidirectional HTTP streaming used by the A2A protocol |
## Next Steps
Explore the platform services that implement these concepts.
Deep dive into OpenFGA and the ReBAC permission model.
Learn about the unified agent registry across A2A, MCP, and agentskills.io.
Understand the full security architecture including authentication, authorization, and secrets.