User Service Delivery Policy

This document owns the default delivery path for UniDesk user services registered in config.json.microservices[], together with the paired frontend verification expectations for those services. It does not replace docs/reference/deploy.md, docs/reference/ci.md, docs/reference/dev-environment.md, or docs/reference/microservices.md; it states the default release order that future user-service work should follow unless a service-specific exception is documented.

Scope

User services are non-core business services mounted onto the UniDesk platform. They must remain deliverable without changing the base platform strategy. The default policy here applies to user services that are expected to reach production after validation, including D601-managed services such as Decision Center.

This policy does not apply to:

core platform services;
CI/CD infrastructure itself;
provider-gateway;
k3sctl-adapter;
release/v1 governance;
one-off infrastructure repair actions.

Default Release Flow

The default release flow for a user-service change is:

CI builds the user-service image on D601 from a pushed Git commit.
CI publishes the commit-pinned image to the D601 host-managed registry.
The dev environment runs automated validation against that same commit-pinned artifact.
CD on the production side pulls the registry artifact and deploys it without rebuilding the source.
Manual acceptance is performed after the live deployment has been verified.

Operating Rules

CI may carry heavier dependency resolution, build cache, and test cost than CD.
CD must stay low-dependency and fast.
No user-service artifact may rely on a third-party registry as source of truth.
No production deploy may rebuild the source from a dirty worktree.
Commit-pinned image tags are the deployment truth; mutable latest tags are not.
The standard CI artifact producer is bun scripts/cli.ts ci publish-user-service --service <id> --commit <full-sha>. It accepts only a pushed Git commit and a registered service id, and reports image ref, tag, digest, source commit and service id.
The CI artifact producer is not a deploy executor. It must not mutate the production namespace, restart production services, or update deploy.json.
Every production release must finish with a manual acceptance step after the automated checks pass.

Frontend Pairing

Many user services are surfaced through the UniDesk frontend rather than through their own browser-exposed product. When a user-service backend has a paired UniDesk frontend page, the frontend change must be validated in the same dev/prod release window as the backend artifact, but it does not create a second deployment truth. The backend artifact remains the production deployment unit; the frontend page remains the user-visible acceptance surface.

Decision Center

Decision Center is the canonical example of a user service that doubles as a product workflow for requirements, decisions, and daily work diaries.

The minimal standard artifact command is bun scripts/cli.ts ci publish-user-service --service decision-center --commit <full-sha> --wait-ms 1200000.
The expected artifact is 127.0.0.1:5000/unidesk/decision-center:<commit> plus its registry digest from the CI output.
Requirements and follow-up items should be represented with structured records such as goal, decision, blocker, debt, and experiment, with linked evidence and goal references.
The service should act as a demand-management surface for external goals that need to be decomposed into internal tasks, blockers, and decisions.
The work-diary surface should support creating today's diary entry automatically from the real current date.
Historical diary entries should be editable by date, with PostgreSQL remaining the source of truth.
The resulting product surface should stay structured and reviewable, not collapse into an untracked chat log.
Before any production deploy, the dev gate must pass first with the focused Decision Center E2E set covering microservice:decision-center-record-crud, microservice:decision-center-diary-lifecycle, frontend:decision-center-visible, frontend:decision-center-demand-management-visible, and frontend:decision-center-diary-visible; this is an automated user-service validation gate, not a production deploy.
Production acceptance is manual after the dev gate and must explicitly verify health, records, diary editor, the paired frontend page, no public business ports, and live commit / artifact information.

Detailed service-level API and UI contracts remain in docs/reference/microservices.md.

4.6 KiB Raw Blame History