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

# Solution Developer Guide

> Build, package, and deploy a new solution on the CRAFT platform — from first FastAPI service to production deployment.

<Note>
  **For AI agents and LLMs**: this site is Mintlify-hosted, so every page is also available as Markdown by appending `.md` to the URL (or via content negotiation with `Accept: text/markdown`). Prefer those variants — HTML wastes context tokens. The site-wide index lives at `/llms.txt` and the full corpus at `/llms-full.txt`. **Cursor / Claude Code / Windsurf users** — connect your IDE to `https://docs.emergence.ai/mcp` for live doc queries during coding tasks (MCP search tool enabled).
</Note>

# Solution Developer Guide

This guide walks you through building a new **solution** on the CRAFT platform: registering it, wiring it to platform services (auth, secrets, storage, LLMs), running it locally, and deploying it. It is the single starting point for engineers building on top of CRAFT.

## Who this is for

This guide is for **engineers building a new solution on CRAFT** — Emergence platform engineers, embedded teams, and co-design partners. It is *not* for end users of an already-built solution — those have their own docs: [Data Insights](/data-insights/overview), [Data Governance](/data-governance/overview), and [Semiconductor](/semiconductor/overview).

### Reader audiences and where you read

There are two reader sites:

| Site     | URL                                               | You see                                                      |
| -------- | ------------------------------------------------- | ------------------------------------------------------------ |
| Internal | `docs-internal.emergence.ai` (password-protected) | Everything, including internal-only pages and gated sections |
| External | `docs.emergence.ai` (public)                      | Only the partner-safe content                                |

If you are reading on the public site (`docs.emergence.ai`), some implementation-specific sections are hidden by design — the partner-friendly capability descriptions remain.

## Journey map

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart LR
    A["Read overview"] --> B["Quickstart<br/>(30 min)"]
    B --> C["Understand<br/>architecture"]
    C --> D["Local dev"]
    D --> E["Register your<br/>solution"]
    E --> F["Wire integrations"]
    F --> G["Package &<br/>deploy"]
    G --> H["Operate"]

    F -.-> F1["Auth"]
    F -.-> F2["Secrets"]
    F -.-> F3["Storage"]
    F -.-> F4["LLMs"]

    classDef entry fill:#56B4E9,stroke:#555555,color:#000
    classDef step fill:#0072B2,stroke:#555555,color:#fff
    classDef leaf fill:#E69F00,stroke:#555555,color:#000
    class A entry
    class B,C,D,E,F,G,H step
    class F1,F2,F3,F4 leaf
```

## Use this when…

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/guides/solution-dev/quickstart">
    You want a working hello-solution in 30 minutes.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/guides/solution-dev/architecture-for-solution-developers">
    You want to understand what the platform provides and what your solution owns.
  </Card>

  <Card title="Local development" icon="laptop-code" href="/guides/solution-dev/local-development">
    You're iterating on your service locally and want hot reload + mocked platform services.
  </Card>

  <Card title="Register a solution" icon="clipboard-check" href="/guides/solution-dev/register-a-solution">
    You're starting a new solution and need names, namespaces, and registration steps.
  </Card>

  <Card title="Authenticate users" icon="shield-check" href="/guides/solution-dev/authenticate-users">
    You need to validate JWTs and propagate `X-Project-ID` from your service.
  </Card>

  <Card title="Manage secrets" icon="key" href="/guides/solution-dev/manage-secrets">
    You need to inject secrets into pods and rotate them safely.
  </Card>

  <Card title="Use shared storage" icon="database" href="/guides/solution-dev/use-shared-storage">
    You need to read and write objects (artifacts, files) to S3/GCS/Azure/MinIO.
  </Card>

  <Card title="Access LLMs" icon="brain" href="/guides/solution-dev/access-llms">
    Your solution calls LLMs and you need provider-agnostic, observable, cost-attributed access.
  </Card>

  <Card title="Package and deploy" icon="box" href="/guides/solution-dev/package-and-deploy">
    You're ready to build a multi-component Helm chart and ship it to a cluster.
  </Card>

  <Card title="Starter templates" icon="file-code" href="/guides/solution-dev/starter-templates">
    You want copy-pasteable scaffolds for three common solution shapes.
  </Card>

  <Card title="Troubleshooting" icon="circle-exclamation" href="/guides/solution-dev/troubleshooting">
    Something is broken and you want a probable cause + fix in seconds.
  </Card>
</CardGroup>

## Issue-to-page traceability

This guide addresses the [seven onboarding requirements](#issue-to-page-traceability) tracked internally as follows:

| Requirement                            | Primary page(s)                                                                                                                |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Register a new solution                | [Register a solution](/guides/solution-dev/register-a-solution)                                                                |
| Container & namespace conventions      | [Register a solution](/guides/solution-dev/register-a-solution); [Package and deploy](/guides/solution-dev/package-and-deploy) |
| Connect to Keycloak (auth)             | [Authenticate users](/guides/solution-dev/authenticate-users)                                                                  |
| Connect to Infisical (secrets)         | [Manage secrets](/guides/solution-dev/manage-secrets)                                                                          |
| Connect to shared storage              | [Use shared storage](/guides/solution-dev/use-shared-storage)                                                                  |
| LLM integration                        | [Access LLMs](/guides/solution-dev/access-llms)                                                                                |
| Local development setup                | [Local development](/guides/solution-dev/local-development)                                                                    |
| Minimal working example                | [Quickstart](/guides/solution-dev/quickstart); [Starter templates](/guides/solution-dev/starter-templates) Tier 1              |
| Starter templates for common scenarios | [Starter templates](/guides/solution-dev/starter-templates)                                                                    |

## Reference solutions

Three production solutions live on the platform today; treat them as canonical examples when you need a working pattern.

| Solution                                     | Code repo           | Pattern                                                                                |
| -------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------- |
| [Data Insights](/data-insights/overview)     | `em-talk2data`      | Multi-agent A2A protocol — gateway service + insights agent + text2sql agent + LiteLLM |
| [Data Governance](/data-governance/overview) | `em-data-readiness` | API service + Prefect workflows — profiling, enrichment, DQ rules                      |
| [Semiconductor](/semiconductor/overview)     | `em-semi`           | Pydantic AI agents + air-gapped deployment — fab analytics                             |

The starter templates page maps each tier to one of these reference solutions: Tier 1 ≈ minimal API service, Tier 2 ≈ `em-data-readiness` shape, Tier 3 ≈ `em-talk2data` shape.

## Success criteria — your feedback closes the loop

This guide has one explicit performance target:

> **The [Quickstart](/guides/solution-dev/quickstart) must take you 30 minutes or less, end to end.** If it takes longer, that is a guide bug — please report it via the 👎 thumbs at the bottom of the affected page (Mintlify captures the comment and routes it to the docs team).

Use the 👍 / 👎 thumbs at the bottom of every page. Thumbs-down comments roll up into the quarterly docs governance review for this group. The quickstart also runs in CI weekly (see [Local development](/guides/solution-dev/local-development#ci-smoke)) so we know within a week if it stops working.

## Conventions used in this guide

* **Placeholders**: `<service>` is your solution's name (DNS-safe, lowercase, hyphens). `<env>` is one of `dev`, `stg`, `prod`. `<org-id>` and `<project-id>` come from your JWT and `X-Project-ID` header — see [Concepts](/getting-started/concepts).
* **Pinned versions**: Code samples are pinned to **em-service v0.0.15** (the version in [em-service Chart](/deployment/helm/em-service) as of 2026-05-14). Major em-service version bumps refresh the Tier 1 fixtures under `scripts/tests/fixtures/solution-dev/tier1/`; `npm run check-snippets` (CI) fails if inline snippets drift.
* **Service catalog**: There is no Backstage-style service catalog yet; the closest current surface is the em-runtime Assets API where you register agents, data connections, and artifacts — see [Register Your First Agent](/guides/first-agent). A first-class portal is on the platform roadmap.
* **Cross-refs**: Use absolute paths (`/guides/...`, `/platform/...`).
* **Diagrams**: Mermaid only, with the project init block and the Okabe-Ito palette (entry `#56B4E9`, infrastructure `#0072B2`, data store `#009E73`, action `#E69F00`, decision `#F0E442`, external `#CC79A7`).

## What's next

If you are reading this for the first time, go straight to the [Quickstart](/guides/solution-dev/quickstart). If you have a running hello-solution and want to add real integrations, jump to the relevant how-to from the journey map above.