# yunmin311/gitlineage architecture

> Architecture diagram of the GitHub repository yunmin311/gitlineage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yunmin311/gitlineage
- Repository: https://github.com/yunmin311/gitlineage

## Overview

GitLineage turns a GitHub repository reference into a validated, evidence-backed lineage graph. The main workflow resolves the input, gathers repository metadata, documents, package declarations, submodule entries, Git history and blob evidence, then resolves observations under a relationship ontology and validates the canonical artifact. The same analysis powers a web explorer with queued, cached requests and a presentation view-model. README documentation establishes the product capabilities; some collector and browser details are not shown in source excerpts, so uncertain links are omitted or marked unverified.

Main entry points: [`src/pipeline/analyze.ts`](https://github.com/yunmin311/gitlineage/blob/main/src/pipeline/analyze.ts) (Analyze pipeline), [`src/web/client/app.js`](https://github.com/yunmin311/gitlineage/blob/main/src/web/client/app.js) (Interactive explorer), [`src/pipeline/cached-analyze.ts`](https://github.com/yunmin311/gitlineage/blob/main/src/pipeline/cached-analyze.ts) (Cached analysis), [`src/core/resolver.ts`](https://github.com/yunmin311/gitlineage/blob/main/src/core/resolver.ts) (Relationship resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis workflow"]
  node_cli["CLI commands<br/>[main.ts]"]
  node_pipeline["Analyze pipeline<br/>[analyze.ts]"]
  node_cached_analysis["Cached analysis<br/>[cached-analyze.ts]"]
end

subgraph group_collectors["Evidence collectors"]
  node_github_client["GitHub API client<br/>[client.ts]"]
  node_github_metadata["Fork metadata<br/>[metadata.ts]"]
  node_documents["Document attribution<br/>[attribution.ts]"]
  node_git_history["Git history evidence<br/>[history.ts]"]
  node_git_blobs["Blob identity evidence<br/>[blobs.ts]"]
  node_submodules["Submodule evidence<br/>[collector.ts]"]
  node_package_manifests["Manifest parsing<br/>[manifests.ts]"]
  node_package_collection["Package collection<br/>[collector.ts]"]
  node_registry["Package registries<br/>[registry.ts]"]
end

subgraph group_core["Lineage contract"]
  node_resolver["Relationship resolver<br/>[resolver.ts]"]
  node_policy["Evidence policy<br/>[policy.ts]"]
  node_ontology["Relationship ontology<br/>[ontology.ts]"]
  node_graph_model["Canonical graph model<br/>[model.ts]"]
  node_id_generation["Stable identifiers<br/>[ids.ts]"]
  node_validation["Graph validation<br/>[validate.ts]"]
end

subgraph group_platform["Platform services"]
  node_http["Bounded HTTP<br/>[http.ts]"]
  node_git_runtime["Bounded Git access<br/>[git.ts]"]
  node_cache[("Namespaced cache<br/>[cache.ts]")]
  node_url_safety["Repository URL safety<br/>[url.ts]"]
end

subgraph group_web["Web explorer"]
  node_web_server["HTTP server<br/>[server.ts]"]
  node_scheduler["Analysis scheduler<br/>[scheduler.ts]"]
  node_analysis_store[("Analysis store<br/>[store.ts]")]
  node_view_model["Presentation view-model<br/>[view-model.ts]"]
  node_web_client["Interactive explorer<br/>[app.js]"]
  node_client_render["Graph rendering<br/>[compose.mjs]"]
  node_client_search["Graph search<br/>[search.mjs]"]
  node_client_state["URL view state<br/>[url-state.mjs]"]
end

node_cli_user(("CLI user"))
node_web_user(("Explorer user"))

node_cli_user -->|"runs command"| node_cli
node_cli -->|"runs analysis"| node_pipeline
node_pipeline -->|"resolves input"| node_url_safety
node_pipeline -->|"fetches repository data"| node_github_client
node_pipeline -->|"collects metadata"| node_github_metadata
node_pipeline -->|"collects submodules"| node_submodules
node_pipeline -->|"collects packages"| node_package_collection
node_pipeline -->|"resolves packages"| node_registry
node_pipeline -->|"collects attribution"| node_documents
node_pipeline -->|"collects history"| node_git_history
node_pipeline -.->|"compares blob evidence"| node_git_blobs
node_pipeline -->|"resolves observations"| node_resolver
node_pipeline -->|"validates graph"| node_validation
node_pipeline -->|"configures client"| node_http
node_pipeline -->|"fetches history"| node_git_runtime
node_pipeline -->|"creates cache"| node_cache
node_resolver -->|"checks evidence policy"| node_policy
node_resolver -->|"creates identifiers"| node_id_generation
node_resolver -->|"applies relationship rules"| node_ontology
node_validation -->|"checks relationship rules"| node_ontology
node_http -->|"caches responses"| node_cache
node_http -->|"checks destinations"| node_url_safety
node_git_runtime -->|"uses cached data"| node_cache
node_github_client -->|"fetches API data"| node_http
node_package_collection -->|"parses manifests"| node_package_manifests
node_registry -->|"uses package facts"| node_package_manifests
node_cached_analysis -->|"runs analysis"| node_pipeline
node_cached_analysis -->|"checks cached graph"| node_validation
node_cached_analysis -->|"reads and writes artifacts"| node_cache
node_web_user -->|"explores lineage"| node_web_client
node_web_client -->|"requests graph views"| node_web_server
node_web_server -->|"queues analysis"| node_scheduler
node_web_server -->|"requests cached analysis"| node_cached_analysis
node_web_server -->|"builds presentation view"| node_view_model
node_scheduler -->|"runs analysis jobs"| node_cached_analysis
node_scheduler -->|"stores job state"| node_analysis_store
node_web_client -->|"composes graph"| node_client_render
node_web_client -->|"searches graph"| node_client_search
node_web_client -->|"reads and writes view state"| node_client_state

click node_cli "https://github.com/yunmin311/gitlineage/blob/main/src/cli/main.ts"
click node_pipeline "https://github.com/yunmin311/gitlineage/blob/main/src/pipeline/analyze.ts"
click node_cached_analysis "https://github.com/yunmin311/gitlineage/blob/main/src/pipeline/cached-analyze.ts"
click node_github_client "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/github/client.ts"
click node_github_metadata "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/github/metadata.ts"
click node_documents "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/documents/attribution.ts"
click node_git_history "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/git/history.ts"
click node_git_blobs "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/git/blobs.ts"
click node_submodules "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/submodules/collector.ts"
click node_package_manifests "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/packages/manifests.ts"
click node_package_collection "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/packages/collector.ts"
click node_registry "https://github.com/yunmin311/gitlineage/blob/main/src/collectors/packages/registry.ts"
click node_resolver "https://github.com/yunmin311/gitlineage/blob/main/src/core/resolver.ts"
click node_policy "https://github.com/yunmin311/gitlineage/blob/main/src/core/policy.ts"
click node_ontology "https://github.com/yunmin311/gitlineage/blob/main/src/core/ontology.ts"
click node_graph_model "https://github.com/yunmin311/gitlineage/blob/main/src/core/model.ts"
click node_id_generation "https://github.com/yunmin311/gitlineage/blob/main/src/core/ids.ts"
click node_validation "https://github.com/yunmin311/gitlineage/blob/main/src/core/validate.ts"
click node_http "https://github.com/yunmin311/gitlineage/blob/main/src/platform/http.ts"
click node_git_runtime "https://github.com/yunmin311/gitlineage/blob/main/src/platform/git.ts"
click node_cache "https://github.com/yunmin311/gitlineage/blob/main/src/platform/cache.ts"
click node_url_safety "https://github.com/yunmin311/gitlineage/blob/main/src/platform/url.ts"
click node_web_server "https://github.com/yunmin311/gitlineage/blob/main/src/web/server.ts"
click node_scheduler "https://github.com/yunmin311/gitlineage/blob/main/src/web/analysis/scheduler.ts"
click node_analysis_store "https://github.com/yunmin311/gitlineage/blob/main/src/web/analysis/store.ts"
click node_view_model "https://github.com/yunmin311/gitlineage/blob/main/src/web/view-model.ts"
click node_web_client "https://github.com/yunmin311/gitlineage/blob/main/src/web/client/app.js"
click node_client_render "https://github.com/yunmin311/gitlineage/blob/main/src/web/client/lib/compose.mjs"
click node_client_search "https://github.com/yunmin311/gitlineage/blob/main/src/web/client/lib/search.mjs"
click node_client_state "https://github.com/yunmin311/gitlineage/blob/main/src/web/client/lib/url-state.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_pipeline,node_cached_analysis,node_cli_user,node_web_user toneBlue
class node_github_client,node_github_metadata,node_documents,node_git_history,node_git_blobs,node_submodules,node_package_manifests,node_package_collection,node_registry toneAmber
class node_resolver,node_policy,node_ontology,node_graph_model,node_id_generation,node_validation toneMint
class node_http,node_git_runtime,node_cache,node_url_safety toneRose
class node_web_server,node_scheduler,node_analysis_store,node_view_model,node_web_client,node_client_render,node_client_search,node_client_state toneIndigo
```

## Components

### Analysis workflow

- [CLI commands](https://github.com/yunmin311/gitlineage/blob/main/src/cli/main.ts): `src/cli/main.ts`
- [Analyze pipeline](https://github.com/yunmin311/gitlineage/blob/main/src/pipeline/analyze.ts): `src/pipeline/analyze.ts`
- [Cached analysis](https://github.com/yunmin311/gitlineage/blob/main/src/pipeline/cached-analyze.ts): `src/pipeline/cached-analyze.ts`

### Evidence collectors

- [GitHub API client](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/github/client.ts): `src/collectors/github/client.ts`
- [Fork metadata](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/github/metadata.ts): `src/collectors/github/metadata.ts`
- [Document attribution](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/documents/attribution.ts): `src/collectors/documents/attribution.ts`
- [Git history evidence](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/git/history.ts): `src/collectors/git/history.ts`
- [Blob identity evidence](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/git/blobs.ts): `src/collectors/git/blobs.ts`
- [Submodule evidence](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/submodules/collector.ts): `src/collectors/submodules/collector.ts`
- [Manifest parsing](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/packages/manifests.ts): `src/collectors/packages/manifests.ts`
- [Package collection](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/packages/collector.ts): `src/collectors/packages/collector.ts`
- [Package registries](https://github.com/yunmin311/gitlineage/blob/main/src/collectors/packages/registry.ts): `src/collectors/packages/registry.ts`

### Lineage contract

- [Relationship resolver](https://github.com/yunmin311/gitlineage/blob/main/src/core/resolver.ts): `src/core/resolver.ts`
- [Evidence policy](https://github.com/yunmin311/gitlineage/blob/main/src/core/policy.ts): `src/core/policy.ts`
- [Relationship ontology](https://github.com/yunmin311/gitlineage/blob/main/src/core/ontology.ts): `src/core/ontology.ts`
- [Canonical graph model](https://github.com/yunmin311/gitlineage/blob/main/src/core/model.ts): `src/core/model.ts`
- [Stable identifiers](https://github.com/yunmin311/gitlineage/blob/main/src/core/ids.ts): `src/core/ids.ts`
- [Graph validation](https://github.com/yunmin311/gitlineage/blob/main/src/core/validate.ts): `src/core/validate.ts`

### Platform services

- [Bounded HTTP](https://github.com/yunmin311/gitlineage/blob/main/src/platform/http.ts): `src/platform/http.ts`
- [Bounded Git access](https://github.com/yunmin311/gitlineage/blob/main/src/platform/git.ts): `src/platform/git.ts`
- [Namespaced cache](https://github.com/yunmin311/gitlineage/blob/main/src/platform/cache.ts): `src/platform/cache.ts`
- [Repository URL safety](https://github.com/yunmin311/gitlineage/blob/main/src/platform/url.ts): `src/platform/url.ts`

### Web explorer

- [HTTP server](https://github.com/yunmin311/gitlineage/blob/main/src/web/server.ts): `src/web/server.ts`
- [Analysis scheduler](https://github.com/yunmin311/gitlineage/blob/main/src/web/analysis/scheduler.ts): `src/web/analysis/scheduler.ts`
- [Analysis store](https://github.com/yunmin311/gitlineage/blob/main/src/web/analysis/store.ts): `src/web/analysis/store.ts`
- [Presentation view-model](https://github.com/yunmin311/gitlineage/blob/main/src/web/view-model.ts): `src/web/view-model.ts`
- [Interactive explorer](https://github.com/yunmin311/gitlineage/blob/main/src/web/client/app.js): `src/web/client/app.js`
- [Graph rendering](https://github.com/yunmin311/gitlineage/blob/main/src/web/client/lib/compose.mjs): `src/web/client/lib/compose.mjs`
- [Graph search](https://github.com/yunmin311/gitlineage/blob/main/src/web/client/lib/search.mjs): `src/web/client/lib/search.mjs`
- [URL view state](https://github.com/yunmin311/gitlineage/blob/main/src/web/client/lib/url-state.mjs): `src/web/client/lib/url-state.mjs`

### Other components

- **CLI user**
- **Explorer user**

## Connections

- CLI user → CLI commands: runs command (evidence: `README.md`)
- CLI commands → Analyze pipeline: runs analysis (evidence: `src/cli/main.ts`)
- Analyze pipeline → Repository URL safety: resolves input (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → GitHub API client: fetches repository data (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Fork metadata: collects metadata (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Submodule evidence: collects submodules (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Package collection: collects packages (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Package registries: resolves packages (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Document attribution: collects attribution (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Git history evidence: collects history (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Blob identity evidence: compares blob evidence (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Relationship resolver: resolves observations (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Graph validation: validates graph (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Bounded HTTP: configures client (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Bounded Git access: fetches history (evidence: `src/pipeline/analyze.ts`)
- Analyze pipeline → Namespaced cache: creates cache (evidence: `src/pipeline/analyze.ts`)
- Relationship resolver → Evidence policy: checks evidence policy (evidence: `src/core/resolver.ts`)
- Relationship resolver → Stable identifiers: creates identifiers (evidence: `src/core/resolver.ts`)
- Relationship resolver → Relationship ontology: applies relationship rules
- Graph validation → Relationship ontology: checks relationship rules (evidence: `src/core/validate.ts`)
- Bounded HTTP → Namespaced cache: caches responses (evidence: `src/platform/http.ts`)
- Bounded HTTP → Repository URL safety: checks destinations (evidence: `src/platform/http.ts`)
- Bounded Git access → Namespaced cache: uses cached data (evidence: `src/platform/git.ts`)
- GitHub API client → Bounded HTTP: fetches API data (evidence: `src/collectors/github/client.ts`)
- Package collection → Manifest parsing: parses manifests (evidence: `src/collectors/packages/collector.ts`)
- Package registries → Manifest parsing: uses package facts (evidence: `src/collectors/packages/registry.ts`)
- Cached analysis → Analyze pipeline: runs analysis (evidence: `src/pipeline/cached-analyze.ts`)
- Cached analysis → Graph validation: checks cached graph (evidence: `src/pipeline/cached-analyze.ts`)
- Cached analysis → Namespaced cache: reads and writes artifacts (evidence: `src/pipeline/cached-analyze.ts`)
- Explorer user → Interactive explorer: explores lineage (evidence: `README.md`)
- Interactive explorer → HTTP server: requests graph views (evidence: `README.md`)
- HTTP server → Analysis scheduler: queues analysis (evidence: `src/web/server.ts`)
- HTTP server → Cached analysis: requests cached analysis (evidence: `src/web/server.ts`)
- HTTP server → Presentation view-model: builds presentation view (evidence: `src/web/server.ts`)
- Analysis scheduler → Cached analysis: runs analysis jobs (evidence: `src/web/analysis/scheduler.ts`)
- Analysis scheduler → Analysis store: stores job state (evidence: `src/web/analysis/scheduler.ts`)
- Interactive explorer → Graph rendering: composes graph (evidence: `src/web/client/app.js`)
- Interactive explorer → Graph search: searches graph (evidence: `src/web/client/app.js`)
- Interactive explorer → URL view state: reads and writes view state (evidence: `src/web/client/app.js`)
