Skip to content

Journal TradeTally Parity Plan

TM-98 migrates the forked TradeTally journal depth into the TradeMate product surface. The goal is not to expose a detached legacy app. The canonical TradeMate web app and native app should use the same journal data and route contracts, with desktop web treated as the primary layout for dense workflows.

Product Principles

  • The account-level Journal is the source of truth for trades, trade notes, reflections, attachments, imports, and journal analytics.
  • Strategy History, Portfolio recent trades, and agent reflections are filtered views into Journal and audit data, not separate trade stores.
  • MVP subscription gates are disabled for integrated journal features. Routes remain authenticated, tenant-scoped, and API-scope protected where applicable.
  • Advanced journal features remain entitlement-ready so paid tiers can be added later without reshaping IA.
  • TradeMate branding replaces TradeTally naming in visible navigation and copy.

Mounted Route Domain Inventory

Fork route domain Decision Product destination Rationale
/api/trades keep Manage > Journal > Trades and Trade Detail Core parity surface: CRUD, fills, splits, attachments, images, charts, comments, tags, notes, imports, exports, quality, news, and bulk actions.
/api/analytics keep Manage > Journal > Analytics Matches TM-98 analytics requirements: overview, performance, drawdown, calendar, symbols, strategies, tags, hours, sectors, MAE/MFE, recommendations, and export.
/api/diary keep Manage > Journal > Diary Reflection entries, search, tags, linked trades, images, attachments, general notes, stats, and AI analysis hooks.
/api/diary-templates merge Journal settings and Diary compose Templates should be managed in settings and applied inside diary workflows.
/api/accounts keep Manage > Journal > Accounts Journal accounts, transactions, cashflow, unlinked identifiers, and trade-account linking.
/api/csv-mappings keep Imports > CSV mapping templates Required for unknown-header handling and repeatable broker import mappings.
/api/tags merge Journal settings > Tags Shared taxonomy for trades, diary entries, analytics filters, and bulk edit.
/api/settings merge Journal settings Keep journal-specific settings only; global profile, billing, broker, and legal settings remain in TradeMate Settings.
/api/equity merge Analytics and Accounts Equity snapshots and K-ratio belong in journal analytics/account performance, not a standalone primary nav item.
/api/trade-management rename Advanced Trade Review R-multiple, target-hit-first, and manual target levels are advanced trade review tools.
/api/behavioral-analytics rename Behavioral Analytics Advanced behavioral review: revenge trading, overconfidence, loss aversion, personality drift, alerts, and settings. MVP unlocked; entitlement-ready.
/api/ai merge Trade detail and Diary actions AI sessions and analyses should appear as contextual actions where the user is already reviewing a trade or reflection.
/api/playbooks keep Journal > Playbooks Playbooks are process-review checklists and setup rubrics, distinct from portfolio-level Strategies. MVP unlocked; entitlement-ready.
/api/news-correlation keep Analytics > News Correlation Journal analytics that correlates news context with trade outcomes.
/api/news-enrichment defer Admin/background controls Useful for operations and data freshness, but not a primary user workflow for TM-98 MVP.
/api/year-wrapped keep Journal > Reports Annual journal review/report surface.
/api/instrument-templates merge Journal settings > Instrument templates Supports trade form defaults and import repair without becoming a separate product area.
/api/symbols keep Shared journal lookup service Needed by trade forms, imports, repair flows, and analytics filters.
/api/features keep internal Feature checks No direct Journal IA page. Used for feature flags and future entitlement checks.
/api/webhook keep internal Pipeline writes Main API and workers push trade lifecycle updates here. No user-facing route.
/api/v1 keep API Native/sync API Mobile-optimized and API-key aware endpoints remain implementation detail.
/api/v2 defer/merge Compatibility API Prefer canonical TradeMate wrappers; keep compatibility while routes are migrated.
/api/users retire from journal IA TradeMate auth/profile/admin Avoid duplicating Better Auth and TradeMate user administration.
/api/gamification defer Future engagement Not part of TM-98 parity acceptance criteria.
/api/investments defer Portfolio/Research candidate Investment analysis belongs outside the journal IA unless later product work pulls it in.
/api/admin/backup retire/replace TradeMate admin/ops Admin backup operations should not appear in user-facing Journal.
/api/health, /api/ready, inline /api/admin/* keep internal Readiness and ops Service health and recovery endpoints remain operational surfaces.

Proposed IA

Manage > Journal

  • Trades: desktop dense table, filters, saved views, bulk actions, export, and import entrypoint.
  • Trade Detail: edit trade, fills, partial exits/splits, attachments, images, charts, comments, tags, notes, quality grading, health fields, playbook review, and TradeMate signal-chain context.
  • Diary: daily reflections, general notes, search, tags, linked trades, images, attachments, templates, and contextual AI analysis.
  • Analytics: overview, performance, drawdown, calendar, symbols, strategies, tags, hours, sectors, MAE/MFE, recommendations, news correlation, and export.
  • Imports / Exports: CSV validation, broker/account mapping, unknown headers, import status/history/logs, rollback, delete, and fixture-backed supported broker coverage.
  • Accounts: journal accounts, cashflow, transactions, unlinked identifiers, and equity snapshots.
  • Playbooks: process review checklists, setup rubrics, trade review, and playbook analytics.
  • Behavioral Analytics: advanced behavior review and alerts.
  • Journal Settings: tags, diary templates, instrument templates, broker fees, CSV mappings, quality weights, and journal-only preferences.
  • Reports: year-wrapped and exportable journal reviews.

Native And Narrow-Screen Coverage

Native and narrow-screen routes should prioritize core actions:

  • Trades list and trade detail.
  • Add/edit trade and fills.
  • Attach images/files from practical device flows.
  • Diary entry creation and review.
  • Basic analytics summary and calendar.
  • Import status/history review after desktop import.

Dense workflows should be desktop-first:

  • CSV mapping and unknown-header repair.
  • Bulk trade edits and large trade tables.
  • Full analytics matrices and multi-panel comparisons.
  • Account cashflow reconciliation.

Store Boundary

Do not create another journal store for Strategies, Portfolio, or agents.

Instead:

  • Portfolio recent trades query Journal with portfolio_id or account context.
  • Strategy History queries Journal/audit data with strategy or strategy_id.
  • Agent reflection output writes to the same journal/reflection model that users inspect and edit.
  • Trade detail composes journal trade data with linked audit and agent-run context.

This avoids stale copies when a trade is edited, imported, split, tagged, or reconciled.

Implemented Surface

The integrated TradeMate surface mounts these Journal workspaces in the shared web/native route tree:

  • /journal for the account-level trade list, filters, summary metrics, and links to every Journal workspace.
  • /journal/[id] for trade detail, fork trade panels, mutable notes/tags/fills, files, charts, health fields, playbook review, and TradeMate signal-chain context.
  • /journal/diary, /journal/analytics, /journal/imports, /journal/accounts, /journal/playbooks, /journal/behavioral, /journal/settings, and /journal/reports for mounted fork workspaces.

The TradeMate API exposes the canonical user-facing contract:

  • GET /journal/summary
  • GET /journal/trades
  • POST /journal/trades
  • PUT /journal/trades/{trade_id}
  • DELETE /journal/trades/{trade_id}
  • GET /journal/trades/{trade_id}/context
  • GET /journal/trades/{trade_id}/management
  • GET /journal/analytics/dashboard
  • GET /journal/reports/edge/latest
  • POST /journal/diary
  • GET|POST|PUT|PATCH|DELETE /journal/fork/{path:path} for temporary approved fork probes only

The fork proxy allows only the product-approved Journal domains listed in this document. Retired user/admin domains remain outside the TradeMate Journal IA. Frontend route definitions share the same allowed-domain vocabulary so route drift is caught in tests before it reaches production.

TM-109 Consumption Bridge Classification

The integrated app consumes Journal through the FastAPI facade. Web code must not point at the standalone Journal service and must not use fork proxy mutation URLs for core Trade Log actions.

Route or API surface Classification Owner Replacement condition
/trade-log native_facade TradeMate web/API Uses /journal/summary, /journal/trades, and named trade mutation facade endpoints.
/journal/[id] native_facade TradeMate web/API Uses /journal/trades/{id}/context and /journal/trades/{id}/management.
/journal/analytics native_facade TradeMate web/API Uses /journal/analytics/dashboard; endpoint-level fork probes may remain hidden as partial data fallbacks.
/journal/reports native_facade TradeMate web/API Uses /journal/reports/edge/latest; report export remains future facade work.
/journal/diary native_facade TradeMate web/API Diary save uses POST /journal/diary; read probes remain temporary until diary list/detail facade endpoints exist.
/journal/playbooks, /journal/behavioral, /journal/settings temporary_fork_proxy TradeMate API Temporary read probes through /journal/fork/{path} are allowed only for approved domains and should be replaced by named facade endpoints before the Journal service becomes fully private.
/journal/accounts, /journal/imports archived_redirect TradeMate web Redirect to /accounts and /trade-log; do not recreate as standalone MVP routes.
/journal/fork/users/*, /journal/fork/admin/* delete_candidate TradeMate API Blocked by allowed_fork_path; user/admin identity belongs to Better Auth and TradeMate Admin.

Verification evidence is covered by focused API tests for journal summaries, trade lists, signal-chain context, proxy forwarding, mutation auditing, and blocked retired domains; mobile tests cover IA coverage, route-domain guards, canonical journal API calls, and panel-level failure isolation.