# podhmo/go-scan architecture

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

- Interactive diagram: https://gitdiagram.com/podhmo/go-scan
- Repository: https://github.com/podhmo/go-scan

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo Go library/CLI tool (“go-scan”) for fast, shallow static analysis of Go code.
- It provides a core Scanner API plus supporting packages (AST walker, import resolution, caching), and ships with two advanced sub-libraries (minigo: mini-interpreter; symgo: symbolic evaluator).
- It’s consumed by other tools (e.g., code generators, API docs), and includes a CLI entrypoint, a testing harness, and many example commands.

##### High-Level Architecture / Main Components
A. Presentation Layer
- CLI / “main.go”
- Examples / “examples/…” (demonstrate usage)
- Docs / “docs/…” (human documentation)
B. Core Library Layer
- goscan.Scanner
– Scanner configuration & API (“WithGoModuleResolver”, “Scan”)
- astwalk
– Shallow AST traversal on go/ast
- scanner
– Tokenizes packages, builds shallow TypeInfo, FunctionInfo, ConstInfo
- importmanager, locator, modulewalker
– Resolve imports, go.mod, go.work, module cache, GOROOT
- cache
– Symbol location caching
- scantest
– Testing helpers and golden-file framework
C. Advanced Sub-Libraries (Consumers of Core)
- minigo
– Mini-Go interpreter (uses goscan to load definitions)
– ffibridge for Go-native interop
– Built-in stdlib package stubs
- symgo
– Symbolic execution engine
– Evaluator, intrinsics, object model
D. Infrastructure Layer
- File system (source files)
- Go toolchain (go/ast, go/parser)
- Module cache / go.mod / go.work
- Persistence (JSON cache file)

##### Relationships and Data Flow
- CLI (main.go) → configures → goscan.Scanner
- Scanner
1. reads file paths / import paths
2. uses locator/modulewalker to find source
3. parses Go AST
4. walks AST (astwalk) to extract types, funcs, consts
5. on-demand resolves cross-package references via importmanager
6. optionally reads/writes cache
7. returns shallow package models to caller
- minigo, symgo
- Depend on Scanner (import “github.com/podhmo/go-scan”)
- Call Scanner.Scan to obtain type definitions
- Execute or symbolically evaluate code based on those definitions
- scantest
- Wraps Scanner.Scan in test harness
- Compares output to “.golden” files

##### Architectural Patterns & Principles
- Layered design: Presentation → Core API → Utility packages → Infrastructure
- Lazy loading / on-demand resolution (minimizes work)
- Shallow scanning: avoids heavy type-checking, uses go/ast only
- Extensibility: ExternalTypeOverrides, plug-in sub-libraries (minigo, symgo)
- Testable: scantest golden tests, unit tests per package

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        CLI["CLI (main.go)"]:::frontend
        Examples["Examples"]:::frontend
        Docs["Documentation"]:::frontend
    end

    subgraph "Core Library Layer"
        Scanner["goscan.Scanner"]:::core
        ASTWalk["astwalk"]:::utility
        ScannerImpl["scanner (impl)"]:::utility
        ScannerModels["scanner models"]:::utility
        ImportManager["importmanager"]:::utility
        Locator["locator"]:::utility
        ModuleWalker["modulewalker"]:::utility
        Cache["cache"]:::utility
        Scantest["scantest"]:::utility
        TestData["scanner/testdata"]:::utility
        IntegrationTests["integration_test"]:::utility
    end

    subgraph "Advanced Sub-Libraries"
        Minigo["minigo"]:::adv
        subgraph "Minigo Components"
            MGInterp["Interpreter"]:::adv
            MGEval["Evaluator"]:::adv
            MGFFI["ffibridge"]:::adv
            MGStd["stdlib stubs"]:::adv
        end
        Symgo["symgo"]:::adv
        subgraph "Symgo Components"
            SGCore["Core"]:::adv
            SGEval["Evaluator"]:::adv
            SGIntr["Intrinsics"]:::adv
            SGObj["Object Model"]:::adv
        end
    end

    subgraph "Infrastructure"
        FileSystem["File System"]:::infra
        GoParser["go/parser"]:::infra
        ASTNode["AST"]:::infra
        ModuleCache["Module Cache"]:::infra
        GoToolchain["Go Toolchain"]:::infra
        JSONCache["JSON Cache File"]:::infra
    end

    CLI -->|"configures"| Scanner
    Examples -->|"uses"| Scanner
    Docs -.->|"references"| Scanner

    Scanner -->|calls| ASTWalk
    Scanner -->|calls| ScannerImpl
    Scanner -->|builds models via| ScannerModels
    Scanner -->|resolves imports with| ImportManager
    Scanner -->|locates sources via| Locator
    Scanner -->|walks modules with| ModuleWalker
    Scanner -->|reads/writes| Cache
    Scanner -->|tested by| Scantest
    Scantest -->|uses| TestData
    Scanner -->|covered by| IntegrationTests

    Minigo -->|imports & calls| Scanner
    MGInterp --> Minigo
    MGEval --> Minigo
    MGFFI --> Minigo
    MGStd --> Minigo

    Symgo -->|imports & calls| Scanner
    SGCore --> Symgo
    SGEval --> Symgo
    SGIntr --> Symgo
    SGObj --> Symgo

    FileSystem -->|provides source| GoParser
    GoParser -->|produces| ASTNode
    ASTNode -->|traversed by| ASTWalk
    ModuleCache -->|used by| ImportManager
    Locator -->|reads| ModuleCache
    Cache -->|persists to| JSONCache

    click CLI "https://github.com/podhmo/go-scan/blob/develop/goscan.go"
    click Examples "https://github.com/podhmo/go-scan/tree/develop/examples/"
    click Docs "https://github.com/podhmo/go-scan/tree/develop/docs/"
    click Scanner "https://github.com/podhmo/go-scan/blob/develop/goscan.go"
    click ASTWalk "https://github.com/podhmo/go-scan/blob/develop/astwalk/astwalk.go"
    click ScannerImpl "https://github.com/podhmo/go-scan/blob/develop/scanner/scanner.go"
    click ScannerModels "https://github.com/podhmo/go-scan/blob/develop/scanner/models.go"
    click ImportManager "https://github.com/podhmo/go-scan/blob/develop/importmanager.go"
    click Locator "https://github.com/podhmo/go-scan/blob/develop/locator/locator.go"
    click ModuleWalker "https://github.com/podhmo/go-scan/blob/develop/modulewalker.go"
    click Cache "https://github.com/podhmo/go-scan/blob/develop/cache.go"
    click Scantest "https://github.com/podhmo/go-scan/blob/develop/scantest/scantest.go"
    click TestData "https://github.com/podhmo/go-scan/tree/develop/scanner/testdata/"
    click IntegrationTests "https://github.com/podhmo/go-scan/tree/develop/integration_test/"
    click Minigo "https://github.com/podhmo/go-scan/blob/develop/minigo/minigo.go"
    click MGEval "https://github.com/podhmo/go-scan/tree/develop/minigo/evaluator/"
    click MGFFI "https://github.com/podhmo/go-scan/tree/develop/minigo/ffibridge/"
    click MGStd "https://github.com/podhmo/go-scan/tree/develop/minigo/stdlib/"
    click Symgo "https://github.com/podhmo/go-scan/blob/develop/symgo/symgo.go"
    click SGEval "https://github.com/podhmo/go-scan/tree/develop/symgo/evaluator/"
    click SGIntr "https://github.com/podhmo/go-scan/tree/develop/symgo/intrinsics/"
    click SGObj "https://github.com/podhmo/go-scan/tree/develop/symgo/object/"

    classDef frontend fill:#ccf,stroke:#888
    classDef core fill:#cce,stroke:#888
    classDef utility fill:#eef,stroke:#888
    classDef adv fill:#fc8,stroke:#888
    classDef infra fill:#ddd,stroke:#888
```
