PersonaX — AI Personality Scanner

A futuristic AI-powered personality analysis tool that generates psychological-style reports using Google Gemini API

PersonaX is a frontend web application that simulates an AI personality scanner. Users enter a brief self-description (and optionally a GitHub username), and the app generates a structured psychological report displayed on a cyberpunk-inspired "Dossier" dashboard.

⚠️ Disclaimer: This is an experimental, educational project. The analysis is AI-generated and not real psychology or clinical assessment.

---

🔥 Features

• ✨ Futuristic Cyberpunk UI — Built with TailwindCSS
• 🧠 AI-Generated Personality Archetype — Unique character profiles
• 📝 Dynamic Summary Generation — Personalized insights
• 🧬 Strengths & Blind Spots — Balanced analysis
• 🎭 Fictional Character Match — Pop culture personality mapping
• 💾 LocalStorage Data Flow — Seamless page transitions
• ⚡ Fully Frontend — No backend required
• 🧪 Gemini API Integration — Powered by Google's latest AI
• 🛡️ API Key Safety — No exposed credentials in repo

---

🎥 Demo

Live Demo: https://personax-sepia.vercel.app

🧠 How It Works

Architecture Overview

User Input (scan.html) 
    ↓
Build Structured Prompt
    ↓
Send to Gemini API
    ↓
Receive JSON Response
    ↓
Store in localStorage
    ↓
Redirect to dossier.html
    ↓
Parse & Render UI

Step-by-Step Flow

1. User opens scan.html
2. User fills out:
   • Short bio (required)
   • GitHub username (optional)
3. startScan() builds a structured prompt
4. Prompt sent to Gemini API
5. Gemini returns structured JSON
6. Data stored in localStorage:

   localStorage.setItem("personaReport", JSON.stringify(profile))

7. User redirected to dossier.html
8. Dossier page reads localStorage and renders UI dynamically

No backend. No database. Just clean frontend architecture.

---

🧱 Tech Stack

Technology	Purpose
HTML5	Structure
TailwindCSS	Styling (via CDN)
Vanilla JavaScript	Logic & API calls
Google Gemini API	AI personality generation
LocalStorage	Data persistence
Vercel	Deployment
Git + GitHub	Version control

No frameworks. No libraries. Pure fundamentals.

---

📁 Project Structure

PersonaX/
│
├── scan.html              # User input page (AI scan ritual)
├── dossier.html           # Results dashboard page
├── test-gemini.html       # Gemini API testing playground
├── scripts/
│   └── dossier.js         # (Optional, if separated later)
├── data/
│   └── mockProfile.json   # Sample structured test data
├── README.md              # You are here
└── .gitignore             # Protects API keys

---

🧪 Example Output

What the AI Generates

The Gemini API returns structured JSON like this:

{
  "archetype": "The Strategic Overthinker",
  "summary": "You analyze deeply before acting, seeking patterns in chaos and clarity in complexity. Your mind is a fortress of logic, but sometimes you forget that not every battle needs strategic planning.",
  "traits": [
    "Analytical",
    "Methodical",
    "Introspective"
  ],
  "strengths": [
    "Deep Pattern Recognition",
    "Mental Fortitude",
    "Strategic Planning"
  ],
  "blindspots": [
    "Analysis Paralysis",
    "Emotional Distance",
    "Overthinking Simple Decisions"
  ],
  "characterMatch": "Sherlock Holmes"
}

This JSON is then dynamically injected into the UI using JavaScript DOM manipulation.

---

🚀 How to Run Locally

Prerequisites

• A modern web browser
• A Gemini API key (Get one here)
• Optional: Live Server (VS Code extension)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/personax.git

2. Navigate to the project folder:

   cd personax

3. Add your Gemini API key:

   Open scan.html and locate:

   const API_KEY = "YOUR_API_KEY_HERE";

   Replace with your actual key.

4. Run the project:

   • Option A: Open scan.html directly in your browser
   • Option B: Use Live Server in VS Code (right-click → Open with Live Server)

5. Start scanning! 🧠

---

🔐 API Key Safety

Important Security Notes

✅ This repository does NOT include any real API keys
✅ All sensitive data removed before publishing
✅ Global search confirmed no exposed credentials

Before Pushing to GitHub

Always ensure:

// ❌ NEVER commit this
const API_KEY = "AIzaSyC_RealKeyExample123456789";

// ✅ Instead, use this in repo
const API_KEY = "YOUR_API_KEY_HERE";

Best Practice: Use environment variables or .env files (not included in this repo since it's frontend-only).

---

🌍 Deployment

This project can be deployed easily on:

Platform	Difficulty	Speed
Vercel	⭐ Easy	⚡ Instant
Netlify	⭐ Easy	⚡ Instant
GitHub Pages	⭐⭐ Moderate	🕒 Fast

Deploy to Vercel (Recommended)

1. Push your code to GitHub
2. Go to vercel.com
3. Import your repository
4. Click "Deploy"
5. Done! ✅

Note: Remember to add your API key as an environment variable in your deployment settings.

---

⚠️ Limitations (Honest Disclosure)

This project:

• ❌ Does not validate psychological accuracy
• ❌ Uses AI creatively, not clinically
• ❌ Does not scrape GitHub data yet (username is optional placeholder)
• ❌ Uses user input, not real metadata
• ❌ Stores data only in browser (LocalStorage)

Future Improvements

• GitHub API integration (fetch real profile data)
• Backend proxy for API key safety
• Better form validation
• User accounts & authentication
• Exportable reports (PDF download)
• Scan history tracking
• Social sharing features
• Multi-language support

---

🎯 Why This Project Matters

This is not just a UI project. It demonstrates real-world developer skills:

Skill	Demonstrated
Prompt Engineering	✅ Structured AI queries
JSON Handling	✅ Parsing & validation
Frontend Architecture	✅ Multi-page data flow
API Workflows	✅ HTTP requests & responses
Data Flow Thinking	✅ localStorage management
UX Thinking	✅ User journey design
Debugging Ability	✅ Real-world troubleshooting
Product Thinking	✅ End-to-end feature building

This is the kind of project that:

• ✅ Works in portfolios
• ✅ Shows recruiter-level skills
• ✅ Demonstrates builder mindset
• ✅ Is extendable into real products

---

🛠️ Code Snippets

Prompt Engineering Example

const prompt = `You are a personality analysis AI. Based on this user input:
"${userBio}"

Generate a structured personality profile in strict JSON format:
{
  "archetype": "...",
  "summary": "...",
  "traits": [...],
  "strengths": [...],
  "blindspots": [...],
  "characterMatch": "..."
}`;

LocalStorage Data Transfer

// Save on scan.html
localStorage.setItem("personaReport", JSON.stringify(profile));

// Retrieve on dossier.html
const savedReport = JSON.parse(localStorage.getItem("personaReport"));

---

🤝 Contributing

Contributions are welcome! If you'd like to improve PersonaX:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

👨‍💻 Built By

Pranav
Student learning programming, AI tools, automation, and real-world development.
Focused on building projects, not just tutorials.

---

📜 License

This project is licensed under the MIT License.
Feel free to fork, remix, and build upon it for learning and inspiration.

MIT License

Copyright (c) 2026 Pranav

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

🌟 Show Your Support

If you found this project helpful or interesting:

• ⭐ Star this repository
• 🍴 Fork it for your own experiments
• 📢 Share it with others
• 🐛 Report bugs or suggest features

---

📞 Contact

Questions? Suggestions? Want to collaborate?

• GitHub Issues: Open an issue
• Email: agarwalpranav0711@gmail.com
• Twitter: @yourhandle

---

Made with 🧠 and ⚡ by Pranav

Building the future, one commit at a time.