SmartFolio - AI-Powered Portfolio Generator

Transform your professional data into stunning portfolios with personalized coaching insights

A full-stack application that generates professional portfolios by aggregating data from multiple sources including LinkedIn, resumes, GitHub repositories, Codeforces, and LeetCode profiles. Leverages AI to create polished content while maintaining ethical data usage practices.

Features

Portfolio Generation

AI Content Generation - Professional summaries, project highlights, and skill assessments using Google Gemini
Multi-Source Aggregation - Combines LinkedIn, Resume, GitHub, Codeforces, and LeetCode data
Code Quality Analysis - Analyzes GitHub repositories for complexity, documentation, and best practices
Public/Private Output - Public portfolio JSON + private coaching insights

AI-Powered Refinement

Intelligent Refinement - AI-assisted portfolio editing with natural language instructions
Version Management - Track all changes with draft/committed states
Confirm/Revert Workflow - Review changes before committing
Version History - Complete audit trail of all modifications

Private Coaching Insights

Personalized Feedback - Strengths, areas for improvement, and recommendations
Career Guidance - Next steps and skill development paths
Beautiful UI - Color-coded sections with intuitive navigation

Modern Frontend

Responsive Design - Works seamlessly on desktop, tablet, and mobile
Smooth Animations - Framer Motion animations and Lenis smooth scrolling
Dynamic Loading - Rotating messages with time estimates during generation
Interactive UI - Easy-to-use forms with real-time validation

Tech Stack

Backend

FastAPI (0.115.6) - Modern async web framework
Uvicorn (0.34.0) - ASGI server
SQLAlchemy (2.0.36+) - Async ORM with PostgreSQL/SQLite support
Alembic (1.13.1) - Database migrations
Pydantic - Data validation and serialization
Google Gemini (0.7.2) - AI content generation
httpx (0.28.1) - Async HTTP client
pdfplumber (0.11.4) - PDF text extraction
python-docx (1.1.2) - DOCX text extraction

Frontend

React (19.1.1) - UI library with latest features
Vite (7.1.7) - Lightning-fast build tool and dev server
React Router DOM (7.9.3) - Client-side routing
Tailwind CSS (4.1.14) - Utility-first CSS framework
Framer Motion (12.23.22) - Production-ready animation library
Lenis (1.3.11) - Smooth scrolling library
Axios (1.13.5) - HTTP client for API calls
Lucide React (0.545.0) - Beautiful icon library

External Services

GitHub API - Repository metadata and analysis
Codeforces API - Competitive programming statistics
LeetCode GraphQL - Problem-solving statistics

Project Structure

DevHeat/
├── app/                                     # Backend application
│   ├── main.py                              # FastAPI app with lifecycle events
│   ├── config.py                            # Configuration (API keys, constants)
│   ├── database.py                          # Database session management
│   ├── routers/
│   │   ├── linkedin_router.py               # LinkedIn profile upload
│   │   ├── resume_router.py                 # Resume upload
│   │   ├── codeforces_router.py             # Codeforces API integration
│   │   ├── github_router.py                 # GitHub analyzer
│   │   ├── leetcode_router.py               # LeetCode GraphQL stats
│   │   ├── portfolio_router.py              # Slug generation
│   │   ├── portfolio_generation_router.py   # Main orchestrator
│   │   ├── portfolio_retrieval_router.py    # GET endpoints
│   │   └── portfolio_editing_router.py      # PATCH/POST endpoints
│   ├── services/
│   │   ├── github_service.py                # GitHub API logic
│   │   ├── leetcode_service.py              # LeetCode GraphQL logic
│   │   ├── ai_service.py                    # Gemini API integration
│   │   ├── code_quality_service.py          # Heuristic analysis
│   │   └── portfolio_builder_service.py     # JSON construction
│   ├── models/
│   │   ├── responses.py                     # Pydantic response models
│   │   ├── database.py                      # SQLAlchemy ORM models
│   │   ├── schemas.py                       # DB Pydantic schemas
│   │   └── portfolio_schemas.py             # Portfolio request/response
│   └── utils/
│       ├── validators.py                    # File validation
│       ├── file_parser.py                   # Text extraction
│       └── slug.py                          # Slug generation
│
├── frontend/                                # React frontend application
│   ├── src/
│   │   ├── components/
│   │   │   ├── navbar.jsx                   # Navigation bar with SmartFolio branding
│   │   │   ├── footer.jsx                   # Footer with links and newsletter
│   │   │   └── lenis-scroll.jsx             # Smooth scroll wrapper
│   │   ├── pages/
│   │   │   ├── LandingPage.jsx              # Home page with features showcase
│   │   │   ├── GeneratePortfolio.jsx        # Portfolio generation form
│   │   │   ├── RefinePortfolio.jsx          # Refinement UI with coaching tab
│   │   │   └── ViewPortfolio.jsx            # Public portfolio display
│   │   ├── services/
│   │   │   ├── api.js                       # Axios instance configuration
│   │   │   └── portfolioService.js          # API methods for portfolio operations
│   │   ├── App.jsx                          # Main app with routing
│   │   └── main.jsx                         # Entry point
│   ├── public/
│   │   └── favicon.png                      # Favicon
│   ├── index.html                           # HTML template
│   ├── package.json                         # Frontend dependencies
│   ├── vite.config.js                       # Vite configuration
│   └── tailwind.config.js                   # Tailwind CSS configuration
│
├── alembic/                                 # Database migrations
│   ├── versions/
│   │   └── 001_initial_schema.py
│   ├── env.py
│   └── script.py.mako
│
├── .env                                     # Environment variables (create this)
├── .gitignore                               # Git ignore patterns
├── alembic.ini                              # Alembic configuration
├── requirements.txt                         # Python dependencies
├── portfolio.db                             # SQLite database (auto-created)
└── README.md                                # This file

Setup Instructions

Prerequisites

Python 3.8+
Node.js 18+ and npm
Git
GitHub Personal Access Token
Google Gemini API Key

1. Clone Repository

git clone https://github.com/yourusername/DevHeat.git
cd DevHeat

2. Backend Setup

2.1 Create Virtual Environment

# Windows
python -m venv venv
venv\Scripts\activate

# Mac/Linux
python3 -m venv venv
source venv/bin/activate

2.2 Install Backend Dependencies

pip install -r requirements.txt

2.3 Configure Environment Variables

Create a .env file in the project root:

# GitHub API Token (for repository analysis)
GITHUB_TOKEN=your_github_personal_access_token_here

# Google Gemini API Key (for AI content generation)
GEMINI_API_KEY=your_gemini_api_key_here

# Database URL (SQLite for development, PostgreSQL for production)
DATABASE_URL=sqlite+aiosqlite:///./portfolio.db

# Optional: Override default host/port
# HOST=0.0.0.0
# PORT=8000

To get a GitHub token:

Go to https://github.com/settings/tokens
Click "Generate new token (classic)"
Select public_repo scope
Copy and paste into .env

To get a Gemini API key:

Go to https://aistudio.google.com/app/apikey
Click "Create API key"
Copy and paste into .env

2.4 Run Database Migrations

alembic upgrade head

2.5 Start Backend Server

uvicorn app.main:app --reload

Backend will be available at: http://localhost:8000

3. Frontend Setup

3.1 Navigate to Frontend Directory

cd frontend

3.2 Install Frontend Dependencies

npm install

3.3 Configure Frontend Environment (Optional)

Create frontend/.env file if you need to override the API URL:

VITE_API_URL=http://localhost:8000

3.4 Start Frontend Development Server

npm run dev

Frontend will be available at: http://localhost:5173 (or the port Vite assigns)

4. Access the Application

Frontend: http://localhost:5173
API Documentation: http://localhost:8000/docs
API ReDoc: http://localhost:8000/redoc

User Workflow

1. Landing Page

Visit the home page to learn about SmartFolio
Click "Generate Portfolio" to start

2. Generate Portfolio

Fill in your basic information (name, portfolio focus)
Upload documents (LinkedIn PDF, Resume)
Add GitHub repository URLs (up to 5)
Enter competitive programming usernames (Codeforces, LeetCode)
Click "Generate Portfolio with AI"
Watch dynamic loading messages (30-60 seconds)

3. Refine Portfolio

View your AI-generated portfolio content
Switch to "Private Coaching" tab to see personalized insights:
- Overall Assessment
- Strengths
- Areas for Improvement
- Recommendations
- Next Steps
Use AI refinement to improve specific sections
Review and confirm changes
View version history and revert if needed

4. View Public Portfolio

Click "View Public Portfolio" to see the final result
Share the portfolio URL with recruiters
All data is beautifully presented with:
- Professional summary
- Work experience
- Projects with technologies and highlights
- Skills and achievements
- GitHub projects
- Competitive programming stats
- Contact information

API Documentation

Base URL

http://localhost:8000

Authentication

Currently no authentication required for public endpoints. Private coaching endpoint should be secured in production.

Health Check

GET /
GET /health

Returns API status and version information.

Portfolio Generation

Generate Portfolio

POST /portfolio/generate

Request (multipart/form-data):

Field	Type	Required	Description
name	string	Yes	Full name
portfolio_focus	string	No	Focus area: `general`, `fullstack`, `backend`, `ml`, `competitive`
linkedin_file	file	No	LinkedIn PDF export
resume_file	file	No	Resume PDF/DOCX
github_repos	JSON array	No	GitHub repository URLs (max 5)
codeforces_username	string	No	Codeforces handle
leetcode_username	string	No	LeetCode username

Example:

curl -X POST "http://localhost:8000/portfolio/generate" \
  -F "name=John Doe" \
  -F "portfolio_focus=fullstack" \
  -F "linkedin_file=@linkedin.pdf" \
  -F "resume_file=@resume.pdf" \
  -F 'github_repos=["https://github.com/user/repo1"]' \
  -F "codeforces_username=tourist" \
  -F "leetcode_username=johndoe"

Response:

{
  "portfolio_id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "john-doe-29fa2b",
  "status": "completed",
  "public_portfolio_url": "/portfolio/john-doe-29fa2b",
  "private_coaching_url": "/portfolio/john-doe-29fa2b/coaching",
  "generation_time_seconds": 12.5
}

Get Portfolio

GET /portfolio/{slug}

Returns complete public portfolio JSON.

Response Structure:

{
  "personal_info": {
    "name": "John Doe",
    "slug": "john-doe-29fa2b",
    "portfolio_focus": "fullstack"
  },
  "ai_generated_content": {
    "professional_summary": "...",
    "key_strengths": ["..."],
    "project_highlights": [...],
    "skills": ["..."],
    "work_experience": [...],
    "achievements": ["..."],
    "skills_summary": {
      "languages": ["..."],
      "frameworks": ["..."],
      "tools": ["..."]
    },
    "contact_info": {
      "email": "...",
      "linkedin": "...",
      "github": "..."
    }
  },
  "data_sources": {
    "github_projects": [...],
    "competitive_programming": {
      "codeforces": {...},
      "leetcode": {...}
    }
  },
  "code_quality_metrics": {...},
  "metadata": {
    "generated_at": "2024-02-09T12:00:00Z",
    "data_sources_used": ["resume", "github", "leetcode"]
  }
}

Get Coaching Insights

GET /portfolio/{slug}/coaching

Returns private coaching insights with personalized recommendations.

Response Structure:

{
  "overall_assessment": "Comprehensive assessment text...",
  "strengths": [
    "Strong full-stack development experience",
    "Excellent problem-solving skills"
  ],
  "areas_for_improvement": [
    {
      "area": "System Design",
      "suggestion": "Consider studying distributed systems..."
    }
  ],
  "recommendations": [
    "Build a microservices project",
    "Contribute to open-source projects"
  ],
  "next_steps": [
    "Complete system design course",
    "Practice LeetCode medium problems",
    "Build portfolio website"
  ]
}

Check Status

GET /portfolio/{slug}/status

Response:

{
  "portfolio_id": "...",
  "slug": "john-doe-29fa2b",
  "status": "completed",
  "generation_started_at": "2024-02-09T12:00:00Z",
  "generation_completed_at": "2024-02-09T12:00:12Z",
  "error_message": null
}

Status Values:

draft - Portfolio created but not generated
generating - Generation in progress
completed - Successfully generated
error - Generation failed

Portfolio Refinement

Refine Portfolio

POST /portfolio/{slug}/refine

Request:

{
  "instruction": "Make the professional summary more concise and emphasize backend skills",
  "sections": ["all"]
}

Response:

{
  "message": "Portfolio refined successfully",
  "version_id": "...",
  "version_number": 2,
  "version_state": "draft",
  "changes_summary": "AI refinement: Make the professional summary...",
  "portfolio_json": {...}
}

Confirm Draft

POST /portfolio/{slug}/confirm

Commits the current draft version and deletes other versions.

Revert to Version

POST /portfolio/{slug}/revert

Request:

{
  "version_id": "550e8400-e29b-41d4-a716-446655440000"
}

Get Version History

GET /portfolio/{slug}/versions?limit=50

Response:

{
  "versions": [
    {
      "id": "version-id-2",
      "version_number": 2,
      "version_state": "draft",
      "changes_summary": "AI refinement: Make it more concise",
      "created_at": "2024-02-09T14:30:00Z",
      "created_by": "ai_refinement"
    }
  ],
  "total_count": 2
}

Data Extraction Endpoints

Upload LinkedIn Profile

POST /upload/linkedin

Extracts structured sections from LinkedIn PDF export.

Upload Resume

POST /upload/resume

Extracts raw text from resume PDF/DOCX.

Get Codeforces Stats

GET /codeforces/{username}

Returns competitive programming statistics.

Analyze GitHub Repositories

POST /github/analyze

Request:

{
  "repos": [
    "https://github.com/user/repo1",
    "https://github.com/user/repo2"
  ]
}

Returns repository metadata, structure analysis, and quality metrics.

Get LeetCode Stats

GET /leetcode/{username}

Returns problem-solving statistics via GraphQL.

Frontend Pages

1. Landing Page (`/`)

Hero section with gradient background
Features showcase
Testimonials
Call-to-action buttons

2. Generate Portfolio (`/generate`)

Multi-section form with animations
Dynamic loading states
Time estimates (30-60 seconds)
Rotating messages during generation:
- "Analyzing your professional profile..."
- "Fetching GitHub repositories..."
- "Generating AI-powered insights..."
- And more!

3. Refine Portfolio (`/refine/:slug`)

Two-tab interface: Portfolio | Private Coaching
Portfolio tab:
- Professional summary
- Key strengths
- Project highlights
- Skills
Private Coaching tab:
- Overall Assessment (Indigo)
- Strengths (Green)
- Areas for Improvement (Yellow)
- Recommendations (Blue)
- Next Steps (Purple)
AI refinement controls
Version management
Confirm/revert actions

4. View Portfolio (`/portfolio/:slug`)

Beautiful public portfolio display
Responsive grid layout
Sections:
- Professional Summary
- Work Experience
- Featured Projects
- Achievements
- Skills & Technologies
- GitHub Projects
- Competitive Programming Stats
- Contact Information

Architecture

Backend Architecture

Ethical AI Usage

AI receives ONLY: metadata, README text, statistics
AI NEVER receives: source code, file contents (except README), code snippets
All inputs are sanitized in prepare_ai_context()

Language-Agnostic Analysis

Code quality based on structure, not semantics
Works for any programming language
Heuristic-based scoring (complexity, documentation, best practices)

Separation of Concerns

Public Portfolio: Recruiter-facing, polished content
Private Coaching: User-only, honest feedback and improvement suggestions

Graceful Degradation

Missing data sources handled gracefully
External API failures don't break generation
AI failures fall back to template-based content

Frontend Architecture

Component Structure

Navbar: Sticky navigation with smooth animations
Footer: Links, newsletter subscription, copyright
LenisScroll: Smooth scrolling wrapper
Pages: Separate components for each route

State Management

React hooks (useState, useEffect)
Local state for form data
API calls via Axios

Routing

React Router DOM v7
Client-side navigation
Dynamic routes for portfolio slugs

Styling

Tailwind CSS utility classes
Custom color schemes
Responsive breakpoints
Dark theme by default

Animations

Framer Motion for page transitions
Spring animations for buttons
Smooth scroll with Lenis

Database Schema

Portfolios Table

CREATE TABLE portfolios (
  id UUID PRIMARY KEY,
  slug VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255) NOT NULL,
  portfolio_focus VARCHAR(50),
  status VARCHAR(20) NOT NULL,

  -- Data source flags
  has_linkedin BOOLEAN DEFAULT FALSE,
  has_resume BOOLEAN DEFAULT FALSE,
  has_github BOOLEAN DEFAULT FALSE,
  has_codeforces BOOLEAN DEFAULT FALSE,
  has_leetcode BOOLEAN DEFAULT FALSE,

  -- Raw input data (JSON)
  linkedin_data JSONB,
  resume_text TEXT,
  github_data JSONB,
  codeforces_data JSONB,
  leetcode_data JSONB,

  -- Generated output (JSON)
  public_portfolio_json JSONB,
  private_coaching_json JSONB,
  ai_generation_metadata JSONB,

  -- Timestamps
  generation_started_at TIMESTAMP,
  generation_completed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_portfolios_slug ON portfolios(slug);
CREATE INDEX idx_portfolios_status ON portfolios(status);

Portfolio Versions Table

CREATE TABLE portfolio_versions (
  id UUID PRIMARY KEY,
  portfolio_id UUID REFERENCES portfolios(id) ON DELETE CASCADE,
  version_number INTEGER NOT NULL,
  version_state VARCHAR(20) NOT NULL,
  public_portfolio_json JSONB NOT NULL,
  private_coaching_json JSONB,
  changes_summary TEXT,
  created_by VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW(),

  UNIQUE(portfolio_id, version_number)
);

CREATE INDEX idx_versions_portfolio_id ON portfolio_versions(portfolio_id);
CREATE INDEX idx_versions_state ON portfolio_versions(version_state);

Deployment

Development

Backend:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend
npm run dev

Production

Backend Deployment

# Update DATABASE_URL to PostgreSQL
export DATABASE_URL=postgresql+asyncpg://user:pass@localhost/portfolio

# Run migrations
alembic upgrade head

# Start with multiple workers
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Frontend Deployment

cd frontend

# Build for production
npm run build

# Deploy dist/ folder to hosting service (Vercel, Netlify, etc.)

Environment Variables for Production

Backend (.env):

DATABASE_URL=postgresql+asyncpg://user:pass@host/db
GITHUB_TOKEN=your_token
GEMINI_API_KEY=your_key
CORS_ORIGINS=https://yourdomain.com

Frontend (.env.production):

VITE_API_URL=https://api.yourdomain.com

Security Notes

Current Limitations (Development)

CORS: Allows all origins (*) - restrict for production
Authentication: Not implemented - add JWT/OAuth for production
API Keys: Stored in .env file - use secrets manager for production
Rate Limiting: Relies on external API limits - add middleware for production
Input Validation: Basic validation - enhance for production

Production Recommendations

Add Authentication: JWT tokens for private coaching endpoint
Configure CORS: Whitelist specific domains
Add Rate Limiting: Prevent abuse
Use HTTPS: Enable SSL/TLS
Secrets Management: Use AWS Secrets Manager, Azure Key Vault, etc.
Input Sanitization: Add comprehensive validation
Error Handling: Don't expose internal errors to clients
Logging: Add structured logging with sensitive data redaction

Performance

API Rate Limits

Gemini API (Free Tier):

15 requests per minute
1M tokens per minute
1500 requests per day

GitHub API (Authenticated):

5000 requests per hour

Codeforces & LeetCode:

Public APIs, no authentication required
Best effort rate limiting

Optimization Tips

Use caching for external API responses
Implement request queuing for AI generation
Add database indexes for frequently queried fields
Use CDN for frontend assets
Enable gzip compression
Implement lazy loading for images

Contributing

This project was built for a hackathon. If you'd like to contribute:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Troubleshooting

Backend Issues

Database Migration Errors:

# Reset database
alembic downgrade base
alembic upgrade head

Port Already in Use:

# Change port
uvicorn app.main:app --port 8001

API Key Errors:

Verify .env file exists in project root
Check API key validity
Ensure no extra spaces in .env file

Frontend Issues

Build Errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

API Connection Issues:

Check VITE_API_URL in frontend/.env
Verify backend is running
Check CORS configuration

Styling Issues:

# Rebuild Tailwind CSS
npm run build

License

Built for hackathon use. Feel free to use and modify as needed.

Acknowledgments

FastAPI - Excellent async web framework
React - Powerful UI library
Google Gemini - Free-tier AI API
Tailwind CSS - Utility-first CSS framework
Framer Motion - Beautiful animations
GitHub, Codeforces, LeetCode - Public APIs for data aggregation
PrebuiltUI - Original Agentix template design inspiration

Contact

For questions or support, please open an issue on GitHub.

Built with ❤️ for developers, by developers

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
alembic		alembic
app		app
frontend		frontend
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
Procfile		Procfile
README.md		README.md
alembic.ini		alembic.ini
build.sh		build.sh
list_models.py		list_models.py
portfolios.db		portfolios.db
requirements.txt		requirements.txt
test_gemini_models.py		test_gemini_models.py
test_refine.py		test_refine.py

Folders and files

Latest commit

History

Repository files navigation

SmartFolio - AI-Powered Portfolio Generator

Table of Contents

Features

Portfolio Generation

AI-Powered Refinement

Private Coaching Insights

Modern Frontend

Tech Stack

Backend

Frontend

External Services

Project Structure

Setup Instructions

Prerequisites

1. Clone Repository

2. Backend Setup

2.1 Create Virtual Environment

2.2 Install Backend Dependencies

2.3 Configure Environment Variables

2.4 Run Database Migrations

2.5 Start Backend Server

3. Frontend Setup

3.1 Navigate to Frontend Directory

3.2 Install Frontend Dependencies

3.3 Configure Frontend Environment (Optional)

3.4 Start Frontend Development Server

4. Access the Application

User Workflow

1. Landing Page

2. Generate Portfolio

3. Refine Portfolio

4. View Public Portfolio

API Documentation

Base URL

Authentication

Health Check

Portfolio Generation

Generate Portfolio

Get Portfolio

Get Coaching Insights

Check Status

Portfolio Refinement

Refine Portfolio

Confirm Draft

Revert to Version

Get Version History

Data Extraction Endpoints

Upload LinkedIn Profile

Upload Resume

Get Codeforces Stats

Analyze GitHub Repositories

Get LeetCode Stats

Frontend Pages

1. Landing Page (/)

2. Generate Portfolio (/generate)

3. Refine Portfolio (/refine/:slug)

4. View Portfolio (/portfolio/:slug)

Architecture

Backend Architecture

Ethical AI Usage

Language-Agnostic Analysis

Separation of Concerns

Graceful Degradation

Frontend Architecture

Component Structure

State Management

Routing

Styling

Animations

Database Schema

Portfolios Table

Portfolio Versions Table

Deployment

Development

Production

Backend Deployment

1. Landing Page (`/`)

2. Generate Portfolio (`/generate`)

3. Refine Portfolio (`/refine/:slug`)

4. View Portfolio (`/portfolio/:slug`)