# issmirnov/zap architecture

> Architecture diagram of the GitHub repository issmirnov/zap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/issmirnov/zap
- Repository: https://github.com/issmirnov/zap

## Overview

##### Main Components

a. Core Components:
- HTTP Server (Main Service)
- Config Manager (YAML Parser)
- URL Expansion Engine
- DNS Manager (hosts file)
- Health Check System

b. External Interfaces:
- Web Browsers/Clients
- File System (/etc/hosts)
- Configuration File (c.yml)

**[Client Layer]**
**Web Browsers/HTTP Clients**
- ↓
**[Service Layer]**
**HTTP Server (Port 80/8927)**
- ↓
**[Core Processing Layer]**
- Config Manager
- Hot Reload Handler
- URL Expansion Engine
- Path Parser
- Query Handler
- Port Manager
- DNS Manager
- ↓
**[Storage Layer]**
- /etc/hosts
- c.yml Config File

##### Key Elements to Highlight

a. Request Flow:
- Incoming HTTP request path
- 302 redirect response flow
- Demonstrate config reload paths

- Blue: External clients/interfaces
- Green: Core processing components
- Yellow: Configuration components
- Gray: Storage/file system

##### Important Details

a. Component Interactions:
- Config hot-reload mechanism
- DNS management flow
- URL expansion logic flow

b. Technical Specifications:
- Port configurations (80/8927)
- Performance metrics (~160k QPS)
- Host binding (127.0.0.1/0.0.0.0)

##### Implementation Notes

- Simple and efficient 302 redirect mechanism
- Configuration-driven architecture
- File system interaction for DNS management
- Hot-reload capability without service interruption

##### Architectural Patterns

Following patterns:
- Event-driven configuration reloading
- URL pattern matching and expansion
- Hierarchical config structure
- Service isolation and process management

This design should reflect Zap's nature as a high-performance, lightweight service that provides a critical productivity enhancement tool while maintaining simplicity and reliability.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef client fill:#4A90E2,color:white
    classDef core fill:#2ECC71,color:white
    classDef config fill:#F1C40F,color:black
    classDef storage fill:#95A5A6,color:white
    classDef api fill:#E74C3C,color:white

    %% Client Layer
    subgraph Clients
        WB[Web Browsers]:::client
        HC[HTTP Clients]:::client
    end

    %% Service Layer
    subgraph Service
        HS["HTTP Server<br/>(Port 80/8927)"]:::core
        HE["/health Endpoint"]:::api
    end
    click HS "https://github.com/issmirnov/zap/blob/master/cmd/zap/web.go"

    %% Core Processing Layer
    subgraph Core
        direction TB
        CM["Config Manager"]:::core
        HR["Hot Reload Handler"]:::core
        UE["URL Expansion Engine"]:::core
        PP["Path Parser"]:::core
        QH["Query Handler"]:::core
        PM["Port Manager"]:::core
        DM["DNS Manager"]:::core
        DS["Data Structures"]:::core
        TP["Text Processing"]:::core
    end
    click CM "https://github.com/issmirnov/zap/blob/master/cmd/zap/config.go"
    click DS "https://github.com/issmirnov/zap/blob/master/cmd/zap/structs.go"
    click TP "https://github.com/issmirnov/zap/blob/master/cmd/zap/text.go"

    %% Storage Layer
    subgraph Storage
        HF["/etc/hosts"]:::storage
        CF["c.yml Config"]:::storage
    end
    click CF "https://github.com/issmirnov/zap/blob/master/c.yml"

    %% Testing Components
    subgraph Testing
        CT["Config Tests"]:::core
        WT["Web Tests"]:::core
        E2E["E2E Tests"]:::core
    end
    click CT "https://github.com/issmirnov/zap/blob/master/cmd/zap/config_test.go"
    click WT "https://github.com/issmirnov/zap/blob/master/cmd/zap/web_test.go"
    click E2E "https://github.com/issmirnov/zap/blob/master/e2e.sh"

    %% Relationships
    WB --> HS
    HC --> HS
    HS --> HE
    HS --> UE
    UE --> PP
    UE --> QH
    UE --> PM
    CM --> HR
    HR --> CF
    DM --> HF
    CM --> UE
    PP --> TP
    QH --> TP
    
    %% Legend
    subgraph Legend
        L1[Client Components]:::client
        L2[Core Components]:::core
        L3[Config Components]:::config
        L4[Storage Components]:::storage
        L5[API Endpoints]:::api
    end
```
