Register a New Solution

End-to-end checklist for registering a new solution on the platform — name, namespace, image registry, Helm wiring, database, and platform integration.

Register a New Solution

This is the canonical checklist for starting a new solution on CRAFT. Follow these steps when you’re past the Quickstart prototype and ready to make the solution real.

Most decisions here are conventions — the platform doesn’t force you, but solutions that follow the conventions get free deployment, observability, and CI integration.

Registration sequence

The dashed sequence is the order, not the schedule — most solutions land steps 1–4 in one PR, 5 in the next, and 6/7/8 incrementally. Steps 6 and 7 are conditional; only Tier 3 agentic solutions need them up front.

Pre-flight checklist

Solution name picked (DNS-safe)

Lowercase, alphanumeric + hyphens only, ≤ 30 chars. Used as the Helm release name, the namespace suffix (em-<name>), and the package prefix in your monorepo.

Repository created

One repo per solution. Monorepo layout from day one — even with a single component — so adding a worker later is a 3-step diff. See Architecture for Solution Developers.

Image registry chosen

Any OCI registry your target cluster can pull from. Internal solutions use ghcr.io/emergenceai/. Partners typically use their own registry.

Database design sketched

Your own Postgres database. No cross-service foreign keys. Migrations versioned with Alembic from day one.

Decided what gets registered with Assets

Agents, data connections, files, and models registered through the platform’s Assets API are discoverable to other solutions and the UI. Decide upfront what your solution exposes.

Steps

1. Pick a name

   Match the solution name across:

   • Repo name (e.g. em-talk2data)
   • Helm release name (e.g. talk2data)
   • Namespace (e.g. em-talk2data)
   • Database (e.g. talk2data)

   Existing examples: em-talk2data (Data Insights), em-data-readiness (Data Governance), em-semi (Semiconductor). Stick to this rhythm — it makes ops searches and grep-based audits trivial.

2. Apply the namespace convention

   Namespace	Used by
   em-runtime	Platform services (Governance, Assets, Utils, Keycloak, OpenFGA)
   em-<solution>	Your solution’s pods, services, and config
   em-<solution>-system	Cluster-scoped sidecars or operators owned by your solution (rare)

   Create the namespace explicitly with a label so the platform’s NetworkPolicy / Reloader / cost-attribution pick it up:

   kubectl create namespace em-<solution>
   kubectl label namespace em-<solution> emergence.ai/solution=<solution>
   
3. Choose your container image registry

   Configure image.repository in your chart’s values.yaml. For private registries, also configure imagePullSecrets:

   api:
     image:
       repository: <your-registry>/<solution>-api
       tag: 0.1.0
     imagePullSecrets:
       - name: <your-pull-secret>
   
4. Wire the Helm chart

   Single component? See Quickstart Step 4. Multi-component (api + worker + scheduler + agent…)? See Package and Deploy for the alias pattern.

   The minimum is one em-service subchart per component, with each component aliased so its values live under that key:

   charts/<solution>/Chart.yaml

   dependencies:
     - { name: em-service, alias: api,    version: 0.0.16, repository: oci://ghcr.io/emergenceai/em-charts }
     - { name: em-service, alias: worker, version: 0.0.16, repository: oci://ghcr.io/emergenceai/em-charts }
   
5. Register your database (your own, not platform's)

   Your solution owns its database. Two non-negotiable rules:

   1. No cross-service foreign keys. Each service must be backup-restorable independently. Cross-service consistency is by API contract, not joins.
   2. Migrations from day one — Alembic is the platform standard. Migrations are immutable once committed; never edit a published migration, write a new one.

   Provision via your chart (the Postgres subchart pattern) or via Crossplane claims for managed databases. Connection string injected as a secret-backed env var (see Manage Secrets).

6. Register agents (optional)

   If your solution exposes A2A agents (the Data Insights pattern), register each with the Assets API so other services and the UI can discover them. Follow Register Your First Agent — that walkthrough covers Agent Card authoring (/.well-known/agent-card.json), validation, registration, listing, and update with optimistic concurrency.

7. Register data connections (optional)

   If your solution reads customer data (databases, object stores, file shares), the customer registers a Data Connection and grants your solution permission. Your code fetches the connection at runtime — credentials never live in your config.

8. Wire integrations

   Step through these in order:

   Authenticate

   Validate JWTs and propagate X-Project-ID.

   Secrets

   Inject runtime secrets via the chart.

   Storage

   Use obstore for cross-cloud blob access.

   LLMs

   Call the LiteLLM gateway (never providers directly).

What you get when you follow the conventions

If you…	You get…
Follow em-<solution> namespace	Auto-applied NetworkPolicy, Reloader watching your Secrets, cost attribution by solution
Wrap em-service with one alias per component	Standard probes, env var deduplication, Gateway API ingress, HPA — all configurable but with sane defaults
Register agents in Assets	Discoverability from the UI shell + other solutions; permission integration with OpenFGA
Use Connections for data sources	Credential rotation handled by the platform; never in your code
Call LLMs via LiteLLM gateway	Per-project cost attribution, rate limits enforced centrally, traces in Langfuse

Verification

# Namespace label set
kubectl get namespace em-<solution> -o jsonpath='{.metadata.labels}'

# Helm release lives in the right place
helm list -n em-<solution>

# Image pulls succeed (no ImagePullBackOff)
kubectl -n em-<solution> get pods

# DB migration ran (if applicable)
kubectl -n em-<solution> logs job/<solution>-migrate

If anything is unhealthy, see Troubleshooting.

Next steps

Package and deploy

Multi-component charts, env overlays, image publish.

Local development

Test changes locally before pushing.

Authenticate users

The first integration most solutions need.

Troubleshooting

Common errors at registration time.