Spaces:
Running
Running
| # U2INVEST Current Product PRD | |
| ## 1. Executive Summary | |
| U2INVEST is a three-pillar financial product that combines: | |
| 1. Knowledge Academy | |
| 2. Trading Lab | |
| 3. U2CHAT AI assistant | |
| The current implementation is a Flask-served single-page web app with: | |
| - one primary frontend file: `templates/index.html` | |
| - one primary backend/API file: `web_app.py` | |
| - a LangGraph agent workflow: `agent_graph.py` | |
| - stock/RAG tools: `tools.py` | |
| - a Chroma-backed PDF knowledge pipeline: `vector_store.py` | |
| - a CLI-style agent test entrypoint: `main.py` | |
| This PRD is not a concept document. It is a product-truth document for the current repository. It extracts the actual functions, features, states, gaps, and upgrade paths so the whole UI can be rebuilt without losing product scope. | |
| ## 2. Product Vision | |
| Help beginner and intermediate investors learn investing, practice safely, and ask an AI assistant for analysis inside one integrated product. | |
| ## 2.1 Commercial Website Vision | |
| U2INVEST should not behave only like an internal demo app or portfolio prototype. As a commercial web product, it should also present itself like a credible business: | |
| - discoverable | |
| - trustworthy | |
| - contactable | |
| - explainable | |
| - legally defensible | |
| - conversion-oriented | |
| That means the final product should include both: | |
| - the product application layer | |
| - the public business/marketing/sales website layer | |
| ## 3. Rebuild Objective | |
| Rebuild the entire UI while preserving the full current functional scope, making the product: | |
| - simpler | |
| - calmer | |
| - more premium | |
| - more structurally consistent | |
| - more maintainable | |
| - more trustworthy as a product | |
| The rebuild should not accidentally reduce scope. It should preserve the current breadth of Academy, Lab, and U2CHAT while fixing partial features and surfacing hidden capabilities. | |
| The rebuild should also expand the current landing shell into a proper commercial website experience with public-facing business, sales, trust, and contact functionality. | |
| ## 4. Target Users and Core Jobs | |
| ### Primary users | |
| - Beginner investors who want structured financial education | |
| - Early-stage self-directed investors who want a safe trading simulator | |
| - Users who want an AI assistant to explain stocks, market concepts, and strategies | |
| ### Secondary users | |
| - Recruiters or reviewers evaluating product thinking and technical execution | |
| - Users who want a local finance-learning demo with AI and charts | |
| - Prospective customers evaluating whether to trust or buy the product | |
| - Business partners, media contacts, and inbound collaborators | |
| - Prospective hires or stakeholders evaluating the company and product credibility | |
| ### Core jobs to be done | |
| - "Teach me the fundamentals of investing." | |
| - "Let me practice trading without risking money." | |
| - "Help me analyze a stock with live data and research context." | |
| - "Give me a workspace where learning, simulation, and AI analysis connect." | |
| - "Help me understand what this company/product is and whether I should trust it." | |
| - "Give me a clear way to contact the business, book a demo, or start using the product." | |
| - "Show me enough credibility, legal clarity, and product value to convert me into a lead or customer." | |
| ## 5. Current System Map | |
| ### Product shell | |
| - Flask serves a single-page frontend shell | |
| - SPA-like view switching happens in the browser through `showView()` | |
| - A browser session receives a generated `user_id` | |
| ### Core product surfaces | |
| - Landing page | |
| - Knowledge Academy | |
| - Trading Lab | |
| - U2CHAT | |
| - Public business/marketing website layer, currently only minimally represented by the landing page | |
| ### AI and data layer | |
| - LLM access is configured through `ChatOpenAI` using a DeepSeek-style OpenAI-compatible API | |
| - LangGraph manages reasoning plus tool routing | |
| - SQLite persists LangGraph checkpoints | |
| - AkShare provides live stock data when available | |
| - Chroma stores local knowledge-base embeddings | |
| - PDFs in `knowledge/` power retrieval | |
| ### Deployment layer | |
| - Local Python execution | |
| - Dockerfile | |
| - `docker-compose.yml` | |
| - `.env` configuration | |
| ## 6. Detailed Current Feature Inventory | |
| ## 6.1 Landing and Global Navigation | |
| ### User-facing features | |
| - Fixed top navigation with logo and links to Academy, Lab, and U2CHAT | |
| - Branded landing hero with product tagline | |
| - Three large entry cards for the three product pillars | |
| - In-browser view switching without page reload | |
| ### Supporting frontend functions | |
| - `showView(v)` | |
| ### Supporting backend functions | |
| - `index()` | |
| ### Current status | |
| - Implemented | |
| ### Current gaps | |
| - No deep links for major product surfaces | |
| - No browser-history-aware routing | |
| - No route-level loading state | |
| - No persistent "last visited workspace" behavior | |
| - No commercial footer | |
| - No contact information surface | |
| - No social links | |
| - No company/about section | |
| - No trust or proof section | |
| - No demo, signup, or lead-capture CTA flow | |
| - No legal links or disclosures in the public shell | |
| ## 6.2 Knowledge Academy | |
| ### Current content model | |
| The Academy currently includes 50 hardcoded modules in `ACADEMY_DATA`. Each module includes: | |
| - `id` | |
| - `parent` | |
| - `cat` | |
| - `difficulty` | |
| - `name` | |
| - `video` | |
| - `source` | |
| - `views` | |
| - `completed` | |
| - `ratings` | |
| - `video_intro` | |
| - `outcomes` | |
| - `takeaways` | |
| ### User-facing features currently implemented | |
| - Academy landing view | |
| - Grid view of all modules | |
| - Category label on module cards | |
| - Module view counts on cards | |
| - Completion badge on cards | |
| - Lesson overlay panel | |
| - Embedded YouTube lesson video | |
| - Lesson intro copy | |
| - Outcomes list | |
| - Takeaways list | |
| - Completion state CTA | |
| - Comments thread | |
| - Comment replies | |
| - Comment sorting: Top / Newest | |
| - Share modal | |
| - Share actions for WhatsApp, Facebook, X, LinkedIn, email, copy link | |
| - Visual roadmap mode | |
| - Curated roadmap mode: "Designed By U2INVEST" | |
| - Custom roadmap mode: "You to Design" | |
| - Custom roadmap actions: | |
| - add node | |
| - drag node | |
| - connect nodes | |
| - break link | |
| - delete node | |
| - Toast notifications | |
| - Confirmation modal for roadmap destructive actions | |
| ### Frontend functions powering Academy | |
| - `loadData()` | |
| - `openModule(id)` | |
| - `openShare()` | |
| - `closeShare()` | |
| - `copyLink()` | |
| - `renderComments(list)` | |
| - `replyAt(user, commentId)` | |
| - `replyToReply(user, parentCommentId)` | |
| - `cancelReply()` | |
| - `postComment()` | |
| - `setRoadmapMode(mode)` | |
| - `initRoadmap()` | |
| - `dragstarted(event, d)` | |
| - `dragged(event, d)` | |
| - `dragended(event, d)` | |
| - `renderCustomRoadmap(g, svg)` | |
| - `resetPorts()` | |
| - `openConfirm(title, desc, onOk, onCancel)` | |
| - `openNodeModal()` | |
| - `closeNodeModal()` | |
| - `addCustomNode()` | |
| - `switchAcademy(tab)` | |
| - `closeModule()` | |
| - `renderStatusBox(isDone)` | |
| - `toggleStatus(isDone)` | |
| - `sortComments(type)` | |
| - `showToast(msg)` | |
| ### Backend/API functions powering Academy | |
| - `get_academy()` | |
| - `get_course(cid)` | |
| - `post_comment()` | |
| - `like_comment_main()` | |
| - `like_reply_unique()` | |
| - `toggle_complete()` | |
| - `rate_course()` | |
| ### What is fully implemented | |
| - Module browsing | |
| - Module overlay experience | |
| - Comment posting and replies | |
| - Completion toggle | |
| - Average rating display | |
| - Curated roadmap rendering | |
| - Custom roadmap editing in current browser session | |
| ### What is partial or latent | |
| - `parent` exists in the data model but is not used as the real prerequisite structure in the UI | |
| - `source` exists in the data model but is not surfaced in the UI | |
| - `difficulty` is used in roadmap coloring but not clearly surfaced elsewhere | |
| - `rate_course()` exists in the backend, but there is no visible rating submission UI in the current frontend | |
| - `like_comment_main()` and `like_reply_unique()` exist in the backend, but the frontend references `toggleLike()` and `toggleReplyLike()` handlers that do not exist | |
| - Comment dislike icons are visual only and do not trigger anything | |
| - Share URLs point to `/module/<id>`, but that route is not implemented in Flask | |
| ### Known Academy issues to carry into the rebuild plan | |
| - Comment like buttons are visible but broken because the JS handlers are missing | |
| - Rating is display-only in the current UI | |
| - Shared module URLs are not truly deep-linkable | |
| - Comment timestamps are rendered as hardcoded "2 hours ago" / "1 hour ago" strings, not real relative times | |
| - Academy progress, comments, and ratings are stored in runtime memory only | |
| - Academy progress is not per-user durable data | |
| - Academy state is globally mutable on the server | |
| - `get_course(cid)` does not guard missing IDs cleanly before `.copy()` | |
| - Custom roadmap state is not persisted to local storage or backend | |
| - The auto roadmap is a generated visualization, not a precise prerequisite map | |
| ### Academy advancement opportunities | |
| - Make progress, comments, ratings, and custom roadmap persistent | |
| - Convert `parent` into a true learning dependency graph | |
| - Add search, filter, and sorting across modules | |
| - Add difficulty badges and progress percentages | |
| - Surface lesson `source` and instructor credibility more clearly | |
| - Add note-taking, bookmarks, and study highlights | |
| - Add quizzes, checkpoints, and completion scoring | |
| - Add user-specific learning plans and recommended next lessons | |
| - Add proper rating submission UI and review aggregation | |
| - Add moderation, abuse control, and comment reporting if community features stay | |
| - Add actual shareable deep links and direct-open module routes | |
| ## 6.3 Trading Lab | |
| ### Current product concept | |
| The Lab is a paper-trading workspace for A-share-style stock simulation, with a separate beginner guide path. | |
| ### User-facing features currently implemented | |
| - Lab gateway with two paths: | |
| - advanced dashboard | |
| - beginner guide | |
| - Beginner guide step flow with 3 educational steps | |
| - Stock pool grouped by sectors: | |
| - Popular | |
| - Tech | |
| - Energy | |
| - Finance | |
| - Quote cards for stocks in the selected sector | |
| - Stock selection for chart/trade context | |
| - K-line chart area | |
| - Trade ticket with symbol, price, shares, and total | |
| - Buy action | |
| - Sell action | |
| - Holdings panel | |
| - History panel container | |
| - Portfolio stats: | |
| - Total Assets | |
| - Cash | |
| - Profit | |
| - Return | |
| - Reset portfolio | |
| - Refresh dashboard | |
| ### Data model and business rules | |
| - Starting cash: $100,000 | |
| - Holdings are tracked per symbol | |
| - Trade history is stored on buy/sell | |
| - Buy checks available cash | |
| - Sell checks whether holdings exist and whether the user has enough shares | |
| - Frontend requires minimum `100` shares | |
| ### Frontend functions powering Trading Lab | |
| - `loadLabData()` | |
| - `loadSectorStocks()` | |
| - `selectStock(stock)` | |
| - `initKlineChart()` | |
| - `loadKlineData(symbol, days = 60)` | |
| - `calculateTotal()` | |
| - `executeTrade(action)` | |
| - `updatePortfolioUI()` | |
| - `resetPortfolio()` | |
| - `refreshLab()` | |
| - `updateGuideUI()` | |
| - `nextGuideStep()` | |
| - `prevGuideStep()` | |
| - `setLabView(view)` | |
| ### Backend/API functions powering Trading Lab | |
| - `get_stock_pool()` | |
| - `get_real_quote()` | |
| - `get_kline_data()` | |
| - `get_portfolio()` | |
| - `execute_trade()` | |
| - `reset_portfolio()` | |
| - `get_market_data()` | |
| ### What is fully implemented | |
| - Gateway flow between beginner and advanced entry | |
| - Beginner guide progression | |
| - Sector-based stock list loading | |
| - Quote retrieval with live-data fallback behavior | |
| - K-line retrieval with live-data fallback behavior | |
| - Paper buy/sell execution | |
| - Cash/holdings update logic | |
| - Portfolio reset | |
| ### What is partial or latent | |
| - Trade history is stored in backend state but not rendered into the visible `history-list` | |
| - Return stat exists in the UI but is not updated in `updatePortfolioUI()` | |
| - Time-range buttons `60D`, `120D`, `250D` are visible, but `changeTimeRange()` does not exist | |
| - `get_market_data()` exists as a synthetic endpoint but is not used by the current main UI | |
| - `user_portfolio.json` exists in the repo but is not used by the current app | |
| ### Known Trading Lab issues to carry into the rebuild plan | |
| - Stock selection uses `event.currentTarget` without passing `event`, so the behavior is fragile | |
| - Portfolio value is calculated from average cost basis, not live mark-to-market pricing | |
| - Profit shown is therefore not true unrealized P&L | |
| - Return shown is currently a placeholder | |
| - History panel is currently a placeholder | |
| - Backend trusts the client-supplied execution price in `/api/lab/trade` | |
| - No watchlist, compare view, or market context around a selected stock | |
| - No order types beyond instant buy/sell | |
| - No slippage, fees, order status, or risk feedback | |
| - Lab state is per-session in memory only and resets on server restart | |
| ### Trading Lab advancement opportunities | |
| - Implement live mark-to-market portfolio valuation | |
| - Render complete transaction history with timestamps and realized/unrealized P&L | |
| - Implement `changeTimeRange()` and persist selected chart interval | |
| - Add watchlists and favorite symbols | |
| - Add news and fundamentals side panels for the selected stock | |
| - Add comparison mode across multiple stocks | |
| - Add educational hints tied to user actions | |
| - Add more order types: market, limit, stop, stop-limit | |
| - Add simulated fees, taxes, and slippage | |
| - Add portfolio allocation visualization and performance analytics | |
| - Add saved paper accounts and multiple portfolios | |
| - Make the server authoritative for pricing instead of trusting client price input | |
| ## 6.4 U2CHAT | |
| ### Current product concept | |
| U2CHAT is a financial assistant that combines: | |
| - LLM reasoning | |
| - tool calling | |
| - local knowledge retrieval | |
| - stock-related quick context selection | |
| - inline chart rendering in chat | |
| ### User-facing features currently implemented | |
| - Dedicated chat workspace | |
| - Sidebar with recent sessions | |
| - New chat action | |
| - Session reload from sidebar | |
| - Clear current chat | |
| - Quick stock-select chips by sector | |
| - Selected-stock chip strip | |
| - Prompt input with auto-resize | |
| - Enter to send | |
| - Shift+Enter for newline | |
| - Stop button state during generation | |
| - Assistant/user message bubbles | |
| - Simple markdown-like rendering for headings and bullets | |
| - Inline chart rendering from `json-chart` blocks | |
| - Empty state for no conversation | |
| ### Frontend functions powering U2CHAT | |
| - `loadAgentData()` | |
| - `loadAgentStocks()` | |
| - `addStockToChat(stock)` | |
| - `updateSelectedStocks()` | |
| - `removeStock(i)` | |
| - `sendMessage()` | |
| - `updateSendButtonState()` | |
| - `addMessageToUI(role, content, tools = [])` | |
| - `renderChart(containerId, data)` | |
| - `loadChatSessions()` | |
| - `loadChatSession(sessionId)` | |
| - `clearChat()` | |
| - `newChat()` | |
| - `handleAgentKey(e)` | |
| - `autoResize(t)` | |
| ### Backend/API functions powering U2CHAT | |
| - `agent_chat()` | |
| - `get_chat_sessions()` | |
| - `get_chat_history()` | |
| - `clear_chat_history()` | |
| ### Agent workflow functions | |
| - `AgentState` | |
| - `call_model(state)` | |
| - `route_logic(state)` | |
| ### Agent tools | |
| - `get_realtime_quote(symbol)` | |
| - `get_stock_news(symbol)` | |
| - `get_historical_kline(symbol)` | |
| - `get_fundamental_data(symbol)` | |
| - `query_knowledge_base(query)` | |
| ### What is fully implemented | |
| - Chat session creation | |
| - Session title generation from the first message | |
| - Session history retrieval while the server is running | |
| - LangGraph-based tool routing | |
| - LLM response generation | |
| - Inline chart rendering from model-generated JSON blocks | |
| - Sector-based quick stock selection | |
| - PDF-based retrieval tool availability | |
| ### What is partial or latent | |
| - `agent_chat()` internally iterates `stock_agent_app.stream(...)`, but the frontend does not receive true streaming output; it waits for the final JSON response | |
| - Tool call metadata is collected as `tools_used`, but the frontend does not surface it | |
| - The "stop" button aborts the browser request, but there is no backend cancellation mechanism | |
| - Chat persistence is split: | |
| - visible session metadata and messages are in memory | |
| - LangGraph checkpoints are in SQLite | |
| - Quick stock selection adds stock text into the prompt, but does not create structured chat context objects | |
| ### Known U2CHAT issues to carry into the rebuild plan | |
| - If the server restarts, the sidebar session list and visible session history are lost | |
| - SQLite checkpoints survive, but the current UI model does not reconnect to them cleanly | |
| - `renderChart()` supports simple line/bar assumptions only | |
| - The system prompt mandates structured English responses, but the UI does not visibly explain the assistant's answer format | |
| - The app stores tool call names and args, not a clear user-facing execution trace | |
| - No citation/source cards are shown for RAG output | |
| - No streaming token UI or stepwise reasoning trace is exposed | |
| - `addMessageToUI()` injects rendered HTML directly, which should be treated carefully in a full rebuild | |
| ### U2CHAT advancement opportunities | |
| - Add true streaming responses to the UI | |
| - Add server-side cancellation or job interruption support | |
| - Surface tool usage, tool results, and sources visibly | |
| - Show retrieval sources with document titles and snippets | |
| - Add follow-up suggestions and prompt shortcuts | |
| - Add chart cards, ticker cards, and fundamentals cards as structured UI blocks | |
| - Add conversation search, pinning, renaming, and grouping | |
| - Add better state recovery after refresh and restart | |
| - Add a dedicated research mode, beginner mode, and fast quote mode | |
| - Add file upload and portfolio-aware chat once persistence exists | |
| ## 6.5 Shared and Platform Features | |
| ### Current shared UX/system features | |
| - Toast notification surface | |
| - Confirmation modal | |
| - Custom-node modal | |
| - Session-based `user_id` | |
| - Environment-variable-based secret key | |
| - Broad CORS enablement | |
| - Dockerfile | |
| - Docker Compose mounts for: | |
| - `chroma_db` | |
| - `checkpoints.sqlite` | |
| ### AI/knowledge infrastructure features | |
| - PDF discovery across `knowledge/` recursively | |
| - Empty retriever fallback if no PDFs exist | |
| - PDF loading with `PyPDFLoader` | |
| - Content deduplication by MD5 hash | |
| - Metadata enrichment for source tracking | |
| - Chunking with overlap | |
| - Persistent Chroma vector store | |
| - Incremental addition when new files appear | |
| - Retriever configured with `k=5` | |
| ### Developer and demo features | |
| - CLI interactive session in `main.py` | |
| - Synthetic market endpoint `get_market_data()` | |
| ### Current platform gaps | |
| - No authentication layer | |
| - No persistent database for Academy or Lab user state | |
| - No test suite in the current repo | |
| - No analytics or product instrumentation | |
| - Frontend is monolithic and globally stateful | |
| - Vector-store refresh logic detects new files, but not modified/deleted files robustly | |
| ## 6.6 Commercial Website and Business Layer | |
| ### Current product reality | |
| The current repo has a landing page, branding, and product-entry navigation, but it does not yet function like a complete commercial business website. | |
| ### Current business-site features actually present | |
| - logo and brand mark | |
| - positioning tagline | |
| - top navigation | |
| - high-level entry points into the three product pillars | |
| ### Commercial website features required for a professional business product | |
| This section defines the required public-facing website layer that should exist alongside the product application. | |
| ### A. Global brand and navigation requirements | |
| - public homepage | |
| - consistent header navigation | |
| - clear primary CTA | |
| - secondary CTA for contact/demo/learn more | |
| - professional footer | |
| - company identity and copyright area | |
| - social links | |
| - legal links | |
| - contact links | |
| - app entry / sign in / get started entry points | |
| ### B. Marketing and sales page requirements | |
| - homepage with clear value proposition | |
| - product overview page | |
| - feature overview sections for Academy, Lab, and U2CHAT | |
| - use-case or solution sections | |
| - pricing page or pricing inquiry flow | |
| - demo-request flow | |
| - FAQ page or FAQ section | |
| - about/company page | |
| - contact page | |
| - resources/blog/news section | |
| - optional case studies/testimonials page | |
| ### C. Trust and credibility requirements | |
| - social proof or customer logos | |
| - testimonials or endorsements | |
| - team/founder credibility | |
| - explanation of product methodology | |
| - explanation of data sources | |
| - privacy and security positioning | |
| - financial education / not-financial-advice disclaimers where relevant | |
| - risk disclosure for finance-related content and simulation features | |
| - transparent explanation of what is live data vs simulated vs educational | |
| ### D. Lead generation and conversion requirements | |
| - contact form | |
| - demo-booking form | |
| - newsletter/signup capture | |
| - waitlist or get-started capture | |
| - strong CTA system across the site | |
| - success / thank-you states after form submission | |
| - lead routing to email/CRM | |
| - downloadable asset or resource capture if content marketing is used | |
| ### E. Social and communication requirements | |
| - LinkedIn link | |
| - X/Twitter link if used | |
| - GitHub link if relevant to brand/company presence | |
| - YouTube or media channel link if educational content is part of go-to-market | |
| - business email contact | |
| - optional phone number | |
| - optional business address or registered business location | |
| - press / partnership contact path | |
| ### F. Legal, compliance, and policy requirements | |
| - privacy policy | |
| - terms of service | |
| - cookie policy | |
| - disclaimer | |
| - risk disclosure | |
| - acceptable-use policy if user-generated content or AI chat remains public-facing | |
| - accessibility statement | |
| - data and AI usage disclosure | |
| ### G. SEO, discoverability, and content requirements | |
| - page titles and meta descriptions | |
| - Open Graph / social preview metadata | |
| - sitemap | |
| - robots configuration | |
| - structured data where useful | |
| - clean semantic headings | |
| - internal linking strategy | |
| - indexable product explainer content | |
| - resource/blog structure if SEO is part of acquisition | |
| ### H. Analytics, sales operations, and support requirements | |
| - page analytics | |
| - CTA click tracking | |
| - form conversion tracking | |
| - attribution tracking | |
| - CRM or inbox integration for inbound leads | |
| - contact management flow | |
| - support/help contact path | |
| - error/success instrumentation for forms and CTAs | |
| ### I. Finance-product-specific commercial requirements | |
| - clear statement of educational vs advisory scope | |
| - data freshness / source disclaimers | |
| - simulation disclaimers for the Trading Lab | |
| - AI-answer limitations and responsible-use language | |
| - clear explanation of whether the platform gives education, research assistance, or actionable advice | |
| ### Current status | |
| - mostly missing | |
| ### Known commercial website gaps in the current repo | |
| - no footer with business information | |
| - no contact page or contact form | |
| - no social links | |
| - no about/company page | |
| - no pricing or demo request flow | |
| - no lead-capture forms | |
| - no testimonials, customer proof, or trust content | |
| - no legal pages | |
| - no cookie/privacy consent flow | |
| - no support/help path | |
| - no SEO-oriented public content structure | |
| - no analytics or conversion tracking | |
| - no finance-specific commercial disclaimers in the public website shell | |
| ### Commercial website advancement opportunities | |
| - turn the landing page into a true commercial homepage | |
| - create a full footer and public information architecture | |
| - add contact, demo, and get-started flows | |
| - add proof, trust, and authority sections | |
| - add legal/compliance surface suitable for a finance-related product | |
| - add SEO and content marketing structure | |
| - add analytics and CRM integration | |
| - add conversion-focused CTA system across the entire public experience | |
| See `COMMERCIAL_WEBSITE_SITEMAP_AND_PAGE_SPEC.md` for the concrete sitemap, page-by-page public website specification, CTA architecture, footer requirements, form requirements, and lead funnel design. | |
| ## 7. Complete Engineering Function Inventory | |
| This section is the full code-level function inventory for rebuild planning. | |
| ## 7.1 `web_app.py` | |
| - `index()`: serve the main SPA and initialize `session['user_id']` | |
| - `get_academy()`: return the full Academy module list | |
| - `get_course(cid)`: return a specific course plus computed average rating and comments | |
| - `post_comment()`: create top-level comments or replies | |
| - `like_comment_main()`: increment/decrement comment like count | |
| - `like_reply_unique()`: increment/decrement reply like count | |
| - `toggle_complete()`: set lesson completion state | |
| - `rate_course()`: append a rating and return the updated average | |
| - `get_market_data()`: return synthetic OHLCV-style market data | |
| - `get_stock_pool()`: return grouped stock symbol lists | |
| - `get_real_quote()`: return live or simulated quote data for one or more symbols | |
| - `get_kline_data()`: return live or simulated historical daily K-line data | |
| - `get_portfolio()`: return current user's simulated portfolio | |
| - `execute_trade()`: execute a paper buy or sell | |
| - `reset_portfolio()`: restore paper portfolio to default starting cash | |
| - `agent_chat()`: create/load a chat session, invoke the agent, save the assistant response | |
| - `get_chat_sessions()`: return chat-session list sorted by timestamp | |
| - `get_chat_history()`: return messages for one chat session | |
| - `clear_chat_history()`: clear one session or all sessions for the current user | |
| ## 7.2 `agent_graph.py` | |
| - `AgentState`: typed graph state definition for message history | |
| - `call_model(state)`: run the LLM with the system prompt plus tools | |
| - `route_logic(state)`: send the flow either to tool execution or to `END` | |
| ### Agent graph behavior | |
| - LLM model: `deepseek-chat` | |
| - Temperature: `0` | |
| - System prompt rules: | |
| - English only | |
| - concise headings and bullets | |
| - no `**bold**` emphasis inside prose | |
| - emit `json-chart` blocks for stock analysis visuals | |
| - respond with a structured market-analysis template | |
| ## 7.3 `tools.py` | |
| - `get_realtime_quote(symbol)`: fetch latest price, change, high, low | |
| - `get_stock_news(symbol)`: fetch latest headlines | |
| - `get_historical_kline(symbol)`: fetch last 60 daily data points and return JSON string | |
| - `get_fundamental_data(symbol)`: fetch PE, PB, and ROE-style metrics | |
| - `query_knowledge_base(query)`: retrieve relevant PDF text snippets | |
| ## 7.4 `vector_store.py` | |
| - `build_vector_db(persist_directory, knowledge_base_path)`: build or load the vector store and return a retriever | |
| ### Internal behavior inside `build_vector_db()` | |
| - create empty knowledge directory if missing | |
| - return empty retriever if no PDFs exist | |
| - recursively discover PDFs | |
| - load PDFs | |
| - deduplicate by content hash | |
| - attach source metadata | |
| - split text into chunks | |
| - build or load persistent Chroma DB | |
| - incrementally add documents if new files are detected | |
| - return retriever configured with `k=5` | |
| ## 7.5 `main.py` | |
| - `start_interactive_session()`: run a CLI chat session against the LangGraph app | |
| ## 7.6 `templates/index.html` frontend functions | |
| ### Global shell | |
| - `showView(v)` | |
| ### Academy | |
| - `loadData()` | |
| - `openModule(id)` | |
| - `openShare()` | |
| - `closeShare()` | |
| - `copyLink()` | |
| - `renderComments(list)` | |
| - `replyAt(user, commentId)` | |
| - `replyToReply(user, parentCommentId)` | |
| - `cancelReply()` | |
| - `postComment()` | |
| - `setRoadmapMode(mode)` | |
| - `initRoadmap()` | |
| - `dragstarted(event, d)` | |
| - `dragged(event, d)` | |
| - `dragended(event, d)` | |
| - `renderCustomRoadmap(g, svg)` | |
| - `resetPorts()` | |
| - `openConfirm(title, desc, onOk, onCancel)` | |
| - `openNodeModal()` | |
| - `closeNodeModal()` | |
| - `addCustomNode()` | |
| - `switchAcademy(tab)` | |
| - `closeModule()` | |
| - `renderStatusBox(isDone)` | |
| - `toggleStatus(isDone)` | |
| - `sortComments(type)` | |
| - `showToast(msg)` | |
| ### Trading Lab | |
| - `loadLabData()` | |
| - `loadSectorStocks()` | |
| - `selectStock(stock)` | |
| - `initKlineChart()` | |
| - `loadKlineData(symbol, days = 60)` | |
| - `calculateTotal()` | |
| - `executeTrade(action)` | |
| - `updatePortfolioUI()` | |
| - `resetPortfolio()` | |
| - `refreshLab()` | |
| - `updateGuideUI()` | |
| - `nextGuideStep()` | |
| - `prevGuideStep()` | |
| - `setLabView(view)` | |
| ### U2CHAT | |
| - `loadAgentData()` | |
| - `loadAgentStocks()` | |
| - `addStockToChat(stock)` | |
| - `updateSelectedStocks()` | |
| - `removeStock(i)` | |
| - `sendMessage()` | |
| - `updateSendButtonState()` | |
| - `addMessageToUI(role, content, tools = [])` | |
| - `renderChart(containerId, data)` | |
| - `loadChatSessions()` | |
| - `loadChatSession(sessionId)` | |
| - `clearChat()` | |
| - `newChat()` | |
| - `handleAgentKey(e)` | |
| - `autoResize(t)` | |
| ## 7.7 UI handlers currently referenced but missing | |
| - `toggleLike(...)` | |
| - `toggleReplyLike(...)` | |
| - `changeTimeRange(...)` | |
| These missing handlers are currently important product gaps because visible UI controls already depend on them. | |
| ## 8. Current Data, Persistence, and State Boundaries | |
| ### Browser/session state | |
| - Flask session stores `user_id` | |
| ### Academy state | |
| - Module catalog is hardcoded in memory | |
| - Completion flags mutate in server memory | |
| - Ratings mutate in server memory | |
| - Comments mutate in server memory | |
| - Academy state is shared globally in the process, not persisted per user | |
| ### Trading Lab state | |
| - Portfolio is stored in a `defaultdict` | |
| - State is keyed by `user_id` | |
| - State is not persisted across server restarts | |
| ### Chat state | |
| - Visible session list and session messages are stored in `CHAT_SESSIONS` | |
| - LangGraph thread memory is stored in `checkpoints.sqlite` | |
| - These two sources of truth are not unified | |
| ### Knowledge base state | |
| - Vector DB persists in `chroma_db` | |
| - Knowledge documents live in `knowledge/` | |
| - Retriever creation currently happens at import/startup time | |
| ### Important persistence implications | |
| - Academy feels persistent only while the process is running | |
| - Lab feels persistent only while the process is running | |
| - U2CHAT appears partially persistent because LangGraph checkpoints survive, but the visible session list does not | |
| ## 9. UI Rebuild Product Requirements | |
| The UI rebuild should preserve current scope while correcting the current architecture and interaction quality. | |
| ### Preserve these product surfaces | |
| - Landing page | |
| - Public commercial website layer | |
| - Knowledge Academy | |
| - Trading Lab | |
| - U2CHAT | |
| - Lesson overlay | |
| - Share modal | |
| - Roadmap modes | |
| - Beginner guide | |
| - Chat session sidebar | |
| ### Preserve these interaction capabilities | |
| - Module browsing | |
| - Lesson detail opening | |
| - Comment/reply posting | |
| - Completion toggling | |
| - Custom roadmap editing | |
| - Stock browsing by sector | |
| - Quote and chart loading | |
| - Paper trade execution | |
| - Chat session creation and reopening | |
| - AI chart rendering in chat | |
| - clear contact and conversion entry paths once added | |
| ### Rebuild requirements | |
| - Move away from the current single-file frontend architecture | |
| - Introduce a clean design system with reusable tokens and components | |
| - Make navigation, overlays, and workspaces consistent across the three pillars | |
| - Add a real public business-site information architecture, not only an app shell | |
| - Add proper loading, empty, error, success, and disabled states | |
| - Make the app fully responsive on desktop and mobile | |
| - Add visible keyboard focus states | |
| - Reduce reliance on global mutable frontend state | |
| - Add proper deep-linking strategy for major views and modules | |
| - Preserve D3 and ECharts capabilities while improving presentation | |
| - Keep the UI minimalist, but not scope-reductive | |
| ### Commercial website requirements | |
| - Add a professional homepage that can sell the product clearly | |
| - Add a full footer with contact, social, legal, and business links | |
| - Add contact and demo-request flows | |
| - Add visible trust and credibility sections | |
| - Add public-facing about/company context | |
| - Add legal/policy/disclaimer surfaces | |
| - Add conversion-focused CTA hierarchy | |
| - Add SEO-ready page structure and metadata strategy | |
| - Add support/help and business inquiry pathways | |
| - Make the site feel commercially credible, not only visually polished | |
| ### Rebuild-specific UX requirements | |
| - The Academy should feel like a premium reading and learning workspace | |
| - The Lab should feel like a calm, trustworthy simulation workspace | |
| - U2CHAT should feel like a premium research assistant workspace | |
| - Shared visual language should be coherent across all three | |
| - The public-facing business website should feel credible enough for sales, partnerships, and commercial trust-building | |
| ## 10. Feature and Function Advancement Roadmap | |
| ## 10.1 Academy advancements | |
| - Use the existing `parent` field to model real lesson progression | |
| - Add saved user progress and user-specific completion history | |
| - Add rating submission UI and actual review summaries | |
| - Add comment likes, reply likes, and moderation tooling | |
| - Add search, category filters, difficulty filters, and completion filters | |
| - Surface lesson source, instructor, and credibility context | |
| - Add note-taking, bookmarks, highlights, and exportable study plans | |
| - Add quizzes and assessments after lessons | |
| - Add progress dashboards and learning streaks | |
| - Make custom roadmap saveable and shareable | |
| ## 10.2 Trading Lab advancements | |
| - Implement fully working chart time ranges | |
| - Render transaction history in the dashboard | |
| - Calculate live portfolio value from current quotes | |
| - Show realized and unrealized P&L separately | |
| - Add watchlists, alerts, and favorite stocks | |
| - Add order types beyond immediate buy/sell | |
| - Add slippage, fees, and tax simulation options | |
| - Add risk metrics and portfolio allocation visuals | |
| - Add contextual educational guidance during trading actions | |
| - Add saved paper accounts and multiple simulation profiles | |
| - Support richer data panels such as news, fundamentals, and peer comparison | |
| ## 10.3 U2CHAT advancements | |
| - Stream responses progressively instead of returning one final blob | |
| - Add backend-supported cancellation | |
| - Surface tool execution trace and tool outputs | |
| - Add citations and source cards for knowledge-base answers | |
| - Add structured cards for quotes, fundamentals, and charts | |
| - Add pinned conversations, search, rename, and foldering | |
| - Add suggested prompts and follow-up actions | |
| - Make recent sessions and history durable | |
| - Add beginner/expert assistant modes | |
| - Add portfolio-aware or watchlist-aware analysis once persistence exists | |
| ## 10.4 Data and platform advancements | |
| - Unify Academy, Lab, and Chat persistence in one durable store | |
| - Add proper user accounts and auth if the product goes beyond demo use | |
| - Make vector-store refresh detect modified and deleted PDFs | |
| - Move vector initialization away from blocking import-time startup where appropriate | |
| - Add analytics and product telemetry | |
| - Add a test suite for backend logic and core frontend flows | |
| - Add config separation for dev/staging/prod | |
| - Harden secret management and deployment defaults | |
| ## 10.5 Frontend architecture advancements | |
| - Break the current monolith into reusable components or modular views | |
| - Move styles and scripts into versioned static assets | |
| - Introduce design tokens and a consistent component library | |
| - Introduce cleaner state boundaries between Academy, Lab, and U2CHAT | |
| - Add proper routing and deep links | |
| - Add safer message rendering and sanitization strategy | |
| - Add better chart wrappers and reusable data cards | |
| ## 10.6 Commercial website advancements | |
| - Build a proper homepage with commercial messaging and conversion hierarchy | |
| - Add product overview, about, contact, FAQ, and pricing/demo surfaces | |
| - Add a professional footer with contact, social, legal, and support links | |
| - Add lead capture forms with CRM or email routing | |
| - Add testimonials, credibility markers, and product-proof sections | |
| - Add resource/content marketing structure for SEO and inbound acquisition | |
| - Add business-grade analytics and conversion tracking | |
| - Add finance-specific public disclaimers and risk disclosures | |
| - Add newsletter, waitlist, or demo-booking flows depending on go-to-market model | |
| - Add support/help center and business inquiry routing | |
| ## 11. Recommended Rebuild Phases | |
| ### Phase 0: Truth-preserving inventory | |
| - Freeze current scope | |
| - Preserve all current product surfaces | |
| - Map implemented, partial, latent, and broken features | |
| ### Phase 1: Design system and app shell | |
| - Rebuild the global shell, navigation, typography, surfaces, and spacing system | |
| - Rebuild both the commercial website shell and the product app shell | |
| - Rebuild page layout structure for Academy, Lab, and U2CHAT | |
| - Preserve current backend API contracts | |
| ### Phase 2: Feature completion | |
| - Finish missing handlers | |
| - Finish partial Lab panels | |
| - Finish comment likes and ratings UI | |
| - Finish deep links and route behavior | |
| - Add public commercial pages and CTA flows | |
| ### Phase 3: Persistence and intelligence | |
| - Unify persistence | |
| - Add true streaming and tool/source display | |
| - Make roadmap, chat, and paper portfolios durable | |
| ### Phase 4: Product maturity | |
| - Add richer analysis features | |
| - Add personalization | |
| - Add moderation, analytics, and operational hardening | |
| - Add business analytics, CRM integration, SEO content, and commercial operations support | |
| ## 12. Success Criteria for the Rebuild | |
| The rebuild is successful if a user can: | |
| - understand what U2INVEST is as a company/product before entering the app | |
| - understand the three product pillars immediately | |
| - move between Academy, Lab, and U2CHAT without cognitive friction | |
| - use every currently visible control without hitting dead or partial functionality | |
| - complete Academy learning flows and see trustworthy progress | |
| - use the Lab as a coherent paper-trading workspace | |
| - use U2CHAT as a believable research assistant with visible evidence and structure | |
| - find contact, social, legal, and trust information easily | |
| - submit a business inquiry, contact request, or demo request cleanly | |
| - recover state more reliably across refreshes and restarts | |
| The rebuild is especially successful if it preserves scope while making the product feel more premium, more coherent, and more maintainable than the current single-file implementation. | |
| ## 13. Highest-Priority Truths To Preserve | |
| - U2INVEST is not only an AI chat app | |
| - U2INVEST is not only an in-app product; it also needs a public commercial website layer | |
| - The product is intentionally a three-part system: learn, practice, analyze | |
| - The Academy, Lab, and U2CHAT should remain connected but distinct | |
| - The rebuild should increase clarity and quality, not reduce functionality | |
| - The current code already contains more product scope than the current UI communicates | |