How mvpalheta/ragfolio works
Project type and purpose
• RAGfolio is a full-stack, cloud-native investment analysis application.
• Purpose: Provide a three-stream (fundamental, momentum, sentiment) RAG-powered analysis on stocks, aggregate results, and present recommendations via API and web UI.
File structure
• Top-level directories:
• app/ (FastAPI backend)
• front/ (Next.js + TailwindCSS frontend)
• ingestion/ (data ingestion scripts for SEC filings & news)
• utils/ (helper scripts)
• app/ substructure:
• analyzers/ implement three parallel RAG streams (inherit from base_analyzer)
• config/ holds queries, settings, ticker mappings
• models/ Pydantic schemas for API & analysis results
• prompts/ LLM prompt templates for each analysis task
• routers/ FastAPI endpoints (agent, llm, search)
• services/ business logic: orchestration (agent_service), vector DB client (retriever), embedder, LLM interface, prompt manager, ticker extractor
• utils/ decorators for logging/error handling
• main.py: FastAPI entry point
• Docker-related: Dockerfile under app/, Dockerfile under front/, docker-compose.yml
• ingestion/: Python scripts to populate Qdrant from SEC API and yfinance news
README for insights
• Three-stream hybrid search architecture: dense (Sentence-Transformers), sparse (BM25), late interaction (ColBERTv2) via Qdrant
• Parallel workflow orchestration inspired by Anthropic Agents
• External dependencies: Qdrant vector DB, Groq API (LLM), Docker Compose
a. Main components
• Client (Browser / CURL / Postman)
• Frontend (Next.js app, port 3000)
• Backend API (FastAPI, port 8000)
• Orchestrator (agent_service)
• Analyzer streams (fundamental_analyzer, momentum_analyzer, sentiment_analyzer)
• Document Retriever (Qdrant client)
• Vector Store (Qdrant)
• Embedding service (embedder)
• LLM service (Groq / OpenAI / LLM API)
• Ingestion pipeline (SEC & news ingestion scripts)
• Configuration & Prompts (queries.yaml, .md prompt templates)
• Data stores (vector DB, optional file storage)
b. Relationships & interactions
1. User → Frontend → Backend API (POST /agent)
2. API routers delegate to Agent Service
3. Agent Service in parallel:
• For each stream, build query via Prompt Manager
• Embed query via Embedder → send to Document Retriever → Qdrant → raw docs
• Pass docs + prompt to LLM Service → analysis result
4. Collect three stream results → Final Aggregation prompt → LLM Service → Final recommendation
5. Return JSON to client
6. Ingestion scripts run offline or on schedule: fetch documents → preprocess → embed via embedder → upsert to Qdrant
c. Architectural patterns & design principles
• Workflow parallelization: streams run concurrently
• Layered separation: routers → services → analyzers/model → data store
• Single responsibility: each service class handles one integration
• Config-driven: queries and prompts externalized
• Containerized microservices: separate Docker contexts for front/back
d. Key technologies
• Frontend: Next.js, TailwindCSS, React
• Backend: FastAPI, Pydantic
• Vector DB: Qdrant
• Embeddings: sentence-transformers
• Retrieval: BM25, ColBERTv2
• LLM API: Groq or similar
• Orchestration: Python asyncio parallel tasks
• Ingestion: custom Python scripts