# aron-666/titan-pcdn architecture

> Architecture diagram of the GitHub repository aron-666/titan-pcdn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aron-666/titan-pcdn
- Repository: https://github.com/aron-666/titan-pcdn

## Overview

Step 1: Identify the project type and purpose
- This is a CLI-based service management tool (“Titan-PCDN 服務管理腳本”) that automates the deployment and operation of a PCDN agent using Docker and Docker Compose.
- Its goal is one-click deployment, configuration, logs management, and system tuning for a PCDN proxy service.

Step 2: Analyze the file structure
- Top-level scripts:
- `pcdn.sh` – main entrypoint for commands (`start`, `stop`, `config`, `logs`, etc.)
- `_pcdn.sh` – likely internal helper functions or shared logic
- Infrastructure config:
- `docker-compose.yml` – defines the containerized PCDN agent and any sidecar services
- Miscellaneous:
- `.gitignore`, `LICENSE.md`, `README.md`—documentation and version control files

Step 3: Examine the README for insights
- The script installs/uses Docker (with optional Chinese registry).
- Generates configuration in a `conf/` directory:
- `.env` (HOOK_ENABLE, HOOK_REGION)
- `.key` (authorization token)
- Automates system tuning (sysctl, ulimit adjustments).
- Orchestrates containers (startup, shutdown, log streaming) via the CLI.

a. Main components
1. User & CLI layer
– User on Linux host invokes `pcdn.sh` with commands.
2. Automation script layer
– `pcdn.sh` and `_pcdn.sh` contain interactive menus, argument parsing, config-file generation, system tuning logic.
3. Host OS & System services
– Linux kernel, sysctl settings, ulimit adjustments.
4. Container orchestration
– Docker daemon (Engine + API)
– Docker Compose
5. Containers
– PCDN agent container (communicates with remote Titan network)
– (Optional) sidecar or helper container(s), e.g. logging aggregator
6. Configuration volume
– `conf/` directory mounted into containers (.env, .key)
7. External services
– Titan-PCDN remote endpoints (protected by token)
– Docker registry (Docker Hub or China mirror)

b. Relationships & interactions
- User → CLI script: issues commands (`start`, `config`, `logs`, etc.)
- CLI script → OS: applies sysctl/ulimit; writes `conf/.env` and `conf/.key`
- CLI script → Docker Compose: invokes `docker-compose up/down/logs`
- Docker Compose → Docker daemon: orchestrates container lifecycle
- Containers → External Titan-PCDN servers: establish PCDN tunnels
- CLI script → Docker daemon: fetches logs or container status

c. Architectural patterns & design principles
- CLI facade pattern: single script wrapping multiple concerns (install, config, run, logs).
- Infrastructure-as-code: everything automated via shell script + docker-compose.
- Containerization: isolates PCDN agent in Docker, simplifies dependency management.
- Volume mounting for configuration: decouples runtime settings from code.

d. Key technologies & libraries
- Shell scripting (Bash)
- Docker & Docker Compose
- sysctl & ulimit for system tuning
- CLI argument parsing and interactive menus
- External registries (GitHub or Gitee mirrors)

Step 5: Tailored guidelines for this CLI/automation project
- Flow from user input to container deployment.
- Script’s dual responsibility: system prep (sysctl/ulimit) and orchestration (Docker Compose).
- Read/write path to `conf/` volume for token and environment variables.
- Remote PCDN endpoints and how the agent container connects.

- Clear labels for: User, pcdn.sh, OS/system-tuning, Docker Daemon, Docker Compose, Containers, conf volume, External PCDN.
- From User → pcdn.sh
- pcdn.sh → OS (sysctl/ulimit)
- pcdn.sh → Docker Compose → Docker Daemon → Containers
- Containers ↔ External PCDN servers
- conf volume → Containers
- Grey for Host OS & system services
- Orange for orchestration (Docker/Compose)
- Green for running containers
- Red for external network endpoints

Step 7: Emphasize detail and completeness
- Break the script’s functionality into sub-components (install Docker, config generator, lifecycle commands).
- Sysctl/ulimit tuning as a separate labeled step.
- Optional Chinese-mirror flow: flag `-i cn` → alternative registry endpoint.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Linux Host)"]:::external
    User -->|"invokes command"| CLI["pcdn.sh"]:::cli

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["pcdn.sh"]:::cli
        Helper["_pcdn.sh"]:::cli
        CLI -->|"uses helper"| Helper
    end

    %% System Tuning
    Sys["Sysctl & ulimit adjustments"]:::host

    CLI -->|"applies settings"| Sys

    %% Configuration Volume
    Conf["conf/ (.env, .key)"]:::volume
    CLI -->|"writes config"| Conf

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        direction TB
        DCCompose["docker-compose.yml"]:::orchestration
        DockerDaemon["Docker Daemon (Engine & API)"]:::orchestration
        CLI -->|"docker-compose up/down/logs"| DCCompose
        DCCompose -->|"calls API"| DockerDaemon
    end

    %% Containers
    subgraph "Containers" 
        direction TB
        Agent["PCDN Agent Container"]:::container
        Sidecar["Logging Aggregator Container"]:::container
        DockerDaemon -->|"manages"| Agent
        DockerDaemon -->|"manages"| Sidecar
        Conf -->|"mounted volume"| Agent
    end

    %% External Services
    Titan["Titan-PCDN Remote Endpoints"]:::external
    Registry["Docker Registry (Docker Hub / Mirror)"]:::external

    Agent -->|"tunnels to"| Titan
    CLI -->|"optional -i cn registry"| Registry
    DCCompose -->|"pulls images from"| Registry

    %% Documentation & Versioning
    README["README.md"]:::docs
    Gitignore[".gitignore"]:::docs
    License["LICENSE.md"]:::docs

    click CLI "https://github.com/aron-666/titan-pcdn/blob/main/pcdn.sh"
    click Helper "https://github.com/aron-666/titan-pcdn/blob/main/_pcdn.sh"
    click DCCompose "https://github.com/aron-666/titan-pcdn/blob/main/docker-compose.yml"
    click README "https://github.com/aron-666/titan-pcdn/blob/main/README.md"
    click Gitignore "https://github.com/aron-666/titan-pcdn/blob/main/.gitignore"
    click License "https://github.com/aron-666/titan-pcdn/blob/main/LICENSE.md"

    classDef cli fill:#cce5ff,stroke:#3399ff,color:#003366
    classDef host fill:#f2f2f2,stroke:#999999,color:#333333
    classDef orchestration fill:#ffe5cc,stroke:#ff9933,color:#663300
    classDef container fill:#e6ffe6,stroke:#33cc33,color:#006600
    classDef external fill:#ffe6e6,stroke:#ff3333,color:#660000
    classDef volume fill:#ffffcc,stroke:#cccc00,color:#666600
    classDef docs fill:#f9e6ff,stroke:#cc99ff,color:#660066
```
