Build a Full-Stack GenAI Project in 4 Hours (FastAPI, React, Supabase)

Key Concepts

• Full-Stack GenAI Architecture: Building an end-to-end application with a React/TypeScript frontend, FastAPI backend, and PostgreSQL database.
• RAG (Retrieval-Augmented Generation): A pipeline that grounds AI responses in specific documents (SEC filings) to prevent hallucinations.
• Agentic Workflow: Using AI coding agents (Cursor, Claude, GPT-4o) to build, debug, and manage the codebase through incremental prompts.
• Hybrid Search: Combining semantic vector search (using pgvector) with keyword-based full-text search for better retrieval accuracy.
• Document Ingestion Pipeline: Using Docling to convert messy HTML/HTM files into structured Markdown and JSON for database storage.
• Infrastructure: Using Supabase for database/auth and Railway for deployment.
• Guardrails: Implementing validation steps to ensure AI answers are cited and grounded in retrieved chunks.

---

1. Project Overview & Client Brief

The project, "Driftwood Capital," is a document co-pilot for investment analysts. Analysts spend significant time manually reviewing SEC filings (10-Ks, 10-Qs). The goal is to build a tool where they can ask questions in plain English and receive sourced, trustworthy answers, saving them at least three hours per week.

• Key Requirements: Browser-based access, user authentication, chat history, and strict source citation to prevent hallucinations.
• Why Custom Build? Off-the-shelf tools (ChatGPT/Copilot) lack the necessary privacy compliance, enterprise security, and the ability to handle large, specialized document corpora without losing context.

2. Architecture & Tech Stack

The application follows a mono-repo structure:

• Frontend: React, TypeScript, Vite, Tailwind CSS, and shadcn/ui for components.
• Backend: Python, FastAPI, and Pydantic for data validation.
• Database: Supabase (PostgreSQL) with pgvector for vector embeddings.
• Deployment: Railway (using Docker files for both frontend and backend).
• AI Orchestration: pydantic-ai for agentic tool calling and structured output.

3. Step-by-Step Implementation Process

1. Setup & Data Ingestion: Downloaded 5 years of SEC filings for major tickers (Apple, Nvidia, etc.). Used Docling to convert HTM files to Markdown.
2. Database Modeling: Used SQLAlchemy and Alembic to define and migrate database schemas (Users, Documents, Chunks, Chats, Messages, Citations).
3. Authentication: Implemented Supabase Auth with email-based login, disabling public sign-ups to keep the tool internal.
4. Retrieval Pipeline: Implemented a hybrid search combining semantic embeddings and full-text search, fused via Reciprocal Rank Fusion (RRF).
5. Agentic Logic: Built an agent that can "reason" over tools—searching, reading chunks, and reading surrounding chunks for context—before synthesizing a grounded answer.
6. Deployment: Configured Docker files and Caddy for the frontend, and used the Railway CLI/MCP to deploy the services.

4. Key Technical Challenges & Solutions

• Table Extraction: Initial Docling exports failed to capture complex financial tables correctly. Solution: Created a custom HTML table extractor to convert tables into structured JSON/Markdown.
• Hallucination Prevention: Implemented a "Grounding Validator" that checks the AI's final answer against the retrieved chunks to ensure every claim is cited.
• Dependency Management: Used uv for Python dependency management, enforcing strict versioning and excluding packages younger than 7 days to mitigate supply chain attacks.
• Deployment Complexity: Managed environment variables and cross-service communication (Frontend to Backend API) using Railway’s secret management.

5. Notable Quotes & Perspectives

• "The better the initial prep work, the faster you can go with AI agents."
• "If you don't have intermediate review points and decide what 'good' looks like, it's going to get messy."
• "This is engineering in the real world... sometimes I make mistakes, I get stuck, I have to debug."
• "You cannot 'vibe code' your way to a solution like this... you need to understand the stack from first principles."

6. Synthesis & Conclusion

The project demonstrates that building a production-grade GenAI application requires more than just a prompt; it requires a robust data pipeline, a secure backend, and a thoughtful retrieval strategy. The "agentic" approach—where the AI can loop through tools to gather more context—is superior to naive RAG for complex analytical tasks. The main takeaway is that while AI agents drastically accelerate development, the engineer must remain the "architect" who validates the logic, manages the infrastructure, and ensures the system is reliable enough for professional use.