# vasu-devs/mapmyrepo architecture

> Architecture diagram of the GitHub repository vasu-devs/mapmyrepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vasu-devs/mapmyrepo
- Repository: https://github.com/vasu-devs/mapmyrepo

## Overview

##### Project type and purpose
- MapMyRepo is a client-side, single-page React application (built with Vite and TypeScript) whose purpose is to ingest a local filesystem or GitHub repository, parse its structure, and render it as an interactive, AI-enhanced, force-directed node graph using D3.js.
- It has no bespoke backend; all interactions happen in the browser via two external services: the GitHub REST API and Google Gemini AI.

##### File structure
- Top-level files:
- index.html, index.tsx, App.tsx: React entry point and main layout
- vite.config.ts, tsconfig.json: build/tooling configuration
- package.json: dependencies (React, D3, Tailwind, Google Gemini)
- Directories:
- components/: UI modules (FileUploader, RepoVisualizer, Sidebar, SearchBar)
- services/: business-logic modules handling external calls (fileService, geminiService)
- public/: static assets (favicon, etc.)
- scripts/: local test scripts (used during development)
- There is no “backend” folder; the browser app directly calls external APIs.

##### README for additional insights
- Confirms tech stack: React 19, TypeScript, Vite, D3.js, Tailwind CSS, Google Gemini AI, Marked.js.
- Describes core features: interactive graph, AI-powered summaries & Q&A, local/GitHub import.
- Mentions environment variables (`VITE_GEMINI_API_KEY`, optional `VITE_GITHUB_TOKEN`) injected at build time.

a. Main components
- User’s Browser (host of the SPA)
- UI Layer (React components)
– FileUploader
– RepoVisualizer (D3 force-directed graph)
– Sidebar (AI chat & metadata panel)
- Service Layer
– fileService.ts ( local FileReader + GitHub REST API )
– geminiService.ts ( Google Gemini AI REST API )
- External Services
– GitHub API (for repository fetch)
– Google Gemini AI (for summaries and Q&A)
b. Relationships & interactions
1. User → FileUploader: drags/drops or submits GitHub URL
2. FileUploader → fileService
– If local: FileReader parses folder tree
– If GitHub: fetch tree, filter artifacts
3. fileService → returns tree data to React state
4. RepoVisualizer consumes tree data → D3 renders nodes/links
5. User selects a node → Sidebar triggers geminiService
6. geminiService sends file/folder content to Google Gemini → returns summary/Q&A
7. Sidebar displays AI response
c. Architectural patterns & design principles
– Single responsibility: UI vs. data-fetch services are in separate folders
– Unidirectional data flow: React state → props → child components
– Modular “services” for external-API abstraction
– Static hosting for client-only SPA (Vite build → dist)
d. Relevant technologies
– React + TSX components (blue rectangles)
– D3.js force-directed graph (green module)
– Tailwind CSS styling
– Vite as build/development server
– External REST calls: fetch/XHR to GitHub & Gemini

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Environment
    subgraph "Browser Environment"
        direction TB
        Browser["User's Browser (SPA Runtime)"]:::environment

        subgraph "UI Layer"
            direction TB
            FileUploader["FileUploader Component"]:::frontend
            RepoVisualizer["RepoVisualizer Component"]:::frontend
            Sidebar["Sidebar Component"]:::frontend
            SearchBar["SearchBar Component"]:::frontend
        end

        subgraph "Service Layer"
            direction TB
            fileService["fileService.ts"]:::service
            geminiService["geminiService.ts"]:::service
        end
    end

    subgraph "External Services"
        direction TB
        GitHubAPI[("GitHub REST API")]:::external
        GoogleGemini[("Google Gemini AI API")]:::external
    end

    subgraph "Configuration & Assets"
        direction TB
        Index["React Entry Point\nindex.tsx"]:::config
        AppLayout["Main Application Layout\nApp.tsx"]:::config
        ViteConfig["vite.config.ts"]:::config
        TSConfig["tsconfig.json"]:::config
        PackageJSON["package.json"]:::config
        PublicDir["public/ (Static Assets)"]:::config
        Scripts["scripts/"]:::config
    end

    %% Data Flow
    Browser -->|"loads"| Index
    Index -->|"renders"| AppLayout
    AppLayout --> FileUploader
    AppLayout --> RepoVisualizer
    AppLayout --> Sidebar
    AppLayout --> SearchBar

    FileUploader -->|"invoke parse"| fileService
    fileService -->|"tree data"| RepoVisualizer

    RepoVisualizer -->|"node select"| Sidebar
    Sidebar -->|"request summary"| geminiService
    geminiService -->|"API call"| GoogleGemini
    GoogleGemini -->|"response"| Sidebar

    FileUploader -->|"fetch repo"| GitHubAPI
    fileService -->|"GitHub fetch"| GitHubAPI

    %% Development Workflow
    ViteConfig --> Index
    TSConfig --> Index
    PackageJSON --> Index
    PublicDir -->|served| Browser
    Scripts -->|dev tests| geminiService

    %% Click Events
    click FileUploader "https://github.com/vasu-devs/mapmyrepo/blob/main/components/FileUploader.tsx"
    click RepoVisualizer "https://github.com/vasu-devs/mapmyrepo/blob/main/components/RepoVisualizer.tsx"
    click Sidebar "https://github.com/vasu-devs/mapmyrepo/blob/main/components/Sidebar.tsx"
    click SearchBar "https://github.com/vasu-devs/mapmyrepo/blob/main/components/SearchBar.tsx"
    click fileService "https://github.com/vasu-devs/mapmyrepo/blob/main/services/fileService.ts"
    click geminiService "https://github.com/vasu-devs/mapmyrepo/blob/main/services/geminiService.ts"
    click Index "https://github.com/vasu-devs/mapmyrepo/blob/main/index.tsx"
    click AppLayout "https://github.com/vasu-devs/mapmyrepo/blob/main/App.tsx"
    click ViteConfig "https://github.com/vasu-devs/mapmyrepo/blob/main/vite.config.ts"
    click TSConfig "https://github.com/vasu-devs/mapmyrepo/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/vasu-devs/mapmyrepo/blob/main/package.json"
    click PublicDir "https://github.com/vasu-devs/mapmyrepo/tree/main/public/"
    click Scripts "https://github.com/vasu-devs/mapmyrepo/tree/main/scripts/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef service fill:#FFE0B2,stroke:#e65100,color:#000
    classDef external fill:#C8E6C9,stroke:#2e7d32,color:#000
    classDef config fill:#F0F0F0,stroke:#888,color:#000
    classDef environment fill:#FFF3E0,stroke:#fb8c00,color:#000
```
