# go-gost/core architecture

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

- Interactive diagram: https://gitdiagram.com/go-gost/core
- Repository: https://github.com/go-gost/core

## Overview

##### Project Type & Purpose
- The project is a Go-based core library that provides networking, routing, and service connectivity functionality.
- It appears to be a modular library supporting various stages of network request handling, including admission control, authentication, chain-of-responsibility routing, connection management, service discovery, and instrumentation (e.g., logging, metrics, and observation).
- The lack of a dedicated “frontend” or “backend” folder shows that this is not a full-stack application but rather a low-level, infrastructure-oriented codebase intended to be integrated into larger systems.

##### Analyzing the File Structure
- Top-Level Directories: Many directories (such as admission, auth, bypass, chain, connector, dialer, handler, ingress, limiter, listener, etc.) indicate that the design is decomposed into specific responsibilities or “modules.”
- Core Modules:
- Chain (chain.go, node.go, route.go, router.go, transport.go): Likely handles the chain of processing – a pipeline where each “node” or “route” represents a processing stage.
- Ingress & Listener (ingress/ingress.go, listener/listener.go): Components that accept incoming connections or requests.
- Dialer & Connector: Responsible for outgoing connections and binding mechanisms.
- Limiter (with both connection, rate, and traffic limiter subdirectories): Implements rate-limiting and traffic control.
- Service, Registry, Resolver, and SD: Likely deal with service discovery, registration, and resolution.
- Authentication, Admission, Bypass: Modules addressing security–verifying or filtering incoming requests.
- Common: Utility components (e.g., bufpool, net) that support networking and memory/buffer efficiencies.
- Logging, Metrics, Observer, Recorder, and Metadata: These modules provide telemetry, observation, and likely audit/recording functionality.
- Routing & Router: Besides the chain, these components may refine route matching and decision making.

##### Specific Elements
- Clear Labels: Every module (e.g., “Ingress”, “Chain”, “Limiter”) should be clearly identified.
▪ Processing components (e.g., Chain, Router, Routing) in another.
▪ Supportive modules (e.g., Logger, Metrics, Common) in a third.
▪ Service management (Registry, Resolver, SD) in yet another.
- Annotations: Optionally add brief notes to explain the role/interactions of components.

##### Final Recommendations
- Don’t overcomplicate by trying to include every file; instead, group similar files under their respective module names as outlined by directory names (e.g., group all components under “limiter” together).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        IN("Ingress"):::entry
        LI("Listener"):::entry
        LOpt("Listener Options"):::entry
    end
    
    %% Security Layer
    subgraph "Security Layer"
        AD("Admission"):::security
        AU("Authentication"):::security
        BY("Bypass"):::security
    end
    
    %% Processing Pipeline
    subgraph "Processing Pipeline"
        CH("Chain Processing"):::processing
        RT("Router & Routing"):::processing
    end
    
    %% Rate Limiter
    subgraph "Rate Limiter"
        LM("Limiter"):::processing
    end
    
    %% Connectivity
    subgraph "Connectivity"
        DI("Dialer"):::connectivity
        DIOpt("Dialer Options"):::connectivity
        CO("Connector"):::connectivity
        COOpt("Connector Options"):::connectivity
    end
    
    %% Service Management
    subgraph "Service Management"
        SE("Service"):::service
        RE("Registry"):::service
        RS("Resolver"):::service
        SD("SD"):::service
        SL("Selector"):::service
    end
    
    %% Observability & Telemetry
    subgraph "Observability & Telemetry"
        LO("Logger"):::observability
        ME("Metrics"):::observability
        OB("Observer"):::observability
        RC("Recorder"):::observability
        MD("Metadata"):::observability
    end
    
    %% Common Utilities
    CU("Common Utilities"):::utility
    
    %% External Services
    EX("External Services"):::external

    %% ------------------
    %% Connections
    %% Entry Points feed into Security Layer and Processing Pipeline
    IN --> AD
    IN --> AU
    IN --> BY
    LI --> LOpt
    LI --> CH

    %% Security Layer to Processing Pipeline
    AD --> CH
    AU --> CH
    BY --> CH

    %% Processing Pipeline flows through Rate Limiter to Router
    CH --> LM
    LM --> RT

    %% Router & Routing drives Connectivity and Service Management
    RT --> DI
    RT --> CO
    RT --> SE
    RT --> RE
    RT --> RS
    RT --> SD
    RT --> SL
    
    %% Connectivity details and external communication
    DI --> DIOpt
    DI --> EX
    CO --> COOpt
    CO --> EX

    %% ------------------
    %% Observability (dotted edges represent monitoring connections)
    CH -.-> LO
    RT -.-> ME
    DI -.-> OB
    CO -.-> RC
    LM -.-> MD

    %% Common Utilities support key components
    IN -.-> CU
    AD -.-> CU
    CH -.-> CU
    RT -.-> CU
    DI -.-> CU
    SE -.-> CU
    LO -.-> CU

    %% ------------------
    %% Click Events
    click IN "https://github.com/go-gost/core/blob/master/ingress/ingress.go"
    click LI "https://github.com/go-gost/core/blob/master/listener/listener.go"
    click LOpt "https://github.com/go-gost/core/blob/master/listener/option.go"
    click AD "https://github.com/go-gost/core/blob/master/admission/admission.go"
    click AU "https://github.com/go-gost/core/blob/master/auth/auth.go"
    click BY "https://github.com/go-gost/core/blob/master/bypass/bypass.go"
    click CH "https://github.com/go-gost/core/blob/master/chain/chain.go"
    click RT "https://github.com/go-gost/core/blob/master/router/router.go"
    click DI "https://github.com/go-gost/core/blob/master/dialer/dialer.go"
    click DIOpt "https://github.com/go-gost/core/blob/master/dialer/option.go"
    click CO "https://github.com/go-gost/core/blob/master/connector/connector.go"
    click COOpt "https://github.com/go-gost/core/blob/master/connector/option.go"
    click LM "https://github.com/go-gost/core/blob/master/limiter/limiter.go"
    click SE "https://github.com/go-gost/core/blob/master/service/service.go"
    click RE "https://github.com/go-gost/core/blob/master/registry/registry.go"
    click RS "https://github.com/go-gost/core/blob/master/resolver/resolver.go"
    click SD "https://github.com/go-gost/core/blob/master/sd/sd.go"
    click SL "https://github.com/go-gost/core/blob/master/selector/selector.go"
    click LO "https://github.com/go-gost/core/blob/master/logger/logger.go"
    click ME "https://github.com/go-gost/core/blob/master/metrics/metrics.go"
    click OB "https://github.com/go-gost/core/blob/master/observer/observer.go"
    click RC "https://github.com/go-gost/core/blob/master/recorder/recorder.go"
    click MD "https://github.com/go-gost/core/blob/master/metadata/metadata.go"
    click CU "https://github.com/go-gost/core/blob/master/common/net/dialer.go"

    %% ------------------
    %% Styles
    classDef entry fill:#bde0fe,stroke:#333,stroke-width:2px;
    classDef security fill:#caffbf,stroke:#333,stroke-width:2px;
    classDef processing fill:#ffc6ff,stroke:#333,stroke-width:2px;
    classDef connectivity fill:#ffdfba,stroke:#333,stroke-width:2px;
    classDef service fill:#ffffba,stroke:#333,stroke-width:2px;
    classDef observability fill:#bae1ff,stroke:#333,stroke-width:2px;
    classDef utility fill:#d3f9d8,stroke:#333,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
