# syamchand123/glassmarble architecture

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

- Interactive diagram: https://gitdiagram.com/syamchand123/glassmarble
- Repository: https://github.com/syamchand123/glassmarble

## Overview

GlassMarble is a local-first codebase architecture graph tool. Its main workflow is `gmb analyze`: source files are parsed, normalized into a common representation, aggregated and semantically linked, then committed as the Architecture Knowledge Graph (AKG). Product capabilities derive diagrams, dependency and drift findings, impact answers, grounded AI responses, and living documentation from that graph; intelligence can also produce snapshots and architectural change events. The README documents the analysis stages and capabilities; sampled source supports the documentation, diagram, AI, and intelligence internals, but not every CLI handler or subsystem connection.

Main entry points: [`internal/akg/schema_v3.go`](https://github.com/syamchand123/glassmarble/blob/main/internal/akg/schema_v3.go) (Architecture graph), [`cmd/root.go`](https://github.com/syamchand123/glassmarble/blob/main/cmd/root.go) (CLI commands), [`internal/ai_engine/engine.go`](https://github.com/syamchand123/glassmarble/blob/main/internal/ai_engine/engine.go) (Grounded AI), [`internal/doc_engine/doc_engine.go`](https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/doc_engine.go) (Documentation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_cli["CLI commands<br/>[root.go]"]
  node_mcp["MCP server<br/>[server.go]"]
end

subgraph group_graphbuild["Graph construction"]
  node_ingest["Source ingestion<br/>[engine.go]"]
  node_normalize["GAST normalization<br/>[normalizer.go]"]
  node_aggregate["Topology aggregation<br/>[aggregator.go]"]
  node_link["Semantic linking<br/>[linker.go]"]
end

subgraph group_insight["Architecture insight"]
  node_intelligence["Architecture intelligence<br/>[engine.go]"]
end

subgraph group_outputs["Graph capabilities"]
  node_visualize["Diagram pipeline<br/>[pipeline.go]"]
  node_vizengine["Diagram extraction and rendering<br/>[renderer.go]"]
  node_impact["Impact analysis<br/>[analyzer.go]"]
  node_drift["Drift analysis<br/>[drift.go]"]
  node_linter["Architecture lint<br/>[engine.go]"]
  node_ai["Grounded AI<br/>[engine.go]"]
  node_docs["Documentation engine<br/>[doc_engine.go]"]
  node_renderer["Documentation renderer<br/>[engine.go]"]
end

subgraph group_state["Local state"]
  node_akg[("Architecture graph<br/>[schema_v3.go]")]
  node_timeline[("Snapshots and timeline<br/>[store.go]")]
  node_docstore[("Documentation state<br/>[store_sqlite.go]")]
end

node_engineer(("Engineer"))
node_providers{{"LLM providers"}}
node_repository["Source repository"]

node_engineer -->|"runs commands"| node_cli
node_engineer -.->|"uses tools"| node_mcp
node_repository -->|"reads source"| node_ingest
node_cli -->|"starts analysis"| node_ingest
node_ingest -->|"parsed output"| node_normalize
node_normalize -->|"normalized code"| node_aggregate
node_aggregate -->|"topology"| node_link
node_link -->|"commits graph"| node_akg
node_akg -->|"analyzes graph"| node_intelligence
node_intelligence -->|"builds snapshots"| node_timeline
node_akg -->|"supplies graph"| node_visualize
node_visualize -->|"builds diagrams"| node_vizengine
node_akg -->|"supports analysis"| node_impact
node_akg -->|"supports analysis"| node_drift
node_akg -->|"checks rules"| node_linter
node_cli -->|"asks questions"| node_ai
node_ai -->|"retrieves evidence"| node_akg
node_ai -.->|"sends requests"| node_providers
node_cli -->|"runs documentation"| node_docs
node_docs -->|"grounds documents"| node_akg
node_docs -->|"renders sections"| node_renderer
node_renderer -.->|"requests prose"| node_providers
node_renderer -->|"persists state"| node_docstore
node_mcp -->|"exposes graph tools"| node_akg

click node_cli "https://github.com/syamchand123/glassmarble/blob/main/cmd/root.go"
click node_mcp "https://github.com/syamchand123/glassmarble/blob/main/internal/mcp/server.go"
click node_ingest "https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/ingest/engine.go"
click node_normalize "https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/normalize/normalizer.go"
click node_aggregate "https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/aggregate/aggregator.go"
click node_link "https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/link/linker.go"
click node_akg "https://github.com/syamchand123/glassmarble/blob/main/internal/akg/schema_v3.go"
click node_intelligence "https://github.com/syamchand123/glassmarble/blob/main/internal/arch_intelligence/engine.go"
click node_timeline "https://github.com/syamchand123/glassmarble/blob/main/internal/arch_timeline/store.go"
click node_visualize "https://github.com/syamchand123/glassmarble/blob/main/internal/product/pipeline.go"
click node_vizengine "https://github.com/syamchand123/glassmarble/blob/main/internal/visualization_engine/renderer.go"
click node_impact "https://github.com/syamchand123/glassmarble/blob/main/internal/impact_analyzer/analyzer.go"
click node_drift "https://github.com/syamchand123/glassmarble/blob/main/internal/drift/drift.go"
click node_linter "https://github.com/syamchand123/glassmarble/blob/main/internal/arch_linter/engine.go"
click node_ai "https://github.com/syamchand123/glassmarble/blob/main/internal/ai_engine/engine.go"
click node_docs "https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/doc_engine.go"
click node_renderer "https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/renderer/engine.go"
click node_docstore "https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/storage/store_sqlite.go"

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_mcp toneBlue
class node_ingest,node_normalize,node_aggregate,node_link toneAmber
class node_intelligence toneMint
class node_visualize,node_vizengine,node_impact,node_drift,node_linter,node_ai,node_docs,node_renderer toneRose
class node_akg,node_timeline,node_docstore,node_engineer,node_providers,node_repository toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/syamchand123/glassmarble/blob/main/cmd/root.go): `cmd/root.go`
- [MCP server](https://github.com/syamchand123/glassmarble/blob/main/internal/mcp/server.go): `internal/mcp/server.go`

### Graph construction

- [Source ingestion](https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/ingest/engine.go): `internal/code_analysis_engine/ingest/engine.go`
- [GAST normalization](https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/normalize/normalizer.go): `internal/code_analysis_engine/normalize/normalizer.go`
- [Topology aggregation](https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/aggregate/aggregator.go): `internal/code_analysis_engine/aggregate/aggregator.go`
- [Semantic linking](https://github.com/syamchand123/glassmarble/blob/main/internal/code_analysis_engine/link/linker.go): `internal/code_analysis_engine/link/linker.go`

### Architecture insight

- [Architecture intelligence](https://github.com/syamchand123/glassmarble/blob/main/internal/arch_intelligence/engine.go): `internal/arch_intelligence/engine.go`

### Graph capabilities

- [Diagram pipeline](https://github.com/syamchand123/glassmarble/blob/main/internal/product/pipeline.go): `internal/product/pipeline.go`
- [Diagram extraction and rendering](https://github.com/syamchand123/glassmarble/blob/main/internal/visualization_engine/renderer.go): `internal/visualization_engine/renderer.go`
- [Impact analysis](https://github.com/syamchand123/glassmarble/blob/main/internal/impact_analyzer/analyzer.go): `internal/impact_analyzer/analyzer.go`
- [Drift analysis](https://github.com/syamchand123/glassmarble/blob/main/internal/drift/drift.go): `internal/drift/drift.go`
- [Architecture lint](https://github.com/syamchand123/glassmarble/blob/main/internal/arch_linter/engine.go): `internal/arch_linter/engine.go`
- [Grounded AI](https://github.com/syamchand123/glassmarble/blob/main/internal/ai_engine/engine.go): `internal/ai_engine/engine.go`
- [Documentation engine](https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/doc_engine.go): `internal/doc_engine/doc_engine.go`
- [Documentation renderer](https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/renderer/engine.go): `internal/doc_engine/renderer/engine.go`

### Local state

- [Architecture graph](https://github.com/syamchand123/glassmarble/blob/main/internal/akg/schema_v3.go): `internal/akg/schema_v3.go`
- [Snapshots and timeline](https://github.com/syamchand123/glassmarble/blob/main/internal/arch_timeline/store.go): `internal/arch_timeline/store.go`
- [Documentation state](https://github.com/syamchand123/glassmarble/blob/main/internal/doc_engine/storage/store_sqlite.go): `internal/doc_engine/storage/store_sqlite.go`

### Other components

- **Engineer**
- **LLM providers**
- **Source repository**

## Connections

- Engineer → CLI commands: runs commands
- Engineer → MCP server: uses tools
- Source repository → Source ingestion: reads source
- CLI commands → Source ingestion: starts analysis
- Source ingestion → GAST normalization: parsed output
- GAST normalization → Topology aggregation: normalized code
- Topology aggregation → Semantic linking: topology
- Semantic linking → Architecture graph: commits graph
- Architecture graph → Architecture intelligence: analyzes graph
- Architecture intelligence → Snapshots and timeline: builds snapshots
- Architecture graph → Diagram pipeline: supplies graph
- Diagram pipeline → Diagram extraction and rendering: builds diagrams
- Architecture graph → Impact analysis: supports analysis
- Architecture graph → Drift analysis: supports analysis
- Architecture graph → Architecture lint: checks rules
- CLI commands → Grounded AI: asks questions
- Grounded AI → Architecture graph: retrieves evidence
- Grounded AI → LLM providers: sends requests
- CLI commands → Documentation engine: runs documentation
- Documentation engine → Architecture graph: grounds documents
- Documentation engine → Documentation renderer: renders sections
- Documentation renderer → LLM providers: requests prose
- Documentation renderer → Documentation state: persists state
- MCP server → Architecture graph: exposes graph tools