> ## 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 Architecture

> The 3-layer architecture of CRAFT: Solutions, Platform, and Infrastructure layers with repo mapping and dependency model.

# Architecture

CRAFT uses a **3-layer architecture**. Your domain-specific **Solutions** build on a shared **Platform**, which runs on managed **Infrastructure**.

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TD
    subgraph Solutions["Solutions Layer"]
        T2D["Data Insights"]
        DR["Data Governance"]
        SEMI["Semiconductor"]
    end
    subgraph Platform["Platform Layer (em-runtime)"]
        GOV["Governance<br/>/api/governance<br/>Auth, Orgs, Permissions"]
        ASS["Assets<br/>/api/assets<br/> Data Connections, Models"]
        UTL["Utils<br/>/api/utils<br/>Catalog, Scheduling, Memories"]
    end
    subgraph Infra["Infrastructure Layer"]
        K8S["Kubernetes"]
        PG["PostgreSQL"]
        RED["Redis"]
        KC["Keycloak"]
        FGA["OpenFGA"]
    end
    T2D --> GOV
    T2D --> ASS
    DR --> GOV
    DR --> ASS
    SEMI --> GOV
    GOV --> PG
    GOV --> KC
    GOV --> FGA
    ASS --> PG
    ASS --> RED
    UTL --> PG
    UTL --> RED
    style Solutions fill:#E69F00,stroke:#555555,color:#000
    style Platform fill:#56B4E9,stroke:#555555,color:#000
    style Infra fill:#0072B2,stroke:#555555,color:#fff
```

## The Three Layers

<Tabs>
  <Tab title="Solutions Layer">
    Domain-specific applications that solve customer problems. Each solution is a standalone product with its own data model, agents, and UI, but shares platform services for identity, authorization, secrets, and resource management.

    | Solution            | Description                                                                                                                                                                                |
    | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | **Data Insights**   | Multi-agent conversational data analytics using the A2A protocol. Users ask natural-language questions; agents generate SQL, execute queries, analyze results, and produce visualizations. |
    | **Data Governance** | Metadata enrichment, data profiling, DQ rule generation, and scorecard reporting. Orchestrated by Prefect workflows with LLM-powered enrichment.                                           |
    | **Semiconductor**   | Semiconductor fab analytics with AI-powered analysis agents and context graph.                                                                                                             |
  </Tab>

  <Tab title="Platform Layer">
    Shared services consumed by all solutions. Provides identity, authorization, resource management, and a unified UI shell.

    | Service        | Port | Responsibility                                                                              |
    | -------------- | ---- | ------------------------------------------------------------------------------------------- |
    | **Governance** | 8000 | Organizations, projects, users, Keycloak multi-realm auth, OpenFGA ReBAC, Secrets API       |
    | **Assets**     | 8000 | Artifacts, data connections, files, models                                                  |
    | **Utils**      | 8000 | Data catalog, search, scheduling, context packs, memories, operational utilities            |
    | **Runtime UI** | --   | React microfrontend shell using Module Federation 2.0; hosts solution UIs as remote modules |

    All platform services share a common auth flow: solutions forward user JWT tokens to Governance for permission validation via auto-generated SDKs.
  </Tab>

  <Tab title="Infrastructure Layer">
    Cloud deployment, networking, and GitOps automation.

    | Component                       | Tool      | Responsibility                                                        |
    | ------------------------------- | --------- | --------------------------------------------------------------------- |
    | **Infrastructure Provisioning** | Terraform | Kubernetes clusters, networking, IAM, secrets backend                 |
    | **GitOps Delivery**             | ArgoCD    | Continuous deployment from Helm charts to 4 environments              |
    | **Helm Charts**                 | Helm      | Application chart templates with environment-specific values overlays |
  </Tab>
</Tabs>

## How Solutions Depend on the Platform

Solutions consume platform services through two integration mechanisms:

### 1. Helm Subchart Dependency

Each solution's Helm chart declares `em-runtime` as a subchart dependency. At deploy time, the platform services (Keycloak, OpenFGA, PostgreSQL, Redis) are co-deployed or connected via shared infrastructure values. This ensures every solution gets consistent identity, authorization, and secrets management without duplicating infrastructure.

### 2. SDK-Based Runtime Integration

em-runtime auto-generates Python and TypeScript SDKs from its OpenAPI specs. Solutions import these SDKs to:

* **Authenticate users** -- forward JWT tokens to Governance for permission validation
* **Manage resources** -- CRUD operations on agents, artifacts, data connections via the Assets SDK
* **Check permissions** -- OpenFGA relationship-based access control via the Governance SDK

<Note>
  Solutions never implement their own permission checks. They delegate to the platform via SDK calls. If Governance is down, downstream services return 403.
</Note>

## Open Standards and Portable Components

CRAFT is built on open standards and portable, open-source components at every layer:

### Standards and Protocols

| Layer                   | Standard                 | Purpose                                                                |
| ----------------------- | ------------------------ | ---------------------------------------------------------------------- |
| **Agent Communication** | A2A (JSON-RPC 2.0 / SSE) | Open protocol for inter-agent messaging                                |
| **Tool Integration**    | MCP                      | Open protocol for connecting agents to external tools and data sources |
| **Identity**            | OIDC / PKCE              | Standards-based authentication                                         |
| **Observability**       | OTLP                     | Vendor-neutral telemetry export to any compatible backend              |

### Open-Source Components

| Layer              | Component | Purpose                                                                              |
| ------------------ | --------- | ------------------------------------------------------------------------------------ |
| **Authorization**  | OpenFGA   | Relationship-based access control (open-source engine)                               |
| **Object Storage** | obstore   | Portable storage across GCS, Azure Blob, S3-compatible stores, and local filesystems |
| **LLM Access**     | LiteLLM   | Provider-agnostic gateway -- use Gemini, GPT, Claude, or any supported model         |

<Info>
  Every protocol and component listed above is an open standard or open-source project. The platform does not require any proprietary service -- you can deploy on any infrastructure that supports these standards.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Key Concepts" icon="lightbulb" href="/getting-started/concepts">
    Learn about the core entities: organizations, projects, agents, and data connections.
  </Card>

  <Card title="Platform Overview" icon="cube" href="/platform/overview">
    Deep dive into the em-runtime services that power the platform layer.
  </Card>

  <Card title="Data Insights" icon="chart-bar" href="/data-insights/overview">
    Explore the multi-agent data analytics solution.
  </Card>

  <Card title="Deployment" icon="cloud" href="/deployment/overview">
    Learn how to deploy the platform on Kubernetes.
  </Card>
</CardGroup>