🌊 Fluid Git

Physics-Driven In-Memory Git Engine & Interactive Learning Lab

A zero-latency, topological Git simulation where commands mutate a real in-memory content-addressable DAG.
Real commits · Real branches · Real 3-way LCA merges · Real line-level conflict resolution.

🚀 Launch Live Web App • ✨ Explore Curriculum • 🛠️ Interactive Playground • 🔍 Command Explorer • 📖 Smart Help

---

💡 What Makes Fluid Git Different?

Most Git visualizers show pre-baked animations of what Git conceptually does. Fluid Git is powered by a deterministic in-memory Git state engine modeled directly after Git's internal architecture:

  ┌───────────────────────┐       ┌───────────────────────┐       ┌───────────────────────┐
  │   WORKING DIRECTORY   │  ──>  │     STAGING AREA      │  ──>  │     OBJECT STORE      │
  │    (Unstaged Files)   │       │   (Index / .git/idx)  │       │ (Blobs, Trees, Commits)│
  └───────────┬───────────┘       └───────────┬───────────┘       └───────────┬───────────┘
              │                               │                               │
              └───────────────────────────────┼───────────────────────────────┘
                                              ▼
                              ┌───────────────────────────────┐
                              │     PURE GIT STATE REDUCER    │
                              │     (Deterministic Replay)    │
                              └───────────────┬───────────────┘
                                              │
                 ┌────────────────────────────┴────────────────────────────┐
                 ▼                                                         ▼
  ┌─────────────────────────────┐                           ┌─────────────────────────────┐
  │    PHYSICS COMMIT GRAPH     │                           │   INTERACTIVE TERMINAL &    │
  │ (Framer Motion Spring DAG)  │                           │   4-ZONE PLUMBING VIEWER    │
  └─────────────────────────────┘                           └─────────────────────────────┘

Every command typed into the simulated terminal mutates a single shared state store: the DAG graph, 3-zone staging visualizer, object inspectors, and lesson validators all react in real time.

---

⚡ Core Feature Showcase

Module	Icon	Capabilities
Physics Commit Graph	🌌	Spring-driven SVG canvas, auto-branch routing, detached HEAD markers, 2-parent merge diamonds, and commit SHA inspection tooltips.
Deterministic Engine	⚙️	Full object store (Blob, Tree, Commit, Tag), ref pointers, HEAD tracking, and reflog movement history.
3-Way Merge Engine	🔀	Topological Lowest Common Ancestor (LCA) search across multi-branch diamond DAGs. Accurate fast-forward vs 3-way merge resolution.
Merge Conflict Studio	💥	True line-level array diffing. Overlapping modifications trigger standard conflict markers (<<<<<<<, =======, >>>>>>>) with interactive inline resolvers.
Command Explorer	🔍	5 interactive tabs: Flag Builder, Comparisons (merge vs rebase), Recipe Scenarios, Emergency Triage, and 4-Zone Plumbing.
Smart Help & Catalog	📖	Searchable cheat sheet with live command chips, syntax breakdown, safety risk ratings, and topology diagrams.
Interactive Roadmap	🗺️	22-station learning progression flowchart connecting fundamentals to advanced history surgery.
Context AI Coach	🤖	Built-in Gemini 3.7 multi-model fallback chain with client-side BYOK support (OpenAI / Anthropic) and rate-limited free tier.
Theme Suite	🎨	Curated dark & developer themes: Linear, GitHub Dark, JetBrains, Tokyo Night, Espresso, and Nord.

---

📚 Pedagogical Curriculum (4 Progressive Stages)

Stage 1: Fundamentals  ──>  Stage 2: Branch & Merge  ──>  Stage 3: History Surgery  ──>  Stage 4: Remotes & Conflicts
[Staging & Commits]         [Divergent DAGs & LCA]        [Soft/Hard Resets & Stash]     [Conflict Studio & Remotes]

1. Stage 1: Repository Fundamentals
   • The 3-Zone Mental Model (Working Tree ➔ Index ➔ Commit History)
   • Staging files with git add, snapshotting with git commit -m
   • Inspecting repository state with git status and git log
2. Stage 2: Branching & Branch Topology
   • Creating and switching branches (git branch, git switch, git checkout -b)
   • Fast-Forward merges vs recursive 3-way merge commits
   • Deleting merged branches and tracking HEAD pointers
3. Stage 3: History Surgery & Undoing Mistakes
   • Dissecting git reset modes: --soft vs --mixed vs --hard
   • Temporary work preservation with git stash and git stash pop
   • Reverting safe public history with git revert
4. Stage 4: Remote Operations & Conflict Resolution
   • Simulating remotes: git fetch, git pull origin main, git push origin main
   • Real-time merge conflict handling in the dedicated Conflict Studio
   • History surgery with git cherry-pick and git reflog

---

🧪 Comprehensive Automated Test Suite

Fluid Git is thoroughly tested with Vitest to ensure zero state regressions or invalid Git operations:

✓ __tests__/command-parser.test.ts (15 tests)
  - Tokenizes arguments, quoted strings with spaces, flag bundling (-am), and bad syntax
✓ __tests__/git-engine.test.ts (21 tests)
  - Commits, branch creation, fast-forward merges, diamond LCA 3-way merges
  - Soft, mixed, and hard resets, revert commits, stash and pop stacks
✓ __tests__/curriculum-integrity.test.ts (4 tests)
  - Validates all stage lesson objectives, initial state builders, and completion rules

Test Files  3 passed (3)
     Tests  40 passed (40)
  Duration  1.17s

---

🛠️ Technology Stack

• Framework: Next.js 16 (App Router, Turbopack)
• Language: TypeScript (Strict Mode, 100% Type-Safe)
• UI & Components: React 19, Tailwind CSS
• State Management: Zustand
• Animation & Physics: Framer Motion
• Test Runner: Vitest
• AI Integration: Google Gemini API (with optional OpenAI / Anthropic BYOK proxy)

---

🚀 Quick Start (Local Setup)

1. Clone the repository

git clone https://github.com/Ananth-Sai/Git-Visualizer-Learning-Engine.git
cd Git-Visualizer-Learning-Engine

2. Install dependencies

npm install

3. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

4. Run automated tests

npm test

5. Create a production build

npm run build
npm run start

---

🤖 AI Coach Architecture & Rate-Limiting Design

Fluid Git's AI Coach is engineered to be resilient, educational, and cost-effective:

• Multi-Model Fallback Chain: Google Gemini requests cascade dynamically across available models (gemini-3.7-flash ➔ gemini-3.6-flash ➔ gemini-3.5-flash ➔ gemini-2.5-flash) to prevent 503 service degradations.
• BYOK Support: Users can provide their own OpenAI (gpt-4o-mini), Anthropic (claude-3-5-sonnet), or Gemini keys via the Settings Modal. BYOK requests bypass shared rate limits and are sent with encrypted client-side headers.
• In-Memory Sliding-Window Limiter: The default free tier enforces an IP-based sliding window limit (10 requests/minute).

  Serverless Note: Under distributed serverless environments (e.g. Vercel Edge/Serverless Lambdas), this in-memory Map operates on a per-instance basis as a soft protective guard. If enterprise-scale global synchronization is needed, it can be paired with an Upstash Redis/KV store.

• 100% Offline Local Fallbacks: If API rate limits are hit or the user is offline, the coach gracefully returns context-aware deterministic heuristics based on the active lesson objective and error message, guaranteeing the app never crashes or becomes unusable without network access.

---

🔒 Security & Privacy Notice

• Zero Secret Logging: Your API keys (Gemini, OpenAI, Anthropic) are stored strictly in client-side localStorage and sent directly over HTTPS only when interacting with the AI Coach.
• Fallback Guarantee: The entire simulation, learning tracks, canvas animations, and command parsers function 100% offline without requiring any API keys or network connection.

---

📄 License

Distributed under the MIT License. See LICENSE for more details.

---

_{Built with ❤️ for developers and students mastering Git topology.}