39246-vm/docs/MEMORY.md

Ghost Node — Session Memory

What belongs here: Current architecture state, key gotchas, reusable patterns, dev paths. What does NOT belong here: Session history (→ PROGRESS.md or ARCHIVE.md).

⚠️ MD Update Rule — DYNAMIC, NOT STATIC

Only update the MD file(s) whose content was actually touched this session. Do NOT update all files after every task. Each file gets only what is relevant to it.

• Update this file only when a new reusable gotcha, pattern, or architecture decision was made.
• Update PROGRESS.md whenever any code file was changed.
• Update CLAUDE.md only if API endpoints, DB schema, config keys, or architecture changed.
• Move old PROGRESS.md session entries to ARCHIVE.md when they're no longer active context.

---

Project Identity

• Ghost Node International Auction Sniper v2.7
• Owner: Abbas, Baghdad, Iraq
• Path: C:\Users\Abbas\Documents\Downloads\ClaudeAuction2\
• Backend: Python FastAPI (worker.py, 5000+ lines), port 8000
• NOT a git repository

---

Frontend Stack (Current — Session 16, fully migrated)

• Location: frontend/ directory
• Next.js 16.1.6, React 19, TypeScript, Tailwind CSS v4 (NOT v3)
• Tailwind v4: CSS variables via @theme {} in globals.css — NO tailwind.config.ts
• Session 27 redesign: CSS prefix changed from ghost-* to g-*. Colors: --color-g-base (#050510), --color-g-green (#00e87b), --color-g-cyan (#06b6d4), etc. Classes: bg-g-base, text-g-green. Components: .g-card, .g-card-glow, .g-btn, .g-btn-primary, .g-badge, .g-table, .glass, .glass-strong, .gradient-text, .gradient-accent. Backward compat aliases (.card-panel, .btn-ghost, .btn-danger, .page-title, .page-subtitle) still work.
• output: 'export' in next.config.ts → static build at frontend/out/
• Node.js: default installer C:\Program Files\nodejs\ (on PATH). Alternative: portable at C:\Users\Abbas\AppData\Local\nodejs-portable\node-v22.14.0-win-x64\

Key Architecture Decisions

• SSE route disabled for static build (app/api/stream/route.ts.disabled)
• All API files use http://localhost:8000 as BASE (full URL, not relative)
• FastAPI serves Next.js static build when frontend/out/ exists
• if _frontend_out.exists(): guard is safe — dashboard.html still works without out/ dir
• SPA routing: app.mount("/_next", ...) for assets only + @app.get("/{full_path:path}") catch-all for SPA routing. Never use app.mount("/", StaticFiles(html=True)) — it shadows all explicit routes

File Structure

frontend/
├── app/
│   ├── ai-log/page.tsx
│   ├── dashboard/page.tsx
│   ├── keywords/page.tsx
│   ├── listings/page.tsx
│   ├── settings/page.tsx
│   ├── sites/page.tsx
│   ├── globals.css (Tailwind v4 @theme, cyberpunk palette, btn-ghost, btn-danger)
│   ├── layout.tsx
│   ├── page.tsx (redirects to /dashboard)
│   └── providers.tsx ('use client' QueryClientProvider)
├── components/
│   ├── ai-log/ (AILogCard, AILogFeed)
│   ├── dashboard/ (StatsGrid, ActivityLog)
│   ├── keywords/ (KeywordRow, KeywordsTable — dnd-kit, ScoringRulesPanel)
│   ├── layout/ (Header, Nav, StatusBar)
│   ├── listings/ (ListingRow, ListingsTable, ListingDetailPanel, ImageGallery)
│   └── sites/ (SiteRow, SitesTable — dnd-kit)
├── hooks/ (useSSE, useListings, useCountdown, useKeywords, useSites)
├── lib/
│   ├── api/ (listings, keywords, sites, config, engine, system, ai, scoring-rules)
│   ├── types.ts
│   └── utils.ts (cn, formatUptime)
├── store/ (engineStore, settingsStore)
├── out/ (static build — served by FastAPI)
└── vitest.config.ts (has @/ alias resolution)

Tests (21 passing)

• theme.test.ts (2), types.test.ts (4), engineStore.test.ts (3)
• listings-api.test.ts (3), useCountdown.test.ts (2)
• StatsGrid.test.tsx (1), StatusBar.test.tsx (3), ListingRow.test.tsx (3)

---

Dev Paths & Commands

Node.js

• Default installer (C:\Program Files\nodejs\): usually on system PATH — open new terminal and run node --version; no manual PATH needed.
• Portable (if used): set PATH in each shell before npx/npm:
  • PowerShell: $env:PATH = "C:\Users\Abbas\AppData\Local\nodejs-portable\node-v22.14.0-win-x64;$env:PATH"
  • Bash: export PATH="/c/Users/Abbas/AppData/Local/nodejs-portable/node-v22.14.0-win-x64:$PATH"

Common Commands

# Start backend
python worker.py                          # port 8000

# Frontend build (from project root)
export PATH="..." && npm run build --prefix frontend

# Run tests (from project root)
export PATH="..." && cd frontend && npx vitest run

# Combined build + test
export PATH="..." && cd frontend && npx vitest run && npm run build

---

Key Gotchas (Never Forget These)

Python / Backend

• threading.Event not asyncio.Event for cross-thread signalling — asyncio.Event is not thread-safe
• SQLite enabled field: Store as int (1/0), never bool — filter(enabled==1) breaks on Python True
• JS in f-strings: Use backtick template literals, never apostrophes — breaks Python f-string parsing
• db.flush() before db.commit(): SQLite WAL locking requires this
• calculate_attribute_score() opens own DB session — don't call inside an already-open session loop
• closing_alerts_sent: JSON list — always json.loads + append, never overwrite

FastAPI Routing

• NEVER app.mount("/", StaticFiles(html=True)) with explicit routes you want to preserve — the root mount captures ALL paths. SPA fallback returns 200+index.html for unknown paths, shadowing @app.get("/legacy") etc.
• Fix: app.mount("/_next", ...) for assets + @app.get("/{full_path:path}") explicit catch-all

API Format

• /api/config GET returns flat {key: value} dict, NOT Config[] array
• /api/config POST expects flat dict — not [{key, value}] array
• Frontend fetchConfig() must call .then(data => setConfig(data)) directly — no .map()

Frontend

• SSE disabled in static export — EventSource('/api/stream') always 404s. Use HTTP polling instead
• createPortal needs SSR guard — document.body unavailable during Next.js SSR. Use useEffect(() => setMounted(true), []) before rendering portal

HiBid

• Apollo cache: Search results pages have 0 Lot entries — images only from detail pages
• Image dedup: Use full URL including query string (HiBid CDN uses same path img.axd for all images, differentiated only by query params)

---

Pending Work (Priority Order)

1. Redis Cache Layer — replace in-memory Python dicts; survives restarts; pub/sub for live dashboard
2. Docker Compose — one-command startup with PostgreSQL + Redis
3. Lot Description Extraction — AI only sees title; detail page descriptions → better AI-first accuracy. Needs JS_DETAIL_TEXT + description column on Listing + pass to _ai_analyze()