# cloudwego/abcoder architecture

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

- Interactive diagram: https://gitdiagram.com/cloudwego/abcoder
- Repository: https://github.com/cloudwego/abcoder

## Overview

##### Project type and purpose
- ABCoder is a Go-based CLI SDK for AI-oriented code processing. It ingests source code in various languages, parses it into a universal AST (UniAST), and can emit source code back from that AST. It is neither a web app nor a microservice; it’s a command-line tool & library, focused on language-agnostic code analysis (parsing) and generation (writing).

##### High-level components
a. CLI entrypoint
- main.go: parses args (“parse” vs. “write”), dispatches to the parser or writer.
b. Universal AST layer
- lang/uniast: defines Node, AST structures, parser & writer interfaces.
c. Language-specific modules
- lang/golang/{parser,writer}: Go parser into UniAST and UniAST back to Go.
- lang/rust: Rust parser into UniAST (writer “coming soon”).
- lang/collect: batch collection & export utilities.
- lang/lsp: language server protocol support (for integration).
- lang/patch: AST patching utilities.
d. Utilities & logging
- lang/utils, lang/log: file handling, string utils, error wrapping, logging.
e. Tests & examples
- testdata/: sample Go and Rust repos for integration tests.
- *.go_test.go in each module.
f. Documentation
- docs/: architecture and UniAST spec in Chinese/English.
- README.md: overview, usage.

##### Relationships and interactions
- User invokes `abcoder parse {language} {repo}` (CLI).
→ main.go calls lang/{language}/parser to walk the repo (lang/utils_fs → lang/collect).
→ Parser emits a lang/uniast.AST structure.
→ main.go serializes AST to JSON and writes to stdout.
- User invokes `abcoder write {language} ast.json`.
→ main.go reads JSON into lang/uniast.AST.
→ Calls lang/{language}/writer to generate source files.
→ Writer uses lang/utils and lang/log to output code.
- lang/lsp.client or handler can be used by external LSP servers to operate on AST.

##### Architectural patterns & design principles
- Modular language adapters implementing common interfaces (parser/writer).
- Clean separation of concerns: CLI vs. core AST vs. language implementations.
- Interfaces in lang/uniast ensure new languages can plug in.
- Utilities centralized in lang/utils to avoid duplication.
- Tests co-located with modules for clear coverage.

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI_main["main.go"]:::infra
        CLI_parse["lang/parse.go"]:::infra
        CLI_write["lang/write.go"]:::infra
    end

    %% UniAST Core
    subgraph "UniAST Core"
        Core_ast["ast.go"]:::core
        Core_node["node.go"]:::core
        Core_parser_if["parser.go (Interface)"]:::core
        Core_writer_if["writer.go (Interface)"]:::core
        Core_utils["utils.go"]:::core
    end

    %% Plugins
    subgraph "Parser Plugins"
        Go_parser["Go Parser"]:::ext
        Rust_parser["Rust Parser"]:::ext
    end

    subgraph "Writer Plugins"
        Go_writer["Go Writer"]:::ext
        Rust_writer["Rust Writer (coming soon)"]:::ext
    end

    %% Utilities & Logging
    subgraph "Utilities & Logging"
        Utils["lang/utils & lang/log"]:::infra
    end

    %% Collection & Patch
    subgraph "Collection & Patch"
        Collect["Collect & Export"]:::ext
        Patch["AST Patching"]:::ext
    end

    %% LSP Support
    subgraph "LSP Support"
        LSP["LSP Support"]:::ext
    end

    %% Tests & Documentation
    subgraph "Tests & Docs"
        Tests["Test Files & testdata"]:::gray
        Docs["README & docs"]:::gray
    end

    %% Data Artifacts
    Source["Source Files"]:::data
    AST_json["AST JSON"]:::data

    %% Relationships
    Source -->|"source files"| CLI_parse
    CLI_parse -->|"calls Parser()"| Go_parser
    Go_parser -->|"AST instances"| Core_parser_if
    Core_parser_if --> Core_ast
    Core_ast --> Core_node

    CLI_main --> CLI_parse
    CLI_main --> CLI_write

    CLI_write -->|"reads AST JSON"| AST_json
    AST_json -->|"AST JSON"| Core_writer_if
    Core_writer_if --> Go_writer
    Go_writer -->|"generated code"| Source

    %% Utilities usage
    Go_parser --> Utils
    Go_writer --> Utils
    Rust_parser --> Utils
    Collect --> Utils
    Patch --> Utils
    LSP --> Utils

    %% Core integration
    LSP --> Core_parser_if
    LSP --> Core_writer_if

    %% Future components
    Rust_writer -.->|"planned"| Core_writer_if

    %% Tests & Docs links
    Tests -.-> CLI_parse
    Tests -.-> Core_ast
    Docs -.-> CLI_main

    %% Click Events
    click CLI_main "https://github.com/cloudwego/abcoder/blob/main/main.go"
    click CLI_parse "https://github.com/cloudwego/abcoder/blob/main/lang/parse.go"
    click CLI_write "https://github.com/cloudwego/abcoder/blob/main/lang/write.go"
    click Core_ast "https://github.com/cloudwego/abcoder/blob/main/lang/uniast/ast.go"
    click Core_node "https://github.com/cloudwego/abcoder/blob/main/lang/uniast/node.go"
    click Core_parser_if "https://github.com/cloudwego/abcoder/blob/main/lang/uniast/parser.go"
    click Core_writer_if "https://github.com/cloudwego/abcoder/blob/main/lang/uniast/writer.go"
    click Core_utils "https://github.com/cloudwego/abcoder/blob/main/lang/uniast/utils.go"
    click Go_parser "https://github.com/cloudwego/abcoder/blob/main/lang/golang/parser/parser.go"
    click Go_writer "https://github.com/cloudwego/abcoder/blob/main/lang/golang/writer/write.go"
    click Rust_parser "https://github.com/cloudwego/abcoder/blob/main/lang/rust/ast.go"
    click Collect "https://github.com/cloudwego/abcoder/blob/main/lang/collect/collect.go"
    click Patch "https://github.com/cloudwego/abcoder/blob/main/lang/patch/lib.go"
    click Utils "https://github.com/cloudwego/abcoder/blob/main/lang/utils/files.go"
    click LSP "https://github.com/cloudwego/abcoder/blob/main/lang/lsp/lsp.go"
    click Tests "https://github.com/cloudwego/abcoder/tree/main/testdata/"
    click Docs "https://github.com/cloudwego/abcoder/blob/main/README.md"

    %% Styles
    classDef core fill:#ccffcc,stroke:#336633,color:#336633;
    classDef ext fill:#ccddff,stroke:#223366,color:#223366;
    classDef infra fill:#ffe0b3,stroke:#cc6600,color:#cc6600;
    classDef gray fill:#dddddd,stroke:#888888,color:#888888;
    classDef data fill:#ffe6e6,stroke:#cc3333,color:#cc0000;
```
