Skip to content

TM-110 Journal Fork Decommission Runbook

Use this runbook after the native Journal branch is merged to main and deployed. It removes the legacy apps/journal runtime from production without losing the ability to roll back during the validation window.

Scope

This runbook covers production decommissioning of the forked Journal service:

  • verify that the deployed API no longer needs JOURNAL_URL;
  • remove JOURNAL_URL from production service env vars;
  • delete the legacy trademate-journal service in Coolify after final native validation;
  • prove the web/mobile Journal paths work through native FastAPI routes;
  • define rollback if native validation fails.

It does not delete historical Journal source code or data archives. Source archival and old database disposal require a separate retention decision.

Preconditions

  • PR #176, or its successor TM-110 PR, is merged into main.
  • Coolify has deployed the same commit SHA for trademate-api, trademate-web, trademate-celery, and any service that calls Journal APIs.
  • The deployed API reports native Journal mode:
  • JOURNAL_NATIVE_READS_ENABLED=true
  • JOURNAL_NATIVE_WRITES_ENABLED=true
  • JOURNAL_FORK_PROXY_ENABLED=false
  • The PR-local validation evidence includes:
  • active app-code search with no runtime JOURNAL_URL dependency;
  • Journal and architecture tests passing;
  • mobile Journal helper tests passing;
  • pnpm journal:decommission-readiness artifact generated for the target production API;
  • SDD readiness passing.

Do not remove the old production service before these preconditions are true.

Production Verification Before Removal

  1. Confirm the deployed commit.

Check Coolify deployment metadata or each service /version endpoint. The deployed SHA must match the merged TM-110 commit or a later commit that contains the same Journal runtime cutover.

  1. Run the repo-side readiness harness.

powershell $env:TRADEMATE_API_URL = "https://api.yourtrademate.io" $env:TRADEMATE_EXPECTED_GIT_SHA = "<merged-main-sha>" $env:TRADEMATE_JOURNAL_DECOMMISSION_TOKEN = "<short-lived-admin-or-test-jwt>" pnpm journal:decommission-readiness

The script writes timestamped JSON and Markdown artifacts under output/tm110-journal-decommission-*. It checks /health, /version, /ready, the authenticated /journal/fork/health tombstone, and active web/mobile/API/agent/deploy code boundaries. If no token is provided, the fork tombstone check is marked skipped rather than passed.

  1. Confirm API readiness.

Call production /ready and verify journal_runtime is healthy/native. The old journal_ready dependency should not be required.

  1. Confirm fork proxy retirement.

Call an authenticated or admin-safe request to:

text /journal/fork/health

Expected result: HTTP 410 with detail Legacy Journal fork proxy is retired. Any proxy attempt to the old service is a stop condition.

  1. Confirm named Journal routes.

Smoke at least these authenticated routes with a test user:

  • /trade-log
  • /journal
  • /journal/analytics
  • /journal/diary
  • /journal/playbooks
  • /journal/settings
  • a trade detail route with Journal notes/tags/actions

The page can show empty or not-materialized states, but it must not fail because the old Journal service is unreachable.

  1. Confirm internal agent webhook path.

Run or simulate a paper-safe flow that writes a Journal trade event through JOURNAL_API_URL and verify the native trades, journal_trade_details, and audit rows are written.

Removal Steps

  1. Remove legacy env references.

In Coolify, remove JOURNAL_URL from:

  • trademate-api;
  • trademate-celery;
  • any agent or worker service that still exposes it.

Keep JOURNAL_API_URL where agents need to call the native TradeMate API.

  1. Redeploy or restart affected services.

Restart in this order:

  1. trademate-api
  2. trademate-celery
  3. trademate-web

Use redeploy when env vars changed; use restart only when confirming runtime behavior after a successful deploy.

  1. Stop or delete the old Journal service.

In Coolify, stop trademate-journal during rollback validation. Once native validation is accepted, delete the application and confirm it disappears from the production resource inventory.

  1. Re-run production verification.

Repeat all checks from "Production Verification Before Removal". In addition, confirm API logs do not contain outbound requests to the old Journal service.

Rollback

Rollback is allowed during the validation window if a user-blocking Journal path fails and native repair is not faster than restore.

  1. Re-add JOURNAL_URL only if the deployed code still supports it. The final TM-110 cutover code removes that runtime setting, so this usually requires rolling back the code release too.
  2. Restart trademate-journal.
  3. Roll back trademate-api and clients to the last known release that still used the fork bridge.
  4. Record the failed native route, production evidence, and rollback SHA in the TM-110 phase notes before trying again.

Do not keep a hybrid state where final TM-110 code is deployed but the old Journal service is silently running as if it were active. That hides regressions and makes readiness misleading.

Completion Evidence

TM-110 production decommission is complete only when all of these are true:

  • production trademate-api and callers run the TM-110 native-only code;
  • production env vars no longer include JOURNAL_URL;
  • trademate-journal is removed from active Coolify deployment;
  • /journal/fork/{path} returns 410;
  • named Journal web/mobile routes work without the old service;
  • internal Journal webhook writes land in native TradeMate tables;
  • the runbook results are posted to the PR, deployment issue, or GSD phase notes.

Final production evidence recorded on 2026-07-14:

  • Deployed API SHA: 755d73e3bf27f8ceb74aca4a1cfdbaae37eae7f2.
  • TM-110 decommission harness: output/tm110-journal-decommission-2026-07-14T07-37-43-868Z/.
  • Harness result: 11 passed, 0 failed, 0 skipped.
  • Authenticated /journal/fork/health tombstone returned HTTP 410.
  • /ready reported native Journal reads and writes enabled, fork proxy disabled, and no critical readiness failures.
  • Coolify storage check for legacy application s4yj4xtez7xg5qqda0j9rd3s returned no persistent or file storages.
  • The legacy trademate-journal application was deleted from Coolify with volume deletion enabled and no longer appears in the production resource inventory.
  • API, Celery, and Web container log scans found no trademate-journal or sslip.io references.