Solution Developer Guide

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

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

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 Governance, and Semiconductor.

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

Use this when…

Quickstart

You want a working hello-solution in 30 minutes.

Architecture

You want to understand what the platform provides and what your solution owns.

Local development

You’re iterating on your service locally and want hot reload + mocked platform services.

Register a solution

You’re starting a new solution and need names, namespaces, and registration steps.

Authenticate users

You need to validate JWTs and propagate X-Project-ID from your service.

Manage secrets

You need to inject secrets into pods and rotate them safely.

Use shared storage

You need to read and write objects (artifacts, files) to S3/GCS/Azure/MinIO.

Access LLMs

Your solution calls LLMs and you need provider-agnostic, observable, cost-attributed access.

Package and deploy

You’re ready to build a multi-component Helm chart and ship it to a cluster.

Starter templates

You want copy-pasteable scaffolds for three common solution shapes.

Troubleshooting

Something is broken and you want a probable cause + fix in seconds.

Issue-to-page traceability

This guide addresses the seven onboarding requirements tracked internally as follows:

Requirement	Primary page(s)
Register a new solution	Register a solution
Container & namespace conventions	Register a solution; Package and deploy
Connect to Keycloak (auth)	Authenticate users
Connect to Infisical (secrets)	Manage secrets
Connect to shared storage	Use shared storage
LLM integration	Access LLMs
Local development setup	Local development
Minimal working example	Quickstart; Starter templates Tier 1
Starter templates for common scenarios	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	em-talk2data	Multi-agent A2A protocol — gateway service + insights agent + text2sql agent + LiteLLM
Data Governance	em-data-readiness	API service + Prefect workflows — profiling, enrichment, DQ rules
Semiconductor	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 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) 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.
• Pinned versions: Code samples are pinned to em-service v0.0.16 (the version in em-service Chart 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. 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. If you have a running hello-solution and want to add real integrations, jump to the relevant how-to from the journey map above.