Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The current commit graph visualization in Monolex provides branch-level views through a comprehensive TypeScript module. However, this implementation lacks commit-level granularity that would expose the true Git DAG structure to users. The Work-Wiki system requires complete transparency of AI development work. For git operations, this means showing not just which branches exist, but the precise commit relationships that form the development history. 
┌─────────────────────────────────────────────────────────────────┐
│              CURRENT ARCHITECTURE OVERVIEW                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌───────────────────────────────────────────────────────┐      │
│  │         git-branch-diagram-viewer.ts                  │      │
│  │              (2,331 lines)                            │      │
│  │                                                       │      │
│  │  ┌────────┐  ┌────────┐  ┌──────────┐                 │      │
│  │  │ Branch │  │ Connect│  │   SVG    │                 │      │
│  │  │  Node  │  │  -ion  │  │ Render   │                 │      │
│  │  └───┬────┘  └───┬────┘  └────┬─────┘                 │      │
│  │      └───────────┴─────────────┘                      │      │
│  │                    │                                  │      │
│  │             ┌──────┴──────┐                           │      │
│  │             │   Diagram   │                           │      │
│  │             │   Output    │                           │      │
│  │             └─────────────┘                           │      │
│  └───────────────────────────────────────────────────────┘      │
│                                                                 │
│  LIMITATION: Shows branch→branch connections                    │
│              NOT commit→commit DAG                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

​
Current Implementation

​
BranchNode Interface

The current implementation captures branch-level information: 
┌───────────────────────────────────────────────────────────────────────┐
│  BRANCHNODE DATA STRUCTURE                                            │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  name:        string       // Branch name                             │
│  commit:      string       // HEAD commit SHA                         │
│  x:           number       // Horizontal position                     │
│  y:           number       // Vertical position                       │
│  isHead:      boolean      // Is this HEAD?                           │
│  isCurrent:   boolean      // Current branch?                         │
│  isRemote:    boolean      // Remote tracking branch?                 │
│  upstream:    string?      // Upstream reference (optional)           │
│  aheadBehind: {            // Sync status (optional)                  │
│    ahead:  number                                                     │
│    behind: number                                                     │
│  }?                                                                   │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

​
Missing Fields for DAG Visualization

Two critical fields are absent:
  1. parents: Vec<String> - Without parent references, we cannot show:
    • Merge commit relationships
    • Branch divergence points
    • True development history flow
    • AI’s commit decision tree
  2. lane: usize - Without lane assignment, we cannot:
    • Position commits visually without overlap
    • Show parallel development streams
    • Distinguish simultaneous AI work streams

​
Visualization Mode Comparison

​
Current Mode: Branch-Level Only

CURRENT VISUALIZATION (Branch-Level):

    main *---------------------*
              \
               \    feature/a *----*
                \              \
                 \              feature/b *

    Shows: Branch tips and merge points
    Hides: Individual commits between branches

​
Target Mode: Commit-Level DAG

TARGET VISUALIZATION (Commit-Level DAG):

    Lane 0        Lane 1        Lane 2

    * c1
    |
    * c2
    +-------------* c3
    |             |
    * c4          * c5
    |             |
    * c6          +-------------* c7
    |             |             |
    +-------------+-------------+ (merge)
    |             |             |
    * c8          * c9          * c10

    Shows: Every commit with parent relationships
    Shows: Lane assignment for visual clarity
    Shows: Merge points with multiple parents

​
Backend Limitations

The current Rust backend provides branch relationship data but lacks commit-level capabilities: What it DOES:
  • Lists all branches
  • Gets branch HEAD SHA
  • Detects ahead/behind status
  • Finds merge base
  • Branch-to-branch connections
What it LACKS:
  • Commit iteration
  • Parent SHA retrieval
  • Lane assignment logic
  • DAG traversal
  • Commit-level connections
DATA FLOW (Current):

Repository
    │
    v
Branch Iterator ──> BranchInfo[] ──> JSON Response
                                    (Branch-level only)

DATA FLOW (Needed):

Repository
    │
    v
Commit Walker ──> CommitGraphNode[] ──> Lane Assignment ──> JSON
    │                                                    (Commit-level)
    └──> Parent Traversal

​
Frontend Rendering

​
Current SVG Structure

<svg width="800" height="600">
  |
  +-- <path class="connection">  (Bezier curve connecting branches)
  |
  +-- <g class="branch-node">
  |   |
  |   +-- <circle>  (Branch indicator)
  |   +-- <text>main</text>  (Branch label)
  |
  +-- <g class="branch-node">
  |   +-- <circle>
  |   +-- <text>feature</text>
  |
  +-- ... more nodes ...

</svg>

CURRENT: ~10-20 nodes per view (branches only)
TARGET:  ~50-100+ nodes per view (all commits)

​
Gap Analysis for THE CENTER

​
Transparency Gaps

WHAT HUMAN NEEDS TO SEE          |  WHAT CURRENT SYSTEM SHOWS
(For effective feedback)         |  (Branch-level only)
---------------------------------+-------------------------

X Individual AI commits          |  V Branch names
X Commit messages                |  V Branch tips only
X Parent-child relationships     |  V Merge/diverge indicators
X Parallel development paths     |  X Hidden between branches
X Commit timestamp ordering      |  X Not shown
X Merge commit complexity        |  X Single connection shown

​
Feedback Loop Impairment

THE CENTER REQUIREMENT:
Human sees AI work → Human understands → Human provides feedback

CURRENT SYSTEM BREAKS THIS LOOP:

Step 1: AI creates 50 commits across 3 branches
    │
Step 2: Current system shows: 3 branch nodes, 2 connections
    │
Step 3: Human sees: "There are 3 branches"
    │
Step 4: Human cannot provide specific feedback because:
    ├── Cannot see which commits did what
    ├── Cannot see commit order
    ├── Cannot see merge decisions
    └── Cannot see parallel work streams

RESULT: Feedback loop efficiency < 10%
        (Human can only comment on branch names, not actual work)

​
Feedback Loop Efficiency

CURRENT STATE (Branch-Level):

AI Work ────────────────────────────────────────> Transparency
100 commits                                       3 branches shown
                                                      │
                                                      v
                                     Human Understanding: ~3%
                                     (Can see: 3 branch names)
                                                      │
                                                      v
                                     Feedback Quality: ~3%
                                     ("Maybe merge feature branch?")

────────────────────────────────────────────────────────────────

TARGET STATE (Commit-Level DAG):

AI Work ────────────────────────────────────────> Transparency
100 commits                                       100 commits shown
                                                  + parent links
                                                  + lanes
                                                      │
                                                      v
                                     Human Understanding: ~80%
                                     (Can see: all decisions)
                                                      │
                                                      v
                                     Feedback Quality: ~80%
                                     ("Commit 47 approach is wrong")

​
Performance Considerations

​
Current Performance Profile

CURRENT PERFORMANCE:

Data Volume:
├── Branches per repo: 5-50 (typical)
├── Connections: 5-100
├── SVG nodes: 10-150
└── Render time: <100ms

Scalability:
├── Large repos (1000+ branches): May lag
├── No virtualization
└── Full SVG re-render on update

​
Upgrade Performance Implications

Commit-level visualization will increase data volume significantly: 
TARGET PERFORMANCE REQUIREMENTS:

Data Volume:
├── Commits per view: 50-500
├── Connections: 50-1000
├── SVG nodes: 100-1000
└── Target render time: <200ms

Mitigation Strategies:
├── Pagination (load 50 commits at a time)
├── Virtual scrolling
├── Lazy connection rendering
└── WebGL for large graphs (future)

​
Technology Stack

The current implementation uses:
LayerTechnologyPurpose
BackendRust + git2-rsGit operations
IPCTauri invoke/emitFrontend-backend communication
FrontendTypeScriptUI logic
RenderingSVG DOMVector graphics
StylingCSSVisual styling
The upgrade requires no new technologies - only enhanced capabilities within the existing stack.

​
Summary

​
Current State

  1. Exists as: git-branch-diagram-viewer.ts (2,331 lines) + Rust backend (360 lines)
  2. Shows: Branch-level relationships only
  3. Hides: Individual commits, parent relationships, lane assignments
  4. Limits: THE CENTER’s Human ◈ AI feedback loop effectiveness

​
Gap Summary

AspectCurrentRequiredGap
GranularityBranch-levelCommit-levelHigh
Parent trackingNoneFull DAGCritical
Visual positioningBranch layoutLane algorithmHigh
Transparency~3% of AI work visible~80% targetCritical

​
Upgrade Necessity

The upgrade is necessary because:
  1. THE CENTER requires complete transparency
  2. Human ◈ AI feedback loop needs granular visibility
  3. Current implementation hides 97% of commit-level information
  4. Monokinetics demands Human and AI operate as ONE motion

​
THE CENTER

​
How This Analysis Serves the Human ◈ AI Feedback Loop

This chapter contributes by:

1. TRANSPARENCY
   ├── Documents current implementation completely
   ├── Identifies exactly what is visible vs hidden
   └── Establishes baseline for improvement measurement

2. VISUALIZATION
   ├── Shows current architecture in diagrams
   ├── Compares branch-level vs commit-level approaches
   └── Illustrates gap between current and target

3. FEEDBACK ENABLEMENT
   ├── Quantifies feedback loop efficiency (~3% current)
   ├── Defines target efficiency (~80%)
   └── Establishes upgrade criteria

CONNECTION TO MONOKINETICS:
This analysis enables Human to understand current system limitations,
so Human can provide effective feedback on upgrade requirements.
This IS the feedback loop in action.

Next: Upgrade Requirements

Documenting all requirements for the Git Commit Graph upgrade