Automated submission bundle generator for hackathon teams. Analyzes your GitHub repository and combines code-based evidence with user-provided narrative to generate professional pitch decks, comprehensive READMEs, architecture diagrams, and demo scripts in under 90 seconds.
- Docker and Docker Compose
- Git
- Google Gemini API Key (Get one here)
# Clone the repository
git clone https://github.com/ryanlau1220/HackFast
cd HackFast
# Set up environment variables
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Start the application
docker-compose up --buildAccess the application:
- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
cd backend
# Install uv if not already installed
# curl -LsSf https://astral.sh/uv/install.sh | sh
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
# Install Marp and Mermaid CLI (requires Node.js)
npm install -g @marp-team/marp-cli @mermaid-js/mermaid-cli
# Set up environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Run the backend
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000cd frontend
# Install pnpm if not already installed
# npm install -g pnpm
# Install dependencies
pnpm install
# Set up environment
cp .env.example .env
# Run the frontend
pnpm run dev# Backend tests (using uv)
cd backend
source .venv/bin/activate
uv run pytest tests/ -v
# Test with a sample repository
# 1. Open http://localhost:5173
# 2. Enter a GitHub repository URL
# 3. Complete the 4-question interview
# 4. Review and confirm detected information
# 5. Download your generated bundle!- Automated Repository Analysis: Detects tech stack, dependencies, API routes, and environment variables
- Smart Interview: 4 targeted questions to capture your project narrative
- Verification Dashboard: Review and edit detected information before generation
- Professional Artifacts:
- Pitch deck (PDF) with modern dark theme
- Comprehensive README with copy-paste setup instructions
- Architecture diagrams (Mermaid)
- Demo script
- Fast Generation: Complete bundle in under 90 seconds
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ URL Input │→ │ Interview │→ │ Verification │ │
│ │ Component │ │ Form (4Q) │ │ Dashboard │ │
│ └──────────────┘ └──────────────┘ └─────────────────┘ │
│ │ │ │ │
└─────────┼──────────────────┼────────────────────┼───────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ FASTAPI BACKEND │
│ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ RepoAuditor │ │ Narrative │ │ Export │ │
│ │ (Clone+Scan) │→ │ Engine (LLM) │→ │ Engine │ │
│ └──────────────┘ └──────────────┘ └─────────────────┘ │
│ │ │ │ │
│ Evidence Manifest Structured Content Final Artifacts │
└─────────────────────────────────────────────────────────────┘
- Framework: FastAPI (Python 3.11+)
- Package Manager: uv (fast Python package installer)
- LLM: Google Gemini 2.5 Flash
- Repository Analysis: GitPython for cloning, regex-based scanning
- Artifact Generation:
- Marp CLI for slide rendering (PDF)
- Mermaid CLI for architecture diagrams (PNG)
- Testing: pytest, pytest-asyncio
- Framework: React with Vite
- Package Manager: pnpm (fast, disk space efficient)
- Styling: Tailwind CSS
- State Management: React hooks (useState)
- API Client: Fetch/Axios
- Containerization: Docker + docker-compose
- Deployment: Nginx reverse proxy (production)
hackfast/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI app entry point
│ │ ├── config.py # Environment config
│ │ ├── models.py # Pydantic models
│ │ ├── core/ # Business logic modules
│ │ │ ├── repo_auditor.py # Repository analysis
│ │ │ ├── narrative_engine.py # LLM orchestration
│ │ │ └── export_engine.py # Artifact generation
│ │ ├── services/ # Supporting services
│ │ ├── api/ # API endpoints
│ │ ├── templates/ # Marp themes
│ │ └── prompts/ # LLM system prompts
│ ├── tests/ # Test suite
│ ├── requirements.txt
│ ├── Dockerfile
│ └── .env.example
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Main app component
│ │ ├── components/ # UI components
│ │ └── services/ # API client
│ ├── package.json
│ └── .env.example
├── docker-compose.yml
└── README.md
Required environment variables (see .env.example):
GEMINI_API_KEY: Google Gemini API key (required)MAX_REPO_SIZE_MB: Maximum repository size (default: 100)CLONE_TIMEOUT_SECONDS: Git clone timeout (default: 45)LLM_TEMPERATURE: LLM temperature for generation (default: 0.3)
"GEMINI_API_KEY not configured"
- Make sure you've set the API key in backend/.env
"Git clone failed"
- Check repository URL is valid and public
- Ensure git is installed and accessible
"Marp rendering failed"
- Install Marp CLI:
npm install -g @marp-team/marp-cli
"Mermaid rendering failed"
- Install Mermaid CLI:
npm install -g @mermaid-js/mermaid-cli
"Network Error"
- Ensure backend is running on port 8000
- Check VITE_API_URL in frontend/.env
"Cannot connect to backend"
- Verify backend health: http://localhost:8000/api/health
For production deployment:
- Update CORS settings in
backend/app/main.py - Set proper environment variables
- Use production-ready web server (e.g., Nginx)
- Enable HTTPS
- Set up rate limiting
- Configure proper logging
- Language Support: Currently optimized for Node.js and Python projects
- Private Repos: Only supports public GitHub repos (no OAuth in MVP)
- Monorepos: May struggle with complex monorepo structures
- Business Context: Requires human input for problem/market narrative
- Support for GitLab, Bitbucket
- Multi-language support (Java, C#, Go, Rust)
- Custom branding (team logo on slides)
- Video demo generation
- Rubric alignment (hackathon-specific optimization)
- Team collaboration features