# Corporate Environments Guide

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

This guide defines how enterprises can extend TraderX privately without pushing corporate-specific changes upstream.

Status:

*   This page is the high-level strategy overview.
*   Use [Customizing TraderX](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/spec-kit/customizing-traderx.md) as the primary entrypoint.
*   Use the two `custom-*` guides for implementation contracts and environment details.

Detailed implementation contracts:

*   [Custom Overlay Architecture](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/spec-kit/custom-overlay-architecture.md)
*   [Custom Environments Guide](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/spec-kit/custom-environments-guide.md)

## Current Repository Baseline

Current TraderX baseline is already set up with:

*   canonical authoring in `specs/**` and `.specify/**`
*   generated code publish model in `code/generated-state-*` branches
*   catalog-driven publish metadata in `catalog/state-catalog.json`
*   generation/publish automation in `pipeline/generate-state.sh` and `pipeline/publish-generated-state-branch.sh`

Important current constraints:

*   a state must be present in `catalog/state-catalog.json`
*   `generation.mode` must be `implemented`
*   publish branch must match `code/generated-state-*`
*   working tree must be clean before publish

## Decision

Use a separate corporate overlay repository as the runtime implementation model, and keep this TraderX repository upstream-canonical.

Do not place corporate-only state definitions, transforms, secrets, proxy config, or private runtime assumptions into upstream TraderX.

## Recommended Corporate Repository Shape

```text
traderx-corporate-overlay/  upstream/traderX/                  # git submodule pinned to upstream commit  corporate/catalog/state-catalog.json  corporate/profiles/    corporate-internal.yaml    public-dev.yaml  corporate/states/    corp-001-internal-build/    corp-002-podman-runtime/  corporate/transforms/  corporate/runtime/  scripts/  docs/
```

Bootstrap starter included in this repository:

*   canonical starter: `examples/custom-overlay-template/`

## State and Branch Policy

Define three classes:

1.  `mirrored-upstream`: generate and publish selected upstream states in your private remote.
2.  `suppressed-upstream`: skip states that are not runnable or not approved for corporate runtime.
3.  `internal-only`: generate additional corporate states (`corp-*`) only in the corporate repository.

Example policy file in corporate overlay repo (`corporate/profiles/corporate-internal.yaml`):

```yaml
profile: corporate-internalupstreamPin: mainmirroredUpstreamStates:  - 004-containerized-compose-runtime  - 007-observability-lgtm-compose  - 009-order-management-matchersuppressedUpstreamStates:  - id: 010-kubernetes-runtime    reason: "Cluster runtime not approved in this environment"internalStates:  - id: corp-001-managed-postgres-runtime    basedOn: 004-containerized-compose-runtime    publishBranch: code/generated-state-corp-001-managed-postgres-runtime  - id: corp-002-internal-docs-branding    basedOn: corp-001-managed-postgres-runtime    publishBranch: code/generated-state-corp-002-internal-docs-branding
```

## Internal Docs Portal Strategy

Corporate overlays should run an internal docs portal that:

*   clearly marks internal distribution with a persistent warning banner
*   shows only sanctioned internal learning-path branches
*   distinguishes mirrored upstream states from internal-only `corp-*` states
*   publishes a corporate learning graph derived from internal policy, not all public branches

The bootstrap template includes:

*   `examples/custom-overlay-template/overlay/catalog/sanctioned-learning-graph.example.yaml`
*   `examples/custom-overlay-template/overlay/docs/internal-learning-graph.example.md`
*   `examples/custom-overlay-template/overlay/docs/internal-docs-portal.example.md`

For docs-platform upgrade safety (Docusaurus/plugins/Webpack), follow:

*   `/docs/spec-kit/spec-kit-workflow#docusaurus-ci-compatibility`

## Overlay Learning Graph (required)

Every corporate overlay implementation must maintain a learning-path index page at `docs/learning/index.md` (or an equivalent path documented in the overlay repository) that includes:

*   a Mermaid `flowchart TB` showing both upstream FINOS states used by the overlay and the overlay's own state chain
*   a state-to-artifact table directly beneath the diagram with these required columns: `State | Learning Guide | Spec Pack | Generated Branch | Diff vs Previous | Runnable`

Required node classes and semantics:

*   `upstream`: FINOS canonical state shown for context; not owned by the overlay
*   `anchor`: overlay baseline that mirrors an upstream state but adds no runnable changes
*   `runnable`: first overlay state that is fully runnable as a standalone stack
*   `feature`: subsequent overlay states that add a capability on top of the prior state

Required upstream styling and link behavior:

*   upstream FINOS nodes must use class `upstream`
*   class `upstream` must be defined as: `fill:#fff8e1,stroke:#f57f17,stroke-width:1px,stroke-dasharray:5 5`
*   every upstream node must include a Mermaid `click` target to the public FINOS learning guide for that state

Convergence rule:

*   when an overlay state intentionally converges with (matches functional surface of) an upstream FINOS state, the diagram must include a dotted convergence edge with this syntax: `UpstreamNode -.->|converges| OverlayNode`

The overlay template includes a starter example:

*   `examples/custom-overlay-template/overlay/catalog/learning-graph-diagram.example.md`

## Upstream Sync Workflow

1.  Update submodule pin to a tested upstream commit.
2.  Regenerate only profile-approved states.
3.  Publish private generated-state branches to the corporate remote.
4.  Run corporate validation gates.
5.  Promote the new pin only after generation + runtime validation succeeds.

Bootstrap commands:

```bash
mkdir traderx-corporate-overlaycd traderx-corporate-overlaygit initgit submodule add -b main https://github.com/finos/traderX.git upstream/traderXgit submodule update --init --recursive
```

Refresh upstream pin:

```bash
git -C upstream/traderX fetch origingit -C upstream/traderX checkout maingit -C upstream/traderX pull --ff-onlygit add upstream/traderXgit commit -m "chore: bump TraderX upstream pin"
```

Generate from upstream submodule directly into corporate overlay output root:

```bash
TRADERX_GENERATED_ROOT=/path/to/traderx-corporate-overlay/generated \  bash upstream/traderX/pipeline/generate-state.sh 004-containerized-compose-runtime
```

Generated state output includes a local runtime harness at:

*   `/path/to/traderx-corporate-overlay/generated/code/target-generated/scripts`
*   `/path/to/traderx-corporate-overlay/generated/code/target-generated/RUN_FROM_GENERATED.md`

This lets corporate overlays run start/stop/status from generated artifacts directly, while upstream root scripts can forward to those local harness scripts.

## Generation Rules For Agents and Humans

*   Never modify `upstream/traderX` for corporate-only requirements.
*   Never hand-edit generated runtime outputs.
*   Encode persistent corporate deltas as profile/state/transform artifacts in the corporate repo.
*   Preserve explicit lineage (`previous`) for every corporate state.
*   Keep generation reproducible from pinned upstream commit + corporate artifacts.

## Why This Fits TraderX Today

*   Upstream already cleanly separates canonical specs from published generated branches.
*   Current publish tooling already enforces branch naming and implemented-state controls.
*   Corporate suppression/addition is better represented as a profile-level policy in a separate repo, not as upstream catalog edits.

## Transitional Guidance Inside Upstream TraderX

This document is the upstream reference contract. Actual corporate runtime implementation should live outside this repository.