BeePrepared

system architecture design
good sleeps

Inspiration

As computer science students, we are constantly flooded with slides and lecture recordings. Working through all this content manually would waste hours of our lives. This realization led us to create BeePrepared. The name combines the bee theme of HackHive with our mission: helping students avoid time-wasting tasks and prepare smartly for exams.

BeePrepared takes slides, recordings (both audio and video), and text documents as input, then outputs quizzes, flashcards, study notes, and mock final exam PDFs. As upper-year computer science students at the University of Toronto, we know firsthand how thorough and overwhelming course content can become.

The hackathon theme focused on AI, and we saw an opportunity to build something truly agentic with a smooth user experience and compelling visual design. We wanted to demonstrate that AI agents could work together seamlessly while keeping users informed every step of the way.

What it does

BeePrepared transforms passive learning materials into active study tools. Students upload lecture recordings, presentation slides, or documents in any common format. Our AI pipeline processes this content through specialized agents, each handling a specific task: file validation, transcription, concept extraction, and artifact generation.

The system generates four types of study materials simultaneously: comprehensive notes with clear organization, flashcards optimized for active recall, practice exams with difficulty tiers, and audio study guides for learning on the go. A visual pipeline on the dashboard shows exactly which processing stage is active, with real-time progress updates every two seconds.

The entire workflow completes in under three minutes, regardless of lecture length. Students can then preview, download, or regenerate materials with different difficulty settings. All artifacts are stored in a searchable library for future reference.

How we built it

We began with a four-hour architecture planning session using Excalidraw. This upfront design work clarified how the frontend and backend would connect, which data would flow between components, and how we would handle real-time updates. The architecture diagram became our single source of truth throughout development.

For the frontend, we applied senior development principles focused on intentional design and motion storytelling. The landing page features GSAP animations that guide users through our value proposition. Honey drip effects and bee flight paths reinforce the theme while maintaining professional polish.

The dashboard interface follows modern design patterns with glassmorphism effects, smooth transitions, and micro-interactions on every element. We implemented a collapsible sidebar that persists across all pages, ensuring consistent navigation without cluttering the workspace.

The flow canvas leverages React Flow for the pipeline visualization. We adapted node-based workflow concepts from platforms like Eduflow but refined the design for 21st century aesthetics. Custom bee-themed nodes display real-time status updates with animated progress indicators. The color palette uses honey gold and amber tones throughout for visual cohesion.

Backend development involved extensive evaluation of transcription services. We tested Azure Speech-to-Text against Google Vertex AI, comparing accuracy, speed, language support, and pricing. Azure Speech emerged as the better choice for our use case due to superior handling of technical terminology and academic content.

The file processing pipeline supports six input formats: audio (MP3, WAV, M4A), video (MP4, MOV, AVI), and documents (PDF, PPTX, DOCX, MD, TXT). Each format required different extraction logic, from PyMuPDF for PDFs to FFmpeg for video audio extraction.

We chose Supabase for our database because it provides PostgreSQL with built-in authentication, real-time subscriptions, and Row Level Security policies. Cloudflare R2 handles file storage with zero egress fees, which matters for downloads. FastAPI powers the backend with async request handling and automatic API documentation.

Challenges we ran into

The backend proved more complex than anticipated. We spent significant time evaluating AI service providers, comparing Azure Speech-to-Text, Google Vertex AI, and OpenAI Whisper. Each service had different strengths: Azure excelled at technical terminology, Whisper supported more languages, and Vertex AI offered better pricing for long files. We eventually chose Azure for accuracy despite higher costs.

Alex led frontend development but took on the backend transcription pipeline as his first major backend task. Implementing extraction logic for six different file formats while handling edge cases like corrupted files, unsupported codecs, and oversized uploads required learning new libraries and debugging techniques. This work consumed the entire first day of the hackathon.

File format quirks presented unexpected challenges. Some PDFs used scanned images rather than embedded text, requiring OCR fallback logic we had not planned for. PowerPoint files sometimes stored speaker notes separately from slide content, necessitating careful extraction to capture everything. Video files with multiple audio tracks needed logic to select the correct one.

Frontend development faced its own obstacles. React Flow's default styling did not match our bee theme, requiring extensive CSS customization. GSAP animations needed careful timing to feel natural rather than distracting. The polling architecture required precise state management to prevent memory leaks and unnecessary re-renders.

We also struggled with time management. Both team members worked through the night, subsisting on minimal sleep in our eight-chair setup. Balancing feature development against the hackathon deadline meant constantly prioritizing what would have the most impact for judges.

Accomplishments that we're proud of

We are proud of Vishnu for implementing the complete backend pipeline from file upload through artifact generation. He built the FastAPI endpoints, integrated Azure Speech and Google Gemini APIs, designed the database schema, configured Cloudflare R2 storage, and deployed everything to Railway. The system handles concurrent uploads, processes files in parallel, and provides real-time status updates without a single point of failure.

Alex deserves recognition for tackling backend transcription despite being the frontend lead. He learned PyMuPDF, python-pptx, and FFmpeg from scratch to build extraction logic for six file formats. The code handles edge cases gracefully and provides detailed error messages when files cannot be processed.

The frontend achieves a level of polish rarely seen in hackathon projects. Every page transition uses Framer Motion animations. GSAP powers the honey drip effects and bee flight paths on the landing page. The dashboard feels responsive and intentional, with hover states, loading skeletons, and empty states all carefully designed. React Flow visualizes the processing pipeline in real time with custom bee-themed nodes.

We successfully integrated real-time updates using HTTP polling rather than WebSockets. This architectural decision simplified deployment and improved reliability while still providing two-second update intervals that feel instantaneous to users.

Most importantly, we built a complete product rather than just a prototype. Users can actually upload files, watch them process, and download generated study materials. The entire pipeline works end to end.

What we learned

Architecture planning before coding proves invaluable. Our four-hour Excalidraw session prevented countless hours of rework and confusion. Having a shared diagram that shows data flow, API contracts, and component responsibilities kept both team members aligned even while working on different parts of the codebase.

This principle applies equally to frontend work. Future projects should begin with Figma mockups or similar design tools. Defining layouts, interactions, and visual hierarchy before writing components would accelerate development and improve consistency.

Backend evaluation requires structured comparison. We learned to create matrices comparing services across relevant dimensions: accuracy, speed, language support, pricing, ease of integration, and documentation quality. This approach led to better decisions than gut feeling or brand recognition.

Time management in hackathons demands ruthless prioritization. We spent too long perfecting animations that few judges would notice while delaying critical features like error handling. Future hackathons should focus on core functionality first, adding polish only if time permits.

Dividing work by expertise does not mean avoiding other areas entirely. Alex learning backend concepts strengthened the overall system because he understood constraints and possibilities when building the frontend. Cross-functional knowledge improves team collaboration.

What's next for BeePrepared

BeePrepared has potential beyond the hackathon. The immediate next step involves Docker containerization for easier deployment and distribution. Packaging the application as a desktop app would eliminate the need for users to manage cloud credentials or server infrastructure.

Canvas LMS integration represents a major opportunity. Students could connect their Canvas accounts and have BeePrepared automatically process new lecture materials as professors upload them. This workflow would eliminate manual file downloading and uploading, making study material generation completely automatic.

The platform could expand to support collaborative features. Study groups could share artifact libraries, combining materials from multiple lectures into comprehensive exam preparation resources. Instructors could use the system to generate practice problems and review materials for their courses.

Machine learning could personalize difficulty levels based on student performance. The system would track which flashcards users struggle with and generate additional practice problems targeting weak areas. Adaptive learning paths would emerge from usage patterns.

Additional AI capabilities could enhance the core product. Conversational interfaces would let students ask questions about lecture content and receive answers grounded in the extracted knowledge graph. Multi-modal inputs combining lecture videos with textbook chapters would create more comprehensive study materials.

Long term, BeePrepared could become a platform that fundamentally changes how students engage with educational content. Rather than passively consuming hours of lectures, students would spend their time on active learning through quizzes, flashcards, and practice exams tailored to their needs. The vision is simple: let AI handle content organization so students can focus on actual learning.