# safedep/pmg architecture

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

- Interactive diagram: https://gitdiagram.com/safedep/pmg
- Repository: https://github.com/safedep/pmg

## Overview

PMG is a command-line package-install firewall: developers and coding agents keep using familiar package-manager commands, while PMG intercepts installs, checks threats and cooldown policy, optionally sandboxes execution, and records an audit trail. The per-command flow is the runtime orchestrator; a persistent proxy daemon supports intercepted traffic across ecosystems. The graph preserves documented protections and operational capabilities. Some subsystems are represented from README and index references because their implementation excerpts were not provided.

Main entry points: [`internal/flows/proxy_flow.go`](https://github.com/safedep/pmg/blob/main/internal/flows/proxy_flow.go) (Install flow), [`main.go`](https://github.com/safedep/pmg/blob/main/main.go) (PMG CLI), [`internal/runner/execute.go`](https://github.com/safedep/pmg/blob/main/internal/runner/execute.go) (Command execution), [`internal/proxyserver/server.go`](https://github.com/safedep/pmg/blob/main/internal/proxyserver/server.go) (Persistent proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interception"]
  node_cli["PMG CLI<br/>[main.go]"]
  node_shell["Shell interception<br/>[alias.go]"]
  node_shim["Command shim<br/>[shim.go]"]
end

subgraph group_protection["Install protection"]
  node_flow["Install flow<br/>[proxy_flow.go]"]
  node_pm["Package parsing<br/>[packagemanager.go]"]
  node_intel["Malware analysis<br/>[malysis_query.go]"]
  node_sandbox["Sandbox policy<br/>[apply.go]"]
  node_runner["Command execution<br/>[execute.go]"]
end

subgraph group_network["Registry proxy"]
  node_proxy["Persistent proxy<br/>[server.go]"]
  node_interceptors["Registry interceptors<br/>[pypi_url_parser.go]"]
  node_cert["Proxy certificates<br/>[certmanager.go]"]
end

subgraph group_operations["Audit and operations"]
  node_eventlog[("Local event log<br/>[eventlog.go]")]
  node_audit["Audit system<br/>[audit.go]"]
  node_cloud["Cloud sync<br/>[cloud_client.go]"]
  node_doctor["Setup diagnostics<br/>[doctor.go]"]
end

node_developer(("Developer or agent"))

node_developer -->|"runs install"| node_shell
node_shell -->|"intercepts command"| node_shim
node_developer -->|"manages PMG"| node_cli
node_cli -->|"routes command"| node_flow
node_flow -->|"parses command"| node_pm
node_flow -->|"checks packages"| node_intel
node_flow -->|"starts proxy"| node_proxy
node_flow -->|"executes command"| node_runner
node_runner -->|"applies policy"| node_sandbox
node_proxy -->|"builds interceptors"| node_interceptors
node_proxy -.->|"configures certificates"| node_cert
node_flow -.->|"records events"| node_eventlog
node_cli -->|"initializes audit"| node_audit
node_audit -->|"syncs events"| node_cloud
node_cli -->|"runs diagnostics"| node_doctor
node_interceptors -.->|"checks threat data"| node_intel
node_interceptors -.->|"identifies packages"| node_pm
node_runner -.->|"returns result"| node_developer

click node_cli "https://github.com/safedep/pmg/blob/main/main.go"
click node_shell "https://github.com/safedep/pmg/blob/main/internal/alias/alias.go"
click node_shim "https://github.com/safedep/pmg/blob/main/internal/shim/shim.go"
click node_flow "https://github.com/safedep/pmg/blob/main/internal/flows/proxy_flow.go"
click node_pm "https://github.com/safedep/pmg/blob/main/packagemanager/packagemanager.go"
click node_intel "https://github.com/safedep/pmg/blob/main/analyzer/malysis_query.go"
click node_sandbox "https://github.com/safedep/pmg/blob/main/sandbox/executor/apply.go"
click node_runner "https://github.com/safedep/pmg/blob/main/internal/runner/execute.go"
click node_proxy "https://github.com/safedep/pmg/blob/main/internal/proxyserver/server.go"
click node_interceptors "https://github.com/safedep/pmg/blob/main/proxy/interceptors/pypi_url_parser.go"
click node_cert "https://github.com/safedep/pmg/blob/main/proxy/certmanager/certmanager.go"
click node_eventlog "https://github.com/safedep/pmg/blob/main/internal/eventlog/eventlog.go"
click node_audit "https://github.com/safedep/pmg/blob/main/internal/audit/audit.go"
click node_cloud "https://github.com/safedep/pmg/blob/main/internal/audit/cloud_client.go"
click node_doctor "https://github.com/safedep/pmg/blob/main/cmd/setup/doctor.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_shell,node_shim toneBlue
class node_flow,node_pm,node_intel,node_sandbox,node_runner toneAmber
class node_proxy,node_interceptors,node_cert toneMint
class node_eventlog,node_audit,node_cloud,node_doctor toneRose
class node_developer toneIndigo
```

## Components

### Command interception

- [PMG CLI](https://github.com/safedep/pmg/blob/main/main.go): `main.go`
- [Shell interception](https://github.com/safedep/pmg/blob/main/internal/alias/alias.go): `internal/alias/alias.go`
- [Command shim](https://github.com/safedep/pmg/blob/main/internal/shim/shim.go): `internal/shim/shim.go`

### Install protection

- [Install flow](https://github.com/safedep/pmg/blob/main/internal/flows/proxy_flow.go): `internal/flows/proxy_flow.go`
- [Package parsing](https://github.com/safedep/pmg/blob/main/packagemanager/packagemanager.go): `packagemanager/packagemanager.go`
- [Malware analysis](https://github.com/safedep/pmg/blob/main/analyzer/malysis_query.go): `analyzer/malysis_query.go`
- [Sandbox policy](https://github.com/safedep/pmg/blob/main/sandbox/executor/apply.go): `sandbox/executor/apply.go`
- [Command execution](https://github.com/safedep/pmg/blob/main/internal/runner/execute.go): `internal/runner/execute.go`

### Registry proxy

- [Persistent proxy](https://github.com/safedep/pmg/blob/main/internal/proxyserver/server.go): `internal/proxyserver/server.go`
- [Registry interceptors](https://github.com/safedep/pmg/blob/main/proxy/interceptors/pypi_url_parser.go): `proxy/interceptors/pypi_url_parser.go`
- [Proxy certificates](https://github.com/safedep/pmg/blob/main/proxy/certmanager/certmanager.go): `proxy/certmanager/certmanager.go`

### Audit and operations

- [Local event log](https://github.com/safedep/pmg/blob/main/internal/eventlog/eventlog.go): `internal/eventlog/eventlog.go`
- [Audit system](https://github.com/safedep/pmg/blob/main/internal/audit/audit.go): `internal/audit/audit.go`
- [Cloud sync](https://github.com/safedep/pmg/blob/main/internal/audit/cloud_client.go): `internal/audit/cloud_client.go`
- [Setup diagnostics](https://github.com/safedep/pmg/blob/main/cmd/setup/doctor.go): `cmd/setup/doctor.go`

### Other components

- **Developer or agent**

## Connections

- Developer or agent → Shell interception: runs install (evidence: `README.md`)
- Shell interception → Command shim: intercepts command (evidence: `internal/shim/shim.go`)
- Developer or agent → PMG CLI: manages PMG (evidence: `README.md`)
- PMG CLI → Install flow: routes command (evidence: `main.go`)
- Install flow → Package parsing: parses command (evidence: `internal/flows/proxy_flow.go`)
- Install flow → Malware analysis: checks packages (evidence: `internal/flows/proxy_flow.go`)
- Install flow → Persistent proxy: starts proxy (evidence: `internal/flows/proxy_flow.go`)
- Install flow → Command execution: executes command (evidence: `internal/flows/proxy_flow.go`)
- Command execution → Sandbox policy: applies policy (evidence: `internal/runner/execute.go`)
- Persistent proxy → Registry interceptors: builds interceptors (evidence: `internal/proxyserver/server.go`)
- Persistent proxy → Proxy certificates: configures certificates
- Install flow → Local event log: records events
- PMG CLI → Audit system: initializes audit (evidence: `main.go`)
- Audit system → Cloud sync: syncs events (evidence: `internal/audit/cloud_client.go`)
- PMG CLI → Setup diagnostics: runs diagnostics (evidence: `main.go`)
- Registry interceptors → Malware analysis: checks threat data
- Registry interceptors → Package parsing: identifies packages
- Command execution → Developer or agent: returns result
