# Project export: Helios This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: Cal Hacks 12.0 - Tagline: AI-Powered Conversation Knowledge Graphs - Devpost: https://devpost.com/software/helios-5i04yr - GitHub: https://github.com/yanxue06/CalHacks - Video: https://www.youtube.com/embed/m_2NIEZy6Js?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 4 GitHub contributor(s) — yan (16 commits), itang06 (5 commits), Benjamin Ching (4 commits), Roy Li (4 commits) ## Devpost submission (written by the team) ### Overview 💡 ### Inspiration Ever been in a meeting where important decisions and action items get lost in the conversation? We built Helios to automatically transform spoken discussions into visual, interactive knowledge graphs - making it easy to see relationships, track decisions, and never miss important details. 🚀 ### What it does Helios listens to your conversations through voice AI and automatically generates a live, interactive knowledge graph that: Extracts key entities (people, systems, databases, services) in real-time Identifies relationships between concepts as you speak Tracks decisions and action items automatically Organizes information hierarchically - important nodes at the top, details below 🛠️ ### How we built it Frontend: React + TypeScript + TailwindCSS for the UI React Flow for interactive graph visualization Vapi SDK for real-time voice transcription and AI conversation Socket.IO client for real-time updates Backend: Node.js + Express server Socket.IO for WebSocket communication OpenRouter API with Google's Gemini Pro for intelligent graph generation Vapi API for voice processing and transcription Custom graph service with intelligent positioning algorithms 🔊 VAPI Integration Real-Time Voice-to-Knowledge Graph Pipeline 1. Live Transcription & Conversation Tracking Captured real-time speech-to-text during team discussions Tracked full conversation history with speaker attribution Maintained conversation context throughout entire session 2. AI Assistant Integration Two-way dialogue: Users speak naturally, AI responds with clarifying questions Conversational flow management via Vapi's assistant API Dynamic conversation state handling (started, active, ended events) 3. Streaming Transcript Processing Real-time transcript updates pushed to backend via WebSocket Incremental graph building as conversation progresses Periodic graph refinement every 10 seconds during active recording 4. Multi-Modal Input Support Voice recording through Vapi Web SDK Audio file upload for transcription (supporting async workflows) Session-based recording management 5. Advanced Conversation Analysis Leveraged Vapi's conversation metadata for timestamps Speaker identification for attribution in a knowledge graph Confidence scoring from transcription quality 6. Seamless UX Integration Start/stop recording controls tied to Vapi lifecycle Visual status indicators (listening, processing, finalizing) Toast notifications synced with Vapi conversation events Clean error handling for connection issues Result: Users speak naturally about their ideas, and our AI instantly transforms messy conversations into structured, visual knowledge graphs - all powered by Vapi's robust voice infrastructure. Key Technical Achievement: We went beyond basic transcription by using Vapi as the real-time data source for an intelligent graph-building system, demonstrating Vapi's capability to power complex AI workflows, not just simple voice capture. Key Technical Features: Smart node placement algorithm that organizes by importance (top-to-bottom layout) Real-time position synchronization when users drag nodes Rate limiting and throttling to handle API constraints Collision detection to prevent overlapping nodes WebSocket-based live updates across all connected clients 🏆 Accomplishments we're proud of Real-time AI analysis - Processing conversations and updating graphs live with minimal latency Intelligent layout system - Nodes automatically organize by importance with perfect spacing Seamless voice integration - Natural conversation flows directly into visual structures Production-ready architecture - Rate limiting, error handling, and graceful fallbacks 📚 ### What we learned Robust schemas are imperative to the full-stack development process as it creates solid foundations to build off of Bring ideas. If you can think it, the tools are there to make it Stick to the MVP. Make something first, then make it better. Not the other way around 🔮 ### What's next Persistent storage - Save and reload conversation graphs Advanced AI models - Experiment with different LLMs for better entity extraction Graph analytics - Insights on conversation patterns and key topics Meeting integrations - Connect with Zoom, Teams, or Google Meet Template library - Pre-built graph structures for common meeting types 🎯 Built for CalHacks A project showcasing real-time AI, voice technology, and collaborative visualization - turning conversations into actionable insights. 📊 Tech Stack Summary ## README (from the GitHub repository) ### Tired of important decisions and action items getting lost in meeting conversations? We built **Helios** to automatically transform spoken discussions into visual, interactive **knowledge graphs**. This makes it easy to see relationships, track decisions, and ensures you **never miss an important detail** again. Screenshot 2025-12-11 at 10 18 34 PM --- [**Devpost**](https://devpost.com/software/helios-5i04yr) | [**Live Demo**](Your_Demo_Link_Here) ## Detected evidence (automated analysis) Indexed codebase: 85 recognized source files, 339 KB. - CSS (language) — detected in the code - Express (technology) — detected in the code - HTML (language) — detected in the code - JavaScript (language) — detected in the code - React (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - Google Gemini (technology) — claimed on Devpost, not found in the code - Node.js (technology) — claimed on Devpost, not found in the code - OpenAI (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (97 of 97) ``` .DS_Store backend/.gitignore backend/package.json backend/README.md backend/src/server.ts backend/src/services/graph.service.ts backend/src/services/openrouter.service.ts backend/src/services/vapi.service.ts backend/src/types/graph.types.ts backend/src/types/index.ts backend/src/types/openrouter.types.ts backend/src/types/vapi.types.ts backend/test-graph.ts backend/tsconfig.json frontend/.gitignore frontend/bun.lockb frontend/components.json frontend/eslint.config.js frontend/index.html frontend/package.json frontend/postcss.config.js frontend/public/robots.txt frontend/src/App.css frontend/src/App.tsx frontend/src/components/BottomToolbar.tsx frontend/src/components/DetailsSidebar.tsx frontend/src/components/DiagramNode.tsx frontend/src/components/StatusBanner.tsx frontend/src/components/Toolbar.tsx frontend/src/components/ui/accordion.tsx frontend/src/components/ui/alert-dialog.tsx frontend/src/components/ui/alert.tsx frontend/src/components/ui/aspect-ratio.tsx frontend/src/components/ui/avatar.tsx frontend/src/components/ui/badge.tsx frontend/src/components/ui/breadcrumb.tsx frontend/src/components/ui/button.tsx frontend/src/components/ui/calendar.tsx frontend/src/components/ui/card.tsx frontend/src/components/ui/carousel.tsx frontend/src/components/ui/chart.tsx frontend/src/components/ui/checkbox.tsx frontend/src/components/ui/collapsible.tsx frontend/src/components/ui/command.tsx frontend/src/components/ui/context-menu.tsx frontend/src/components/ui/dialog.tsx frontend/src/components/ui/drawer.tsx frontend/src/components/ui/dropdown-menu.tsx frontend/src/components/ui/form.tsx frontend/src/components/ui/hover-card.tsx frontend/src/components/ui/input-otp.tsx frontend/src/components/ui/input.tsx frontend/src/components/ui/label.tsx frontend/src/components/ui/menubar.tsx frontend/src/components/ui/navigation-menu.tsx frontend/src/components/ui/pagination.tsx frontend/src/components/ui/popover.tsx frontend/src/components/ui/progress.tsx frontend/src/components/ui/radio-group.tsx frontend/src/components/ui/resizable.tsx frontend/src/components/ui/scroll-area.tsx frontend/src/components/ui/select.tsx frontend/src/components/ui/separator.tsx frontend/src/components/ui/sheet.tsx frontend/src/components/ui/sidebar.tsx frontend/src/components/ui/skeleton.tsx frontend/src/components/ui/slider.tsx frontend/src/components/ui/sonner.tsx frontend/src/components/ui/switch.tsx frontend/src/components/ui/table.tsx frontend/src/components/ui/tabs.tsx frontend/src/components/ui/textarea.tsx frontend/src/components/ui/toast.tsx frontend/src/components/ui/toaster.tsx frontend/src/components/ui/toggle-group.tsx frontend/src/components/ui/toggle.tsx frontend/src/components/ui/tooltip.tsx frontend/src/components/ui/use-toast.ts frontend/src/hooks/use-mobile.tsx frontend/src/hooks/use-toast.ts frontend/src/index.css frontend/src/lib/utils.ts frontend/src/main.tsx frontend/src/pages/Board.tsx frontend/src/pages/Index.tsx frontend/src/pages/NotFound.tsx frontend/src/services/mockWebSocket.ts frontend/src/services/vapi.service.ts frontend/src/services/websocket.service.ts frontend/src/types/diagram.ts frontend/src/vite-env.d.ts frontend/tailwind.config.ts frontend/tsconfig.app.json frontend/tsconfig.json frontend/tsconfig.node.json frontend/vite.config.ts readme.md ``` ### Dependencies - backend/package.json: @types/cors@^2.8.17, @types/express@^4.17.21, @types/morgan@^1.9.9, @types/multer@^1.4.11, @types/node@^20.10.5, @types/socket.io@^3.0.1, @types/uuid@^10.0.0, @vapi-ai/web@^2.5.0, axios@^1.6.2, cors@^2.8.5, dotenv@^16.3.1, express@^4.21.2, helmet@^7.1.0, morgan@^1.10.0, multer@^1.4.5-lts.1, nodemon@^3.1.10, socket.io@^4.8.1, ts-node-dev@^2.0.0, typescript@^5.3.3, uuid@^13.0.0 - frontend/package.json: @eslint/js@^9.32.0, @hookform/resolvers@^3.10.0, @radix-ui/react-accordion@^1.2.11, @radix-ui/react-alert-dialog@^1.1.14, @radix-ui/react-aspect-ratio@^1.1.7, @radix-ui/react-avatar@^1.1.10, @radix-ui/react-checkbox@^1.3.2, @radix-ui/react-collapsible@^1.1.11, @radix-ui/react-context-menu@^2.2.15, @radix-ui/react-dialog@^1.1.14, @radix-ui/react-dropdown-menu@^2.1.15, @radix-ui/react-hover-card@^1.1.14, @radix-ui/react-label@^2.1.7, @radix-ui/react-menubar@^1.1.15, @radix-ui/react-navigation-menu@^1.2.13, @radix-ui/react-popover@^1.1.14, @radix-ui/react-progress@^1.1.7, @radix-ui/react-radio-group@^1.3.7, @radix-ui/react-scroll-area@^1.2.9, @radix-ui/react-select@^2.2.5, @radix-ui/react-separator@^1.1.7, @radix-ui/react-slider@^1.3.5, @radix-ui/react-slot@^1.2.3, @radix-ui/react-switch@^1.2.5, @radix-ui/react-tabs@^1.1.12, @radix-ui/react-toast@^1.2.14, @radix-ui/react-toggle@^1.1.9, @radix-ui/react-toggle-group@^1.1.10, @radix-ui/react-tooltip@^1.2.7, @tailwindcss/typography@^0.5.16, @tanstack/react-query@^5.83.0, @types/node@^22.16.5, @types/react@^18.3.23, @types/react-dom@^18.3.7, @vapi-ai/web@^2.5.0, @vitejs/plugin-react-swc@^3.11.0, autoprefixer@^10.4.21, class-variance-authority@^0.7.1, clsx@^2.1.1, cmdk@^1.1.1, date-fns@^3.6.0, embla-carousel-react@^8.6.0, eslint@^9.32.0, eslint-plugin-react-hooks@^5.2.0, eslint-plugin-react-refresh@^0.4.20, globals@^15.15.0, html-to-image@^1.11.13, input-otp@^1.4.2, lovable-tagger@^1.1.11, lucide-react@^0.462.0, next-themes@^0.3.0, postcss@^8.5.6, react@^18.3.1, react-day-picker@^8.10.1, react-dom@^18.3.1, react-hook-form@^7.61.1, react-resizable-panels@^2.1.9, react-router-dom@^6.30.1, reactflow@^11.11.4, recharts@^2.15.4, socket.io-client@^4.8.1, sonner@^1.7.4, tailwind-merge@^2.6.0, tailwindcss@^3.4.17, tailwindcss-animate@^1.0.7, typescript@^5.8.3, typescript-eslint@^8.38.0, vaul@^0.9.9, vite@^5.4.19, zod@^3.25.76 ### Recent commits (newest first) - Update README with additional image and formatting - Update readme.md - Update readme.md - Update readme.md - Revise readme.md for clarity and formatting - Update readme.md - Update readme.md - hail mary - rename to helios - tree structure + rename to helios - fixed ui - feat(db): add Prisma + Postgres transcripts storage, REST routes, and Vapi persistence - nodes into trees - feat: add dark/light mode toggle, resizable sidebar, dotted background, and improved styling - yan's lovely changes - node connections - frontend: bottom toolbar + node color/size UI\n- bottom toolbar for add/color\n- vertical handles, copy/paste, localStorage persistence\n- zoom-based grouping\n- edit dropdown size levels 1-5 (tighter scale) - Merge pull request #1 from yanxue06/ian-branch - added ai summary support - fix rate limit ## Key source files (fetched from GitHub, selected and truncated for size) ### backend/package.json ``` { "name": "calhacks-backend", "version": "1.0.0", "description": "Backend API for CalHacks project with Gemini AI integration", "main": "dist/server.js", "scripts": { "build": "tsc", "start": "node dist/server.js", "dev": "ts-node-dev --respawn --transpile-only src/server.ts", "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [ "express", "api", "calhacks", "typescript", "gemini", "ai" ], "author": "", "license": "ISC", "dependencies": { "@types/socket.io": "^3.0.1", "@types/uuid": "^10.0.0", "@vapi-ai/web": "^2.5.0", "axios": "^1.6.2", "cors": "^2.8.5", "dotenv": "^16.3.1", "express": "^4.21.2", "helmet": "^7.1.0", "morgan": "^1.10.0", "multer": "^1.4.5-lts.1", "socket.io": "^4.8.1", "uuid": "^13.0.0" }, "devDependencies": { "@types/cors": "^2.8.17", "@types/express": "^4.17.21", "@types/morgan": "^1.9.9", "@types/multer": "^1.4.11", "@types/node": "^20.10.5", "nodemon": "^3.1.10", "ts-node-dev": "^2.0.0", "typescript": "^5.3.3" }, "type": "commonjs" } ``` ### frontend/package.json ``` { "name": "vite_react_shadcn_ts", "private": true, "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", "build": "vite build", "build:dev": "vite build --mode development", "lint": "eslint .", "preview": "vite preview" }, "dependencies": { "@hookform/resolvers": "^3.10.0", "@radix-ui/react-accordion": "^1.2.11", "@radix-ui/react-alert-dialog": "^1.1.14", "@radix-ui/react-aspect-ratio": "^1.1.7", "@radix-ui/react-avatar": "^1.1.10", "@radix-ui/react-checkbox": "^1.3.2", "@radix-ui/react-collapsible": "^1.1.11", "@radix-ui/react-context-menu": "^2.2.15", "@radix-ui/react-dialog": "^1.1.14", "@radix-ui/react-dropdown-menu": "^2.1.15", "@radix-ui/react-hover-card": "^1.1.14", "@radix-ui/react-label": "^2.1.7", "@radix-ui/react-menubar": "^1.1.15", "@radix-ui/react-navigation-menu": "^1.2.13", "@radix-ui/react-popover": "^1.1.14", "@radix-ui/react-progress": "^1.1.7", "@radix-ui/react-radio-group": "^1.3.7", "@radix-ui/react-scroll-area": "^1.2.9", "@radix-ui/react-select": "^2.2.5", "@radix-ui/react-separator": "^1.1.7", "@radix-ui/react-slider": "^1.3.5", "@radix-ui/react-slot": "^1.2.3", "@radix-ui/react-switch": "^1.2.5", "@radix-ui/react-tabs": "^1.1.12", "@radix-ui/react-toast": "^1.2.14", "@radix-ui/react-toggle": "^1.1.9", "@radix-ui/react-toggle-group": "^1.1.10", "@radix-ui/react-tooltip": "^1.2.7", "@tanstack/react-query": "^5.83.0", "@vapi-ai/web": "^2.5.0", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "cmdk": "^1.1.1", "date-fns": "^3.6.0", "embla-carousel-react": "^8.6.0", "html-to-image": "^1.11.13", "input-otp": "^1.4.2", "lucide-react": "^0.462.0", "next-themes": "^0.3.0", "react": "^18.3.1", "react-day-picker": "^8.10.1", "react-dom": "^18.3.1", "react-hook-form": "^7.61.1", "react-resizable-panels": "^2.1.9", "react-router-dom": "^6.30.1", "reactflow": "^11.11.4", "recharts": "^2.15.4", "socket.io-client": "^4.8.1", "sonner": "^1.7.4", "tailwind-merge": "^2.6.0", "tailwindcss-animate": "^1.0.7", "vaul": "^0.9.9", "zod": "^3.25.76" }, "devDependencies": { "@eslint/js": "^9.32.0", "@tailwindcss/typography": "^0.5.16", "@types/node": "^22.16.5", "@types/react": "^18.3.23", "@types/react-dom": "^18.3.7", "@vitejs/plugin-react-swc": "^3.11.0", "autoprefixer": "^10.4.21", "eslint": "^9.32.0", "eslint-plugin-react-hooks": "^5.2.0", "eslint-plugin-react-refresh": "^0.4.20", "globals": "^15.15.0", "lovable-tagger": "^1.1.11", "postcss": "^8.5.6", "tailwindcss": "^3.4.17", "typescript": "^5.8.3", "typescript-eslint": "^8.38.0", "vite": "^5.4.19" } } ``` ### frontend/src/main.tsx ```typescript import { createRoot } from "react-dom/client"; import App from "./App.tsx"; import "./index.css"; createRoot(document.getElementById("root")!).render(); ``` ### frontend/src/App.tsx ```typescript import { Toaster } from "@/components/ui/toaster"; import { Toaster as Sonner } from "@/components/ui/sonner"; import { TooltipProvider } from "@/components/ui/tooltip"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { BrowserRouter, Routes, Route } from "react-router-dom"; import Board from "./pages/Board"; import NotFound from "./pages/NotFound"; const queryClient = new QueryClient(); const App = () => ( } /> } /> {/* ADD ALL CUSTOM ROUTES ABOVE THE CATCH-ALL "*" ROUTE */} } /> ); export default App; ``` ### backend/src/types/index.ts ```typescript // Export all types from a central location export * from './graph.types'; export * from './vapi.types'; export * from './openrouter.types'; ``` ### frontend/src/pages/Index.tsx ```typescript // Update this page (the content is just a fallback if you fail to update the page) const Index = () => { return (

Welcome to Your Blank App

Start building your amazing project here!

); }; export default Index; ``` ### frontend/postcss.config.js ```javascript export default { plugins: { tailwindcss: {}, autoprefixer: {}, }, }; ``` ### frontend/vite.config.ts ```typescript import { defineConfig } from "vite"; import react from "@vitejs/plugin-react-swc"; import path from "path"; import { componentTagger } from "lovable-tagger"; // https://vitejs.dev/config/ export default defineConfig(({ mode }) => ({ server: { host: "::", port: 8080, }, plugins: [react(), mode === "development" && componentTagger()].filter(Boolean), resolve: { alias: { "@": path.resolve(__dirname, "./src"), }, }, })); ``` ### frontend/eslint.config.js ```javascript import js from "@eslint/js"; import globals from "globals"; import reactHooks from "eslint-plugin-react-hooks"; import reactRefresh from "eslint-plugin-react-refresh"; import tseslint from "typescript-eslint"; export default tseslint.config( { ignores: ["dist"] }, { extends: [js.configs.recommended, ...tseslint.configs.recommended], files: ["**/*.{ts,tsx}"], languageOptions: { ecmaVersion: 2020, globals: globals.browser, }, plugins: { "react-hooks": reactHooks, "react-refresh": reactRefresh, }, rules: { ...reactHooks.configs.recommended.rules, "react-refresh/only-export-components": ["warn", { allowConstantExport: true }], "@typescript-eslint/no-unused-vars": "off", }, }, ); ``` ### frontend/index.html ```html Meeting Diagram - Live Architecture Visualization
``` [74 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]