# mfblog/webfrpc architecture

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

- Interactive diagram: https://gitdiagram.com/mfblog/webfrpc
- Repository: https://github.com/mfblog/webfrpc

## Overview

##### Project type and purpose
- This is a full-stack, single-binary application written in Go (Gin) with an embedded Vue3/TailwindCSS frontend.
- Purpose: Provide a friendly web interface to manage an FRP client (frpc) configuration (`frpc.toml`), automatically back up configs, restart the service, install/update the binary, and display logs/status.

##### File structure
Top-level files and scripts:
- main.go, go.mod/sum: Go backend entrypoint & dependencies
- build.sh, install.sh, install-service.sh, start.sh: build/deploy/install/start scripts
- DEPLOYMENT.md, LICENSE, README.md: documentation
- web/index.html: static Vue3 frontend

Key patterns & deployment artifacts:
- Embedded assets: `web/` directory is embedded in the Go binary for single-file deployment.
- Service integration: systemd (`install-service.sh`) and `journalctl` for logs.
- Build variants: “embedded” vs. “normal” (with external `web/` folder).

##### README for architectural insights
- Backend exposes REST API endpoints (`/api/config`, `/api/status`, etc.) for all UI actions.
- On startup, the backend performs system checks (directory, frpc binary, systemd service).
- On save operations, the backend: validates TOML, backs up config, writes `frpc.toml`, restarts `frpc.service`, and reports status/logs.
- Frontend is a SPA loaded from embedded assets, communicates via Axios to the Gin server.

##### Main components & interactions
a. Components
1. User’s browser UI (Vue3 + Tailwind)
2. Embedded web server (Go + Gin)
3. File system (config directory `/usr/local/frp`, TOML, backups, SSL certs)
4. FRP client process (`frpc.service` managed by systemd)
5. OS services: systemd & journalctl
6. Optional external network (the actual FRP server)

b. Relationships & data flows
- Browser ←→ HTTP(S) API calls → Go server
- Go server ↔ File system: read/write `frpc.toml`, backups, SSL files
- Go server ↔ systemd: `systemctl status/restart frpc.service` commands
- Go server ↔ journalctl: fetch logs for UI
- Go server ↔ External FRP server: optional connection test on save

c. Architectural patterns & design principles
- Single-page application fronted by REST API
- CLI orchestration via Go exec calls to systemd/journalctl
- Embedded static assets to simplify deployment (“build-embedded”)
- Transactional config updates: validate → backup → write → restart

d. Technologies & frameworks
- Backend: Go 1.x, Gin framework, go-toml
- Frontend: Vue3 (SPA), Tailwind CSS, Axios
- System integration: systemd (install-service.sh), bash scripts
- Build: go build with `-ldflags` embedding, build.sh

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        BrowserUI["Browser UI<br/>(Vue3 SPA)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        GoServer["Go/Gin Server"]:::backend
        StaticAssets["Embedded Static Assets"]:::backend
        GoServer -->|"serves SPA"| StaticAssets
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        FileSystem["File System<br/>(frpc.toml, backups, SSL)"]:::storage
        Systemd["systemd / frpc.service"]:::os
        Journalctl["journalctl Logs"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        FRPServer["External FRP Server"]:::external
    end

    %% Repository Artifacts
    subgraph "Repository Artifacts"
        direction TB
        MainGo["main.go"]:::code
        GoMod["go.mod"]:::code
        GoSum["go.sum"]:::code
        BuildSh["build.sh"]:::script
        InstallSh["install.sh"]:::script
        InstallServiceSh["install-service.sh"]:::script
        StartSh["start.sh"]:::script
        Readme["README.md"]:::doc
        DeployDoc["DEPLOYMENT.md"]:::doc
    end

    %% Connections
    BrowserUI -->|"Axios HTTP JSON"| GoServer
    GoServer -->|"read/write TOML"| FileSystem
    GoServer -->|"systemctl status/restart frpc.service"| Systemd
    GoServer -->|"journalctl -u frpc.service"| Journalctl
    GoServer -.->|"optional test"| FRPServer

    %% Build flows
    BuildSh -->|build embedded| GoServer
    BuildSh -->|build normal| StaticAssets

    %% Service install/start
    InstallSh --> GoServer
    InstallServiceSh --> Systemd
    StartSh --> GoServer

    %% Documentation references
    Readme --> GoServer
    DeployDoc --> BuildSh

    %% Click Events
    click BrowserUI "https://github.com/mfblog/webfrpc/blob/main/web/index.html"
    click StaticAssets "https://github.com/mfblog/webfrpc/tree/main/web/"
    click MainGo "https://github.com/mfblog/webfrpc/blob/main/main.go"
    click GoMod "https://github.com/mfblog/webfrpc/blob/main/go.mod"
    click GoSum "https://github.com/mfblog/webfrpc/blob/main/go.sum"
    click BuildSh "https://github.com/mfblog/webfrpc/blob/main/build.sh"
    click InstallSh "https://github.com/mfblog/webfrpc/blob/main/install.sh"
    click InstallServiceSh "https://github.com/mfblog/webfrpc/blob/main/install-service.sh"
    click StartSh "https://github.com/mfblog/webfrpc/blob/main/start.sh"
    click Readme "https://github.com/mfblog/webfrpc/blob/main/README.md"
    click DeployDoc "https://github.com/mfblog/webfrpc/blob/main/DEPLOYMENT.md"

    %% Styles
    classDef frontend fill:#88CC88,stroke:#006600,stroke-width:1px
    classDef backend fill:#88BBEE,stroke:#005599,stroke-width:1px
    classDef storage fill:#DDDDDD,stroke:#888888,stroke-width:1px
    classDef os fill:#FFCC88,stroke:#AA7700,stroke-width:1px
    classDef external fill:#EEC8FF,stroke:#9933CC,stroke-width:1px
    classDef code fill:#FFFFFF,stroke:#333333,stroke-width:1px
    classDef script fill:#FFF5CC,stroke:#CCAA55,stroke-width:1px
    classDef doc fill:#F0F0F0,stroke:#888800,stroke-width:1px
```
