files

README.md

@@ -0,0 +1,205 @@
+# 🚀 ARCHON
+<p align="center">
+  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:6366f1,100:8b5cf6&height=200&section=header&text=Repo%20Interview%20Generator&fontSize=40&fontColor=ffffff" />
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Backend-FastAPI-009688?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Language-Python-3776AB?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/AI-RAG%20Pipeline-8b5cf6?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Embeddings-SentenceTransformers-orange?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Status-Production%20Ready-success?style=for-the-badge" />
+</p>
+
+<p align="center">
+  <img src="https://readme-typing-svg.herokuapp.com?font=Fira+Code&size=20&pause=1000&color=8B5CF6&center=true&vCenter=true&width=600&lines=Analyze+Any+GitHub+Repo;Generate+Deep+Interview+Questions;Fallback+AI+Without+LLMs;Built+for+Real+Engineering+Insight" />
+</p>
+
+---
+
+## 🧠 What is this?
+
+A system that **analyzes any GitHub repository** and generates **deep technical interview questions + answers** based on:
+
+* Architecture
+* Scalability
+* Tradeoffs
+* Real-world engineering decisions
+
+⚡ Works even without LLM access using a **fallback heuristic engine**.
+
+---
+
+## ✨ Features
+
+### 🔍 Repository Analysis
+
+* Fetches and parses GitHub repositories via API
+* Prioritizes important files (core logic > boilerplate)
+* Supports multiple languages
+
+### 🧩 Intelligent Chunking
+
+* Breaks code into meaningful chunks
+* Filters noise (non-informative code)
+* Preserves structural context
+
+### 🧠 Embedding + Retrieval (RAG)
+
+* Uses **SentenceTransformers**
+* Retrieves most relevant code sections
+* Builds contextual understanding of system design
+
+### 🤖 AI Question Generation
+
+* Generates interview-level questions on:
+
+  * Architecture decisions
+  * Scalability concerns
+  * Tradeoffs
+
+### ⚡ Fallback Mode (No LLM Required)
+
+* Automatically switches to **rule-based generation**
+* Uses detected signals:
+
+  * API usage
+  * State management
+  * Auth systems
+  * Async logic
+
+---
+
+## 🧱 System Architecture
+
+```txt
+GitHub Repo
+   ↓
+File Fetching + Prioritization
+   ↓
+Chunking + Filtering
+   ↓
+Embeddings (SentenceTransformers)
+   ↓
+Vector Similarity Retrieval
+   ↓
+Context Builder
+   ↓
+AI Question Generator
+   ↓
+Fallback Engine (if LLM unavailable)
+```
+
+---
+
+## 🛠️ Tech Stack
+
+```bash
+Backend:
+- FastAPI
+- Python
+
+AI / ML:
+- SentenceTransformers
+- Cosine Similarity (Sklearn)
+
+Data:
+- GitHub REST API
+
+Frontend:
+- Minimal Web UI (React / HTML)
+
+Optional:
+- OpenAI API (LLM generation)
+```
+
+---
+
+## ⚙️ How it Works
+
+1. Input a GitHub repo URL
+2. System fetches and filters key files
+3. Code is chunked and embedded
+4. Relevant chunks are retrieved
+5. Questions are generated using:
+
+   * LLM (if available)
+   * OR fallback heuristic engine
+
+---
+
+## 📡 API Usage
+
+### POST `/analyze`
+
+```json
+{
+  "repo_url": "https://github.com/user/repo",
+  "num_questions": 5
+}
+```
+
+### Response
+
+```json
+{
+  "repo": "...",
+  "mode": "mock",
+  "questions": [
+    {
+      "id": 1,
+      "question": "...",
+      "answer": "..."
+    }
+  ]
+}
+```
+
+---
+
+## ⚠️ Challenges Solved
+
+* Large repo handling (chunking + prioritization)
+* Token limitations (retrieval instead of full context)
+* LLM dependency → solved with fallback system
+* Noise reduction in code analysis
+
+---
+
+## 💡 Future Improvements
+
+* 🔥 Dynamic repo-type detection (ML, backend, real-time, etc.)
+* 📊 Question difficulty levels (junior → senior)
+* 🔗 Follow-up interview questions
+* 🧠 Hybrid LLM + rule-based reasoning
+* ⚡ Caching + performance optimization
+
+---
+
+## 🧑‍💻 Author
+
+Built by **Dave** — aspiring systems engineer ⚡
+
+---
+
+## 🎬 Demo
+
+<p align="center">
+  <img src="https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExZ2Z4b2h3YzJ5dTFoMGN6dGx6eTVjYjZ0d2VtZ2w0N2JkNnR3b2p5ZyZlcD12MV9naWZzX3NlYXJjaCZjdD1n/26tn33aiTi1jkl6H6/giphy.gif" width="500" />
+</p>
+
+---
+
+## ⭐ Support
+
+If this project helped or inspired you:
+
+* ⭐ Star the repo
+* 🍴 Fork it
+* 🧠 Build something even crazier
+
+---
+
+<p align="center">
+  <b>“Don’t just read code. Interrogate it.”</b>
+</p>

ai.py

@@ -0,0 +1,22 @@
+from openai import OpenAI
+import os
+from openai import OpenAI
+
+client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+
+def call_llm(prompt):
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[
+            {"role": "system", "content": "You are a senior software engineer."},
+            {"role": "user", "content": prompt}
+        ],
+        temperature=0.7
+    )
+    return response.choices[0].message.content
+   clear
+
+    git pull space
+    git add .
+    git commit -m "files"
+git push space master

fake_ai.py

@@ -0,0 +1,52 @@
+def generate_mock_questions(chunks, num_questions=5):
+    questions = []
+
+    context_text = " ".join([c["chunk"].lower() for c in chunks])
+
+    # Heuristic signals (lightweight, no LLM)
+    signals = {
+        "api": "fetch" in context_text or "axios" in context_text,
+        "auth": "auth" in context_text or "login" in context_text,
+        "database": "db" in context_text or "firebase" in context_text,
+        "state": "useState" in context_text or "state" in context_text,
+        "async": "async" in context_text or "await" in context_text,
+    }
+
+    if signals["api"]:
+        questions.append({
+            "question": "How would you design this API layer for scalability and fault tolerance?",
+            "answer": "Introduce caching, retries, rate limiting, and abstraction layers to decouple API logic."
+        })
+
+    if signals["database"]:
+        questions.append({
+            "question": "What are the tradeoffs of using a NoSQL database like Firebase in this system?",
+            "answer": "It offers flexibility and scalability but may lack strong consistency and complex querying."
+        })
+
+    if signals["state"]:
+        questions.append({
+            "question": "How would you manage global state in a growing frontend application?",
+            "answer": "Use centralized state management (Context, Redux) and avoid excessive prop drilling."
+        })
+
+    if signals["auth"]:
+        questions.append({
+            "question": "What security concerns exist in this authentication flow?",
+            "answer": "Token leakage, improper session handling, and lack of validation are key risks."
+        })
+
+    if signals["async"]:
+        questions.append({
+            "question": "How would you handle concurrency and async operations safely in this system?",
+            "answer": "Use proper error handling, cancellation, and avoid race conditions with controlled state updates."
+        })
+
+    # fallback generic
+    while len(questions) < num_questions:
+        questions.append({
+            "question": "What architectural improvements would you suggest for this system?",
+            "answer": "Improve modularity, scalability, and separation of concerns across components."
+        })
+
+    return questions[:num_questions]

github_client.py

@@ -0,0 +1,327 @@
+import base64
+from sentence_transformers import SentenceTransformer
+from sklearn.metrics.pairwise import cosine_similarity
+import requests
+import os
+from dotenv import load_dotenv
+
+from ai import call_llm
+from fake_ai import generate_mock_questions
+
+load_dotenv()
+
+GITHUB_TOKEN = os.getenv("GITHUB_TOKEN")
+
+HEADERS = {
+    "Accept": "application/vnd.github+json"
+}
+
+if GITHUB_TOKEN:
+    HEADERS["Authorization"] = f"Bearer {GITHUB_TOKEN}"
+
+
+
+def get_repo_tree(owner, repo, branch):
+    url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1"
+
+    res = requests.get(url, headers=HEADERS)
+
+    if res.status_code != 200:
+        raise Exception(f"GitHub API error: {res.json()}")
+
+    return res.json()["tree"]
+
+
+ALLOWED_EXTENSIONS = (
+    ".py", ".js", ".ts", ".jsx", ".tsx", ".md", ".json",
+    ".html", ".htm", ".css", ".scss", ".sass", ".less",
+    ".csv", ".sql", ".xml", ".sh", ".bash", ".bat", ".ps1", ".ipynb",
+    ".php", ".rb", ".java", ".go", ".cs", ".scala", ".kt", ".kts", ".ex", ".exs",
+    ".swift", ".m", ".mm", ".dart", ".rst", ".gitattributes"
+)
+
+IMPORTANT_FILES = [
+    "server/",
+    "src/",
+    "app/",
+    "index",
+    "main",
+    "api",
+]
+
+def filter_files(tree):
+    return [
+        file for file in tree
+        if file["type"] == "blob" and file["path"].endswith(ALLOWED_EXTENSIONS)
+    ]
+
+
+def get_file_content(owner, repo, path):
+    url = f"https://api.github.com/repos/{owner}/{repo}/contents/{path}"
+
+    res = requests.get(url, headers=HEADERS)
+
+    if res.status_code != 200:
+        return None
+
+    data = res.json()
+
+    content = base64.b64decode(data["content"]).decode("utf-8", errors="ignore")
+
+    return content
+
+
+from urllib.parse import urlparse
+
+
+def parse_github_url(url: str):
+    path = urlparse(url).path.strip("/")
+    parts = path.split("/")
+
+    if len(parts) < 2:
+        raise ValueError("Invalid GitHub URL")
+
+    owner, repo = parts[0], parts[1]
+    return owner, repo
+
+def get_default_branch(owner, repo):
+    url = f"https://api.github.com/repos/{owner}/{repo}"
+    res = requests.get(url, headers=HEADERS)
+    if res.status_code != 200:
+        raise Exception(f"GitHub API error: {res.json()}")
+    return res.json()["default_branch"]
+
+def fetch_repo_contents(repo_url):
+
+    owner, repo = parse_github_url(repo_url)
+    branch = get_default_branch(owner, repo)
+
+    tree = get_repo_tree(owner, repo, branch)
+    files = filter_files(tree)
+
+    results = []
+
+    for file in prioritize_files(files)[:20]:
+        content = get_file_content(owner, repo, file["path"])
+
+        if content:
+            results.append({
+                "path": file["path"],
+                "content": content
+            })
+
+
+    return results
+def score_file(path):
+    score = 0
+
+    if "README" in path:
+        score += 3
+    if any(key in path.lower() for key in IMPORTANT_FILES):
+        score += 5
+    if path.endswith((".js", ".ts", ".py", ".java", ".jsx", ".c")):
+        score += 4
+
+    return score
+
+
+def prioritize_files(files):
+    return sorted(files, key=lambda f: score_file(f["path"]), reverse=True)
+
+def chunk_text(text, size=1000):
+    lines = text.split("\n")
+    chunks = []
+    current = []
+
+    current_len = 0
+
+    for line in lines:
+        current.append(line)
+        current_len += len(line)
+
+        if current_len >= size:
+            chunks.append("\n".join(current))
+            current = []
+            current_len = 0
+
+    if current:
+        chunks.append("\n".join(current))
+    return chunks
+
+def process_files(files):
+    processed = []
+
+    for file in files:
+        chunks = chunk_text(file["content"], size=1000)
+
+        processed.append({
+            "path": file["path"],
+            "chunks": chunks
+        })
+
+    return processed
+
+def classify_file(path):
+    if "server" in path or path.endswith(".py") or path.endswith(".js"):
+        return "backend"
+    if "client" in path or path.endswith(".jsx"):
+        return "frontend"
+    if "config" in path or path.endswith(".json"):
+        return "config"
+    return "other"
+
+def filter_chunks(chunks):
+    return [
+        c for c in chunks
+        if len(c.strip()) > 50 and (
+            "import" in c or "function" in c or "class" in c
+        )
+    ]
+def build_retrieval_query():
+    return """
+core architecture system design scalability performance
+state management data flow backend logic frontend interaction
+real-time communication concurrency bottlenecks tradeoffs
+"""
+
+def build_question_prompt(repo_summary, signals, num_questions):
+    return f"""
+You are a senior software engineer conducting a deep technical interview.
+
+Repository Summary:
+{repo_summary}
+
+Detected System Signals:
+{signals}
+
+Generate {num_questions} deep interview questions and strong answers.
+
+Focus on:
+- architecture decisions
+- scalability challenges
+- tradeoffs (e.g. WebSockets vs polling)
+- real-world engineering issues
+
+Avoid generic questions.
+Format:
+Q1:
+A1:
+"""
+embeddings = [
+    {
+        "chunk": "...",
+        "vector": [...]
+    }
+]
+
+def retrieve(query_vector, embeddings, top_k=5):
+    scored = []
+
+    for item in embeddings:
+        score = cosine_similarity(
+            [query_vector],
+            [item["vector"]]
+        )[0][0]
+
+        scored.append((score, item))
+
+    scored = sorted(scored, key=lambda x: x[0], reverse=True)
+
+    return [item for _, item in scored[:top_k]]
+
+def build_embeddings(processed_files):
+    index = []
+
+    for file in processed_files:
+        filtered = filter_chunks(file["chunks"])
+
+        for chunk in filtered:
+            vector = embed_text(chunk)
+
+            index.append({
+                "chunk": chunk,
+                "vector": vector,
+                "path": file["path"]
+            })
+
+    return index
+
+def format_context(chunks):
+    return "\n\n".join([
+         f"[FILE: {c['path']}]\n{c['chunk'][:800]}"
+        for c in chunks
+    ])
+
+
+def generate_questions_from_repo(repo_url, num_questions=5):
+    # 1. Fetch
+    files = fetch_repo_contents(repo_url)
+
+    # 2. Process
+    processed = process_files(files)
+
+    # 3. Build embeddings
+    embedding_index = build_embeddings(processed)
+
+    # 4. Build query
+    query = build_retrieval_query()
+    query_vector = embed_text(query)
+
+    # 5. Retrieve relevant chunks
+    top_chunks = retrieve(query_vector, embedding_index, top_k=8)
+
+    # 6. Build context
+    context = format_context(top_chunks)
+
+    # 7. Build final prompt
+    prompt = f"""
+You are a senior software engineer conducting a deep technical interview.
+
+Analyze this code context:
+
+{context}
+
+Generate {num_questions} deep technical interview questions and answers.
+
+Focus on:
+- architecture
+- scalability
+- tradeoffs
+- real-world engineering challenges
+
+Format:
+Q1:
+A1:
+"""
+    try:
+        result = call_llm(prompt)
+
+        return {
+            "mode": "llm",
+            "data": result
+        }
+
+    except Exception as e:
+        print("LLM failed, falling back to mock:", str(e))
+
+        mock = generate_mock_questions(top_chunks, num_questions)
+
+        return {
+            "mode": "mock",
+            "data": mock
+        }
+
+model = SentenceTransformer("all-MiniLM-L6-v2")
+
+def embed_text(text):
+    return model.encode(text)
+
+repo_cache = {}
+
+def get_or_create_embeddings(repo_url, processed):
+    if repo_url in repo_cache:
+        return repo_cache[repo_url]
+
+    embeddings = build_embeddings(processed)
+    repo_cache[repo_url] = embeddings
+    return embeddings

main.py

@@ -0,0 +1,43 @@
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from fastapi.middleware.cors import CORSMiddleware
+
+from github_client import  generate_questions_from_repo
+
+app = FastAPI()
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000"], # Your Next.js frontend URL
+    allow_credentials=True,
+    allow_methods=["*"], # Allows POST, GET, etc.
+    allow_headers=["*"], # Allows Content-Type, Authorization, etc.
+)
+
+class RepoRequest(BaseModel):
+    repo_url: str
+    num_questions: int = 5
+
+
+@app.get("/")
+def home():
+    return {"message": "Repo Interview Generator API"}
+
+
+@app.post("/analyze")
+def analyze_repo(data: RepoRequest):
+    try:
+        result = generate_questions_from_repo(
+            data.repo_url,
+            data.num_questions
+        )
+
+        return {
+            "repo": data.repo_url,
+            "questions_requested": data.num_questions,
+            "mode": result["mode"],
+            "result": result["data"]
+        }
+
+    except Exception as e:
+        raise (HTTPException(status_code=500, detail=str(e)))

requirements.txt

@@ -0,0 +1,26 @@
+fastapi==0.110.0
+uvicorn[standard]==0.29.0
+
+pydantic==2.6.4
+python-dotenv==1.0.1
+
+requests==2.31.0
+httpx==0.27.0
+
+openai==1.14.3
+
+tiktoken==0.6.0
+
+beautifulsoup4==4.12.3
+
+gitpython==3.1.43
+
+numpy==1.26.4
+scikit-learn==1.4.2
+
+tenacity==8.2.3
+sentence-transformers==3.0.1
+
+
+git remote add space https://huggingface.co/spaces/davex-ai/archon-backend
+git push space master