Back to Blog
🏦

Achi AI Stock Assistant

Published on·5 min read
Portfolio

🏢 Project Overview

This project is an intelligent full-stack investment assistant customized for personal stock and cryptocurrency portfolios. Built on a Fastify REST API and React SPA architecture, the system leverages automated cron jobs to fetch daily market K-lines, global macroeconomic indicators, and financial news. It processes this data through a multi-tier Google Gemini API architecture for sophisticated decision-making, enqueuing buy/hold/watch/caution signals, quantitative scores, and portfolio health reports directly to LINE, alongside responsive RWD web snapshots (daily/weekly reports).

  • Project Type: AI-Driven Quant & Portfolio Management Full-Stack System
  • Core Tech Stack: Node.js, Fastify, TypeScript, React, Vite, Supabase (PostgreSQL), Gemini API, GitHub Actions, PWA

🛑 Challenges & Situation

  1. Multi-Source Heterogeneous Data Integration: Interfacing with multiple distinct APIs—Yahoo Finance (K-lines/fundamentals), FRED (macro), CNN (Fear & Greed), Finnhub, and GNews (news)—required managing concurrent asynchronous streams while strictly bypassing rate limiters (429 errors) and 418 anti-scraping blocks.
  2. LLM Stability & Cost Management: As the asset watchlist scaled, standard LLM requests frequently hit token limitations (truncating JSON responses) or triggered rate limits and 503 service exceptions under clustered requests.
  3. Mitigating AI Hallucinations & Indicators Contradiction: Raw LLM engines often yield trading logic that directly contradicts quantitative realities (e.g., suggesting a "strong buy" on an asset with an extremely overbought RSI and death crosses). The system needed an engineering barrier to force the AI to respect mathematical constraints.

🛠️ Technical Actions

1. Multi-Tier LLM Architecture & Automatic Fallback Pipeline

  • Tiered Gemini Strategy: Built a customized generateWithFallback() wrapper, mapping varied prompt complexities to the most optimal models: L1 gemini-3.5-flash for signal and sentiment logic; L2 gemma-4-31b-it for in-depth earnings analysis; and L3 gemini-2.5-flash-lite for bulk headline translation into Traditional Chinese.
  • Intelligent Quota Fallback: When L1 or L3 triggers a 429, Resource Exhausted, or 503 error, the system applies the exact system instructions and automatically downgrades to L2 to retry, suppressing chain-of-thought outputs and maintaining schedule execution.
  • Batch Signal Ingestion: Dispatched valid tickers in batches of BATCH_SIZE = 12 with active post-merge de-duplication, eradicating JSON response truncation.

2. Rule-Based Quant & AI Hybrid Framework

  • Technical Contradiction Detector: Pre-scanned asset historical K-lines for conflicting metrics (e.g., RSI > 65 with a moving average death cross) prior to prompt construction. The system dynamically injects an [⚠️ Technical Contradiction] warning block into the prompt, forcing Gemini to explain the divergence in its reasoning text.
  • 4-Dimensional Investment Scoring: Engineered a pure-function quantitative engine measuring Technicals (30%), Fundamentals (30%), News Sentiment (20%), and Macro Environments (20%). It dynamically filters out fundamentals for Crypto assets and re-normalizes the score to a 100-point scale, anchoring the AI's signal generation.
  • Portfolio Concentration Penalty Model: Designed mathematical exposure evaluations that flag risk when a single GICS sector exceeds 40% or an individual asset outweighs 20% of the entire portfolio, triggering an L2 prompt to append an AI executive diagnostic comment.

3. Advanced Macro & Long-Cycle Analytics Engine

  • 75-Year Pearson Correlation Matching: Aggregated S&P 500 (^GSPC) 75-year historical daily candles into weekly close periods. Utilizing a rolling 260-week window with z-score normalization and Pearson correlation calculations, it extracts the Top 3 historical analogues. If the correlation coefficient falls under 0.35, the system falls back gracefully to a pure macro context diagnostic, preventing forced analogies.
  • Three-Dimensional Market Regime Logic: Programmed real-time algorithms to track the Rate Cycle (hiking/peak/cutting), Liquidity Regime (tightening/neutral/easing), and Credit Cycle (expansion/slowdown/recession) from FRED datasets, injecting structured macro dimensions directly into weekly LINE push payloads.

4. Automated Operations & API Guarding

  • Asymmetric Build Pipelines: Offloaded heavy UI Vite compilations to GitHub Actions Runners due to memory limits on the production AWS EC2 (t4g.micro). Compiled dist/ and dist-frontend/ directories are securely shipped via SCP before trigger-restarting the server natively under PM2.
  • Scoped Webhook Routing: Encapsulated the LINE Webhook route inside a Fastify scoped plugin instance, constraining the raw string Content Type Parser to /webhook/line only, isolating it from global JSON body parsing setups.

5. Dual-Track Responsive UI & PWA Architecture

  • Dual-Track JSX Breaking Layouts: Architected all 6 core dashboard pages (Portfolio, Watchlist, Signals, Performance, Health, Reports) with concurrent desktop (hidden lg:block) and mobile (lg:hidden) components inside the single DOM tree, optimizing screen readability across viewports.
  • Progressive Web App Implementation: Configured vite-plugin-pwa with a Cache-First strategy for static assets and a strict NetworkOnly policy for /api/* segments, enabling standalone full-screen launches and seamless iOS/Android home-screen pinning without caching stale market metrics.

📈 Results & Impact

  • Autonomous Investment Pipelines: The background crons operate with extreme stability, blasting out short LINE summaries bound with automated, unauthenticated UUID links (60-day TTL), drastically minimizing free LINE push quota drains.
  • Closed-Loop Performance Backtesting: Deployed an automated tracking pipeline that evaluates real-world returns at 7-day, 30-day, and 90-day post-signal intervals, calculating win ratios and measuring Alpha gains over SPY to provide transparent strategy audit tracks.
  • High Availability on Zero-Cost API Ingestions: Coupled with sequential processing (2-second delays for FRED loops to prevent 429 errors) and stale-check caching (weekly fundamental updates), the system maintains a 100% cron success rate despite working under free-tier API quotas.