Clarum is an AI-powered repository onboarding assistant designed to help developers understand unfamiliar codebases faster.

Instead of forcing engineers to manually trace imports, jump through folders, and reverse-engineer architecture diagrams, Clarum transforms a GitHub repository into:

• A project mission brief
• An interactive dependency blueprint
• A structured onboarding path
• A developer-friendly architecture summary

Built for students, junior developers, contributors, and engineers joining new projects, Clarum acts as a living "Code Atlas" for any repository.

One of the hardest parts of software engineering isn't writing code.

It's understanding code that somebody else already wrote.

New developers often spend hours or days answering questions like:

• Where does the application start?
• What framework is being used?
• Which files matter most?
• How does data flow through the system?
• What should I read first?

Clarum automates that process.

Paste a GitHub repository URL and receive a complete onboarding package generated through deterministic code analysis and AI-powered architectural reasoning.

Generate a concise mission brief describing:

• Project purpose
• Core functionality
• Primary framework
• File count
• Architectural responsibilities

Automatically generate an interactive dependency graph showing:

• Internal file relationships
• Module imports
• System structure
• Architectural boundaries

Powered by:

• NetworkX
• React Flow
• Dagre Layout Engine

Receive a guided onboarding roadmap.

Instead of opening random files, Clarum recommends:

1. Which file to start with
2. Why it matters
3. What you'll learn from it

Making unfamiliar repositories significantly easier to navigate.

Gemini analyzes the extracted repository structure and generates:

• System overview
• Major modules
• Data flow explanation
• Architectural breakdown

Presented in plain English for rapid understanding.

Clarum follows a deterministic-first architecture.

GitHub Repository
        ↓
Repository Scanner
        ↓
Dependency Extraction
        ↓
Framework Detection
        ↓
Gemini Analysis
        ↓
Structured JSON Report
        ↓
React Visualization Layer

Users submit a public GitHub repository URL.

The backend:

• Validates the URL
• Normalizes repository paths
• Checks the local cache

If the repository has already been analyzed, Clarum instantly serves the cached result.

Using GitPython:

• Repository is cloned locally
• File tree is traversed
• Binary files are skipped
• Relevant source files are identified

A deterministic scanner extracts:

• Imports
• Internal references
• File relationships

These relationships are converted into a directed graph using NetworkX.

The extracted repository context is sent to Gemini 2.5 Flash.

The model generates:

• Architecture summary
• System explanation
• Learning path
• Developer onboarding report

All outputs are validated through Pydantic schemas before being returned.

Frontend components consume the structured JSON and render:

• Interactive dependency graphs
• Architecture summaries
• Learning recommendations

No manual configuration required.

The frontend is designed around a simple principle:

One screen. One idea. One focus.

Instead of dashboards packed with widgets and controls, Clarum uses scroll-snapped narrative sections to guide the user through understanding a repository.

• React 18
• Vite
• Tailwind CSS
• Framer Motion
• React Flow
• Dagre
• Axios

Application orchestrator.

Responsible for:

• Global state management
• Analysis lifecycle
• Loading states
• View transitions

Interactive repository map.

Features:

• Automatic graph layout
• Deterministic edge coloring
• Hierarchical node spacing
• Zoom and pan controls

Displays the AI-generated onboarding sequence.

Each recommendation includes:

• File name
• Order
• Purpose
• Learning objective

Clarum's backend is built around FastAPI and follows a modular service architecture.

• Python 3.12
• FastAPI
• SQLAlchemy
• SQLite
• GitPython
• Google Gemini
• Pydantic v2
• NetworkX

Handles:

• Repository ingestion
• URL validation
• Cache lookup

Responsible for:

• Analysis execution
• Background processing
• Status tracking

Deterministic repository analyzer.

Extracts:

• File counts
• Frameworks
• Imports
• Dependency relationships

Builds the dependency graph used throughout the application.

Generative analysis engine.

Responsibilities:

• Prompt construction
• Gemini communication
• JSON validation
• Structured report generation

• React 18
• Vite
• Tailwind CSS
• React Flow
• Dagre
• Framer Motion
• Axios

• FastAPI
• SQLAlchemy
• SQLite
• GitPython
• NetworkX
• Google Gemini SDK
• Pydantic

• Vercel (Frontend)
• Render (Backend)

• Node.js 18+
• Python 3.12+
• Gemini API Key

cd backend

python -m venv venv

# Windows
venv\Scripts\activate

# Linux / macOS
source venv/bin/activate

pip install -r requirements.txt

Create a .env file:

GEMINI_API_KEY=your_api_key_here
DATABASE_URL=sqlite:///./repopilot.db

Run the backend:

uvicorn app.main:app --reload

cd frontend

npm install

npm run dev

Ensure the API client points to your local FastAPI instance during development.

Hosted on Vercel.

Benefits:

• Global CDN
• Edge caching
• Instant deployments

Hosted on Render.

Configuration:

PYTHON_VERSION=3.12.3

Render automatically installs backend dependencies and launches the FastAPI service.

clarum/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── analyzers/
│   │   ├── services/
│   │   ├── models/
│   │   └── main.py
│   ├── requirements.txt
│   └── repopilot.db
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── api/
│   │   ├── pages/
│   │   └── App.jsx
│   ├── package.json
│   └── vite.config.js
│
└── README.md

Clarum generates:

• Purpose
• Framework
• Architecture summary

• Dependency graph
• Import relationships
• Structural visualization

• Recommended files
• Reading order
• Onboarding explanations

• Repository analysis systems
• Dependency graph generation
• AI-assisted software onboarding
• FastAPI service architecture
• React visualization engineering
• Deterministic + Generative AI hybrid design
• Production deployment workflows
• Human-centered developer tooling

• Feature Complete
• Production Deployed
• Hackathon Submission Ready

Built to make understanding unfamiliar codebases dramatically faster.