Replenishment pod: architecture and releases

Where the client-specific code lives, which shared headless services do the heavy lifting, and how a new agent version reaches the planner's queue. Agents read, calculate and draft. The client's team decides. No purchase order is placed by an agent.

Where the code goes

Planners and buyersportal, Teams or Slack, emailClient managersbrowserSchedules and data feedsnightly ERP, hourly WMS, EDI, on demandPod Hubbranded client portalruns, questionssign inCUSTOM CODE · one repo and container per clientReplenishment runtimefrom pod-sdkschedule, read data,run agent steps,queue proposalspod.yamlmodels, tools, hostsagents/*.jsondemand, stock watch,drafter, exceptionsprompts/reasoning format,weekly brieftools.yamlERP, WMS, EDI reads;approval-gated POevals/120 golden reorderdecisions, 6 hard rulesmetrics.yamlstockout rate, lostsales, hours returnedread-only snapshotsHEADLESS SERVICES · shared by every pod, no UI of their ownpod-gatewaymodels, budgets,card and ID blockRagOSterms, policies,promo calendartoolOStools, secrets,PO approval gateEvalOSgolden calls,release gateLangfuseone traceper runKeycloaksign-in,roles, tenantspod-controlversions, livepointer, usageShared by default, each client isolated. Single-tenant or client-hosted on request.pod-egress sits in front: a pod can only reach the hosts named in pod.yaml.MCP and API calls, trace id on every hopreads records, editscontent, versionsClientplanning teampeople on the loopproposal withits reasoningflaggedruns toreviewClient systems: ERP, WMS, EDI and POS feeds, supplier terms, promo calendar, Teams or Slacksigned calls
Orange is custom code: one repo and one container per client. Blue is headless services that every pod reuses. The blue arrow from the runtime is the human on the loop: every purchase order is proposed to the client's planners with its reasoning attached; they approve, edit or reject it, and only an approved PO reaches the ERP. Exceptions land in their queue with the rule that fired. The pod never holds a model key or a client system password; it calls the services, and toolOS is the only path to client systems.
Custom, per clientHeadless, sharedOutside the platform

Why this is easier to build, more custom and more responsive

AreaHow it works for a client pod
Faster buildsThe next pod reuses all seven services. Only the orange box is new work, built from a tested template.
Custom per clientEach client gets its own flows, prompts, tools, metrics and portal screens, in its own repo. Nothing is forced into a generic builder.
Agent logicJSON in git: reviewed, compared step by step, rebuilt from the last shipped version
Responsive changesReorder rules, supplier terms, the promo calendar, run schedules and brief recipients change from the portal and apply on the next run
KnowledgeRagOS: a supplier terms record that always wins over an old price list, reorder policies, a promo and seasonality calendar with dates
Approval gatetoolOS: the only write to the ERP is create_po, and it runs only with a planner's approval id attached. An agent cannot call it
ReversibleEvery agent action is logged with its reasoning and can be undone from the audit timeline; a rejected proposal leaves nothing behind in the ERP
Client portalPod Hub screens built for this pod: proposal queue, exceptions, the number by site, weekly brief
Safe releasesEvalOS gate on the client's golden cases; a worse version cannot ship
Tools and secretstoolOS: timeouts, failure results, approvals; keys never enter the pod or its exports
Modelspod-gateway: per-pod budget, card and ID numbers blocked before any model call, models swapped without code changes
TracingLangfuse: one trace per run across model, knowledge and tools

Where it runs, where data lives, how long it is kept

OptionWhat runs whereBest for
Shared (default)The client's pod runs in its own container; the seven services are shared, with every record scoped to that clientMost clients: fastest to start, lowest cost
Single-tenantThe pod and a dedicated copy of every service, used by this client only, run and patched by SectorFlowClients who need no shared infrastructure
Client-hostedThe same containers deployed in the client's own cloud account; SectorFlow ships releases through the same gateRegulated clients, or data that cannot leave their account
DataResidencyDefault retentionClient control
Proposals, decisions and reasoningRegion chosen per client: Canada, US or EU24 months12 months to 7 years; exported in full on exit
Audit timelineSame region24 monthsUp to 7 years; exportable at any time
Demand and stock snapshotsSame region90 days30 days to 24 months
TracesSame region30 daysShorter or longer per client
Supplier terms, policies and calendarSame regionUntil removed; every version keptDelete any record or version
BackupsSame region14 daysFixed
On exit––Demand rules, documentation and a full export; 30 days of transition help

How an agent version is updated

1 Changeagent JSON, prompt,tool or model, in a branch2 Build checksstructure, references,variables, diff by step3 Quality gate120 golden cases,18 months of runs replayed4 Client reviewrelease notes and gateevidence in Releases5 Make livemove the live pointer,schedules unchangedEvery release is a new immutable version. PO drafter v12 is never edited; PO drafter v13 is built from it.fails: blocked, cannot be overridden, back to step 1Morning PO rundaily 6:00 am, per supplierPO drafter v12PO drafter v13Stock watch v9Stock watch v10beforeafter step 5PO drafter and Stock watch move together as a pair. Rollback is one move of the pointer back to v12 and v9.No release needed: reorder rules, supplier terms, promo calendar, run schedules, brief recipientssaved in the portal, live on the next run; every change is versioned and in the activity log
A flow, prompt, tool or model change goes through all five steps. SectorFlow moves the pointer in pod-control after the client has seen the gate result. Content changes at the bottom skip the release path because they do not change how the agent behaves step by step.

Release steps in detail

StepWhoWhat happens
1 ChangeSectorFlow engineerBranch from the live version. Edit agents/po-drafter.json and its Stock watch pair, prompts or tools.yaml. Write release notes.
2 Build checksCIEvery tool and edge exists, every step is reachable, every variable is set, no write tool on any agent step, a failure edge on every data read. Diff by step, tool and rule for the reviewer.
3 Quality gateCI calls EvalOSThe candidate replays 120 golden reorder decisions from the client's own history; 18 months of logged production runs must still produce a proposal. All 6 hard rules pass on every case (never place a PO, MOQ and pack rounding, lead time respected, promo uplift applied, freeze windows honoured, reasoning on every line), at least 90% overall, no regressions against live.
4 Client reviewClient in Pod HubThe candidate appears under Releases with notes, scores and failed cases. Make live is disabled for client users.
5 Make liveSectorFlow in pod-controlThe image and flow hash are registered as an immutable version. The live pointer moves to the new version. Traces and alerts are watched on the first runs.
RollbackSectorFlowMove the pointer back. The previous version is still deployed, so it takes effect on the next run.