# A1 Prospect Platform Integration Plan — 2026

**Status:** Draft for execution  
**Created:** 2026-05-16  
**Owner:** James  
**Related audit:** Same folder (`audit_consistency_check.md`, `systems.md`, `dependencies.md`, `data-path-trace.md`)

This document captures feasibility assessment, architecture, phased work, dependencies, critical path, tables, and **Mermaid** diagrams (render in GitHub, VS Code preview, or [mermaid.live](https://mermaid.live)).

---

## 1. Executive summary — feasibility

**Yes — feasible with discipline, not a big-bang rewrite.**

The platform already matches a coherent mental model documented in the architecture hub (see **§2.5**) and in-repo references such as `UNIFIED-FRAMEWORK-v1.md` (spine / cockpit / lenses, 13 properties). MGP, Accountability v2, Scorecards, Playbooks, and System hub work today. The May 16 audit shows **execution drift** (mixed schemas, stale `main.*` assumptions, split hosts), not a broken vision.

Integration means **aligning boundaries and auth**, not replacing working UIs — consistent with reusing code and preserving look-and-feel.

---

## 2. Current architecture (as-built)

### 2.1 Multi-host + spine diagram

```mermaid
flowchart TB
  subgraph hosts["Web hosts"]
    TSA["trsportsacademy.com\nZ:/trsports_gd/html"]
    SMB["smb.a1prospect.com\n/ams/ lenses + system hub"]
    WP["A1 Prospect journal\nWordPress / PHP session"]
  end

  subgraph spine["Postgres spine"]
    DB1[("trsports_tradingjournal_dev")]
    M["schema: main\nusers, teams, groups,\nraw_trade_access"]
    AT["schema: alerts_tradingview\nindicator_alerts, fills,\nuser_app_access"]
    AC["schema: accountability\nsessions, positions, trades_closed"]
  end

  subgraph apps["Properties"]
    MGP[MGP static]
    SC[Scorecards + PHP APIs]
    PB[Playbooks]
    SYS[System hub]
    HUD[Accountability v2\nNode + PHP + SSE]
    JRN[A1 Prospect journal\nPHP session]
  end

  TSA --> MGP & SC & PB & SYS
  SMB --> HUD
  SMB -.->|symlinks| MGP & SC & PB & SYS
  WP --> JRN

  JRN --> M
  HUD --> AC & AT
  SC --> M & AT
```

### 2.2 Live data paths (audit-aligned)

| Surface | Trade / P&amp;L truth | Alerts / enrichment |
|--------|---------------------|---------------------|
| **Accountability v2** | `accountability.*` projected from `alerts_tradingview.fills` | HUD API = cockpit source of truth |
| **Scorecards** | **KTI CLI** (`kti trades date`) | `alerts_tradingview.indicator_alerts` |
| **Monthly reports** | **HUD API** (`trader-range.php`) | KTI for per-symbol only |
| **Legacy journal** | `main.*` (largely **unused** in live generators) | Session auth + teams/groups |

### 2.3 Schema boundaries (design firewall)

| Schema / database | Owns | Auth model (today) |
|-------------------|------|---------------------|
| **`main`** | Users, teams, groups, trade ACLs, journal-related tables | PHP session (`session_guard.php`, `login_user.php`) |
| **`alerts_tradingview`** | TV webhooks, `indicator_alerts`, **`fills`** (v2 ingest), SMB app grants | Webhook `shared_secret`; `user_app_access` per app |
| **`accountability`** | Live HUD state (positions, daily stop, breaches) | Relay token on ingest; HUD reads mostly open |
| **`trsports_accountability_dev`** | Optional **dev-only database** for v2 (not a schema name) | Profile via `LA_V2_DB_PROFILE` |

### 2.4 Host / URL migration note

Symlinks under `/gt_dev` and **`/gt_dev/ams`** pointing at `trsports_gd/html/{mgp,system,playbooks,scorecards}` are a valid bridge until files move. Canonical public host is **`https://smb.a1prospect.com`** with lenses grouped under the **`/ams/`** prefix (see §2.5).

### 2.5 Canonical entry point — Architecture Hub (production)

**Primary URL for operators and “where everything lives”:**

**[https://smb.a1prospect.com/ams/system/](https://smb.a1prospect.com/ams/system/)**

That hub ([Trade Accountability System — Architecture Hub](https://smb.a1prospect.com/ams/system/)) is the intended front door to todos, property links, freshness (`/ams/system/freshness.json` once paths are aligned), and Phase 0 messaging. Integration work should:

| Topic | Convention |
|-------|------------|
| **Hub / doctrine** | Treat **`/ams/system/`** as canonical on SMB (confirm Apache maps this path; avoid assuming only `/system/` at vhost root unless Alias duplicates it). |
| **Sibling properties on SMB** | Typically **`/ams/mgp/`**, **`/ams/scorecards/`**, **`/ams/playbooks/`**, etc., matching the `ams` symlink layout. |
| **Shared assets** | **`/_shared/nav.js`** — verify how the hub resolves shared URLs from `/ams/` (relative vs absolute) so nav and freshness do not 404. |
| **Cross-links in generators** | Prefer **`https://smb.a1prospect.com/ams/...`** as the default base in new config; retire `trsportsacademy.com` in user-facing links per migration plan. |

The live hub still describes some spine tables (e.g. `main.journal` as trade SoT) that the May 16 **data-path trace** contradicts for scorecards/HUD — reconcile hub copy with corrected data contracts during Phase 0–1.

---

## 3. Integration target (cohesive product)

**Working name:** *A1 Prospect Accountability Platform* — one login, shared trader identity, existing property UIs unchanged where possible.

### 3.1 Design principles

| # | Principle |
|---|-----------|
| 1 | **One identity path** — `account_id → user_id → display_name` across journal, generators, HUD. |
| 2 | **One auth front door** — journal session + teams/groups; static lenses behind the same gate where required. |
| 3 | **Explicit data contracts** — document source of truth per metric (HUD P&amp;L vs KTI gross vs indicator enrichment). |
| 4 | **Schema firewall** — no cross-schema convenience joins without documented views or APIs. |
| 5 | **Preserve generators** — `gen_scorecard.py`, `gen_mgp.py`, orchestrator; avoid rebuilding analytics in the browser. |

### 3.2 Target integration layer (conceptual)

```mermaid
flowchart LR
  subgraph gate["Integration layer (target)"]
    AUTH[Session + RBAC middleware]
    ID[resolve_user PHP/Python]
    NAV["/_shared/nav.js +\nsmb.a1prospect.com/ams/ base"]
    FRESH["/system/freshness"]
  end

  subgraph existing["Keep UI + generators"]
    MGP2[MGP]
    SC2[Scorecards]
    HUD2[Accountability v2]
    PB2[Playbooks]
    JRN2[Journal features]
  end

  subgraph spine2["Postgres spine"]
    PG[(Postgres)]
  end

  AUTH --> MGP2 & SC2 & HUD2 & PB2 & JRN2
  ID --> SC2 & HUD2
  PG --> existing
```

---

## 4. Phased project plan

**Assumptions:** Part-time execution (~2–3 focused days/week); James/jimbo for user-owned DDL and HUD bugs; calendar anchor **2026-05-19** (Monday after audit weekend). Adjust dates if start slips.

### Phase 0 — Foundation freeze (audit-aligned)

**Window:** 2026-05-19 → 2026-06-06 · **Critical path**

| ID | Work | Owner | Depends on | Unlocks |
|----|------|-------|------------|---------|
| P0-1 | **Schema/task audit** — grep todos/code for `main.journal`, `main.closed_trades`; re-scope stale tasks | Claude + James review | — | Honest foundation queue |
| P0-2 | **Freshness dashboard** — HUD API + `indicator_alerts` + KTI probe + output mtimes | Claude | P0-1 | Ops visibility across properties |
| P0-3 | **Nightly orchestrator** — single log, all generators | Claude | — | Silent-failure detection |
| P0-4 | **`p0-identity-fn`** — PHP + Python `resolve_user()` | Claude | — | Multi-trader, dropdowns |
| P0-5 | **Catalog cutover** — consumers → `/system/strategies.json` | Supervised | — | Strategy drift stops |
| P0-6 | **Param surface registry** | Claude | Partial P0-5 | Per-strategy grids |
| P0-7 | **MGP scheduler fix + independent pipeline cutover** | James + Claude | — | Monday reliability |
| P0-8 | **Acct v2 P0 bugs** (risk-bump, ticket-meter date range) | jimbo | — | Trust in cockpit SoT |
| P0-9 | **Risk HUD decision** — archive vs merge into acct-v2 | James | P0-8 | Five blocked risk_hud tasks |

**Exit criteria:** Freshness operational; identity helper used in ≥2 generators; catalog single-source where agreed; MGP cron reliable; HUD date-range bugs fixed.

---

### Phase 1 — Schema hygiene &amp; URL canonicalization

**Window:** 2026-06-09 → 2026-07-04

| ID | Work | Depends on |
|----|------|------------|
| P1-1 | **Schema boundary doc** (one page per schema: tables, writers, readers) | P0-1 |
| P1-2 | **Unify `db.json` profiles** — single matrix; remove duplicate creds (e.g. scorecards APIs) | P1-1 |
| P1-3 | **SMB URL pass** — nav, playbooks, generators: smb base | Symlinks stable |
| P1-4 | **`user_app_access` ↔ `main.users` mapping** — bridge webhook identity to journal users | P0-4 |
| P1-5 | **Webhook + DDL hygiene** — indicator alerts DDL, audit-webhook-coverage, wire-webhooks | User DDL |
| P1-6 | **Cross-nav (`ux-cross-nav`)** on lens properties | P1-3 |
| P1-7 | **Promote acct-v2 dev → prod** (after Kore bridge + services) | P0-8, P0-9 |

**Exit criteria:** Documented writers/readers per schema; no stray hardcoded DB passwords in apps; public links smb-aligned.

---

### Phase 2 — Auth gateway &amp; team sharing (journal model on lenses)

**Window:** 2026-07-07 → 2026-08-15 · **Critical path for protected data**

| ID | Work | Depends on |
|----|------|------------|
| P2-1 | **`add-user-role-approval`** — roles, approval workflow | P0-4 |
| P2-2 | **Auth shell for static properties** — thin PHP wrapper or Apache include after `session_guard` | P1-2, P2-1 |
| P2-3 | **Scope APIs** — extend pattern from `get-user-scope.php` / ACL for `scorecards/api/*` | P2-2 |
| P2-4 | **HUD trader selector** — session user + permitted traders | P2-1, P0-4 |
| P2-5 | **Shared user dropdown component** | P2-1 |
| P2-6 | **A1 Prospect journal ↔ SMB nav** — login on smb, links to journal where needed | P1-3, P2-2 |

**Exit criteria:** Unauthenticated users cannot open protected smb lenses (as scoped); team visibility matches `raw_trade_access` / group rules; HUD respects trader permissions.

---

### Phase 3 — Deep integration &amp; multi-trader

**Window:** 2026-08-18 → 2026-09-26

| ID | Work | Depends on |
|----|------|------------|
| P3-1 | **Multi-trader scorecards** | P2-5 |
| P3-2 | **Monthly per-trader view** | P3-1 |
| P3-3 | **Strategy Library upload UI** | P2-1, P0-5 |
| P3-4 | **Live grade → HUD** (supervised) | Webhooks + catalog |
| P3-5 | **Einstein fill stream** (optional; see `DECISIONS-streaming.md`) | P1-7 |
| P3-6 | **Physical file migration** — retire symlinks after copy to `gt_dev` | P1-3, P2-2 stable |
| P3-7 | **Journal trade path decision** — align scorecards with chosen SoT | P1-1, P0-8 |

**Exit criteria:** Named traders on scorecards/HUD with roles; migration runbook tested; single deploy root direction clear.

---

### Phase 4 — Hardening &amp; optional consolidation

**Window:** 2026-09-29 → 2026-10-24

| Theme | Examples |
|-------|----------|
| Operations | Orchestrator alerting from freshness signals |
| Retirement | `live/` legacy tree; risk_hud mock page if archived |
| Identity | WordPress journal same host vs SSO bridge |
| Performance | SSE scaling, chart cache policy |

---

## 5. Gantt chart (Mermaid)

Paste into [mermaid.live](https://mermaid.live) if your viewer does not render Gantt.

```mermaid
gantt
    title A1 Prospect Integration — 2026 (indicative)
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Phase 0 Foundation
    Schema/task audit           :p01, 2026-05-19, 5d
    Freshness dashboard         :p02, after p01, 8d
    Identity fn                 :p04, 2026-05-26, 10d
    Catalog cutover             :crit, p05, 2026-06-02, 5d
    Orchestrator                :p03, 2026-05-26, 7d
    MGP cutover + cron          :crit, p07, 2026-05-19, 14d
    Acct v2 P0 bugs             :crit, p08, 2026-05-19, 10d
    Risk HUD decision           :p09, 2026-05-26, 7d

    section Phase 1 Hygiene
    Schema boundary doc         :p11, 2026-06-09, 5d
    db.json + API creds         :p12, after p11, 8d
    SMB URL canonicalization    :p13, 2026-06-16, 10d
    Webhook DDL chain           :p15, 2026-06-09, 20d
    Acct v2 prod promote        :milestone, p17, 2026-07-04, 0d

    section Phase 2 Auth
    User roles + approval       :p21, 2026-07-07, 10d
    Auth shell static props     :crit, p22, after p21, 15d
    API scope + team ACLs       :crit, p23, after p22, 12d
    HUD trader selector         :p24, after p21, 10d

    section Phase 3 Multi-trader
    Multi-trader scorecards     :p31, 2026-08-18, 15d
    File migration gt_dev       :p36, 2026-09-15, 10d
    Trade SoT decision          :p37, 2026-08-18, 20d

    section Phase 4 Hardening
    Legacy retire + SSO         :p41, 2026-09-29, 20d
```

---

## 6. Critical path summary

**Suggested critical path:**

`MGP reliability` → `HUD trust (P0 bugs)` → `identity-fn` → `auth shell` → `API scoping` → `multi-trader scorecards` → `physical migration`.

**Parallel tracks:** Freshness dashboard, orchestrator, catalog cutover, webhook enrichment (after user DDL).

---

## 7. What not to do (audit lessons)

| Avoid | Why |
|-------|-----|
| **`main.daily_summary` as blind first fix** | Live path uses HUD + KTI; empty `main.journal` in scorecard path — re-scope or mirror HUD export |
| **Big-bang merge of schemas** | Keep `accountability` for live state; `alerts_tradingview` for events; `main` for identity |
| **Rewrite MGP/Scorecards UI** | Generators + static HTML work; add gate + identity |
| **Risk HUD build before dedup decision** | Audit recommends archive if acct-v2 subsumes |
| **Move all files before auth** | Symlinks acceptable until smb login works |

---

## 8. Reuse map (maximize existing code)

| Capability | Reuse |
|------------|--------|
| Login, 2FA, lockout | `a1p_journal/src/php/login_user.php`, `session_guard.php` |
| Teams / groups / trade sharing | `main` DDL: teams, groups, `raw_trade_access`; `get-user-scope.php` |
| Live cockpit | `accountability-v2/` (ingest, SSE, HUD) |
| Alerts / TradingView | `src/php/webhooks/*`, `alerts_tradingview.*` |
| Daily plans | MGP generators + static pages |
| Execution grading | `gen_scorecard.py`, scorecards overlays |
| Doctrine / nav | `/system/`, `strategies.json`, `/_shared/nav.js` |
| Ops | `update_freshness.py`, todos PM |
| SMB app RBAC seed | `extend_alert_users.sql` — align with `main.users` |

---

## 9. Risks and mitigations

| Risk | Mitigation |
|------|------------|
| Two P&amp;L definitions (KTI gross vs HUD net) | Document in UI; scorecards label pre-commission; monthly stays HUD-aligned |
| HUD regressions | Supervised-only HUD card edits; DEV HUD first |
| Symlinks broken on Windows `Z:\gt_dev` mount | Validate on Linux server paths; deploy scripts target production FS |
| User-owned DDL slips | Gate webhook chain on migrations |
| Scope creep | Finish Phase 0 before Phase 3 features |

---

## 10. Immediate next steps (week of 2026-05-19)

| Step | Action |
|------|--------|
| 1 | Approve schema/task re-scope from `data-path-trace.md` (e.g. `p0-daily-summary-view`, drop dead `main.journal` assumptions where applicable). |
| 2 | Resolve **risk_hud vs accountability_v2** (one decision unblocks five tasks). |
| 3 | Apply supervised picks if not done: catalog cutover, `add-user-role-approval`. |
| 4 | Fix **MGP cron** + **acct-v2 P0 bugs** before heavy auth work. |
| 5 | Publish **schema boundary doc** as Phase 1 gate. |

---

## 11. Open decisions (fill in)

| Question | Decision |
|----------|----------|
| WordPress journal merge onto smb vs SSO-only? | |
| Acct-v2 prod promote before or after auth shell? | |
| Phase 3 user count (James-only vs firm-wide)? | |

---

## Document history

| Date | Change |
|------|--------|
| 2026-05-16 | Initial plan exported from integration discussion + May 16 audit references |
| 2026-05-16 | Branding: use **A1 Prospect** (not Grumpy Trade) throughout |
| 2026-05-16 | **Canonical hub:** `https://smb.a1prospect.com/ams/system/` (§2.5); `/ams/` prefix for SMB lenses |
