# uservseatb/apinfra architecture

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

- Interactive diagram: https://gitdiagram.com/uservseatb/apinfra
- Repository: https://github.com/uservseatb/apinfra

## Overview

apinfra is a single-host, pull-model GitOps agent for Docker Compose applications, managed Nginx routing, and automatic TLS. Each run loads host settings and the selected namespace from Git, validates configuration before making changes, applies Docker state, processes ingress and certificates, then prunes unused images. The graph follows the documented cycle and sampled composition root; several subsystem internals are unsampled, so their detailed calls are omitted rather than inferred.

Main entry points: [`internal/app/update.go`](https://github.com/uservseatb/apinfra/blob/main/internal/app/update.go) (Service wiring), [`internal/domain/deployment/service.go`](https://github.com/uservseatb/apinfra/blob/main/internal/domain/deployment/service.go) (Update cycle), [`internal/domain/docker/service.go`](https://github.com/uservseatb/apinfra/blob/main/internal/domain/docker/service.go) (Compose orchestration), [`internal/infrastructure/adapters/git_source.go`](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/git_source.go) (Git config loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_entry["Update entrypoint<br/>[main.go]"]
  node_composition["Service wiring<br/>[update.go]"]
end

subgraph group_desired["Desired state"]
  node_hostconfig["Host configuration<br/>[host.go]"]
  node_gitconfig["Git config loader<br/>[git_source.go]"]
  node_gitrepo["Git repository access<br/>[repo.go]"]
  node_settings["Project settings<br/>[settings.go]"]
end

subgraph group_deploy["Deployment"]
  node_cycle["Update cycle<br/>[service.go]"]
  node_docker["Compose orchestration<br/>[service.go]"]
  node_compose["Compose validation<br/>[compose.go]"]
end

subgraph group_ingress["Ingress and TLS"]
  node_nginx["Ingress routing<br/>[service.go]"]
  node_nginxrender["Nginx rendering<br/>[render.go]"]
  node_certs["Certificate management<br/>[service.go]"]
  node_acme["ACME providers<br/>[client.go]"]
end

subgraph group_infra["Host adapters"]
  node_stackfs["Stack filesystem<br/>[stack_fs.go]"]
  node_cli["Docker and CLI adapter<br/>[cli_runner.go]"]
  node_vhostfs["Virtual-host filesystem<br/>[vhost_fs.go]"]
  node_acmebridge["ACME adapter<br/>[acme_bridge.go]"]
  node_state[("Certificate state<br/>[yaml_repo.go]")]
  node_layout["Host layout<br/>[layout.go]"]
  node_events[("Event records<br/>[events.go]")]
end

node_operator(("Host operator"))

node_operator -->|"starts run"| node_entry
node_entry -->|"runs update"| node_composition
node_composition -->|"loads settings"| node_hostconfig
node_composition -->|"executes cycle"| node_cycle
node_composition -->|"wires service"| node_docker
node_composition -->|"wires source"| node_gitconfig
node_composition -->|"wires layout"| node_layout
node_composition -->|"wires service"| node_certs
node_composition -->|"wires adapter"| node_acmebridge
node_composition -->|"wires repository"| node_state
node_composition -->|"wires ingress"| node_nginx
node_gitconfig -->|"loads clone"| node_gitrepo
node_gitconfig -->|"reads projects"| node_settings
node_cycle -->|"prepares directories"| node_layout
node_cycle -->|"loads workspace"| node_gitconfig
node_cycle -->|"validates and applies"| node_docker
node_cycle -->|"processes routing"| node_nginx
node_cycle -->|"prunes images"| node_docker
node_docker -->|"validates projects"| node_compose
node_nginx -->|"renders configuration"| node_nginxrender
node_certs -->|"issues certificates"| node_acmebridge
node_acmebridge -->|"calls client"| node_acme
node_certs -->|"persists state"| node_state
node_cycle -.->|"records activity"| node_events
node_docker -.->|"writes stacks"| node_stackfs
node_docker -.->|"runs Compose"| node_cli
node_nginx -.->|"writes host files"| node_vhostfs

click node_entry "https://github.com/uservseatb/apinfra/blob/main/cmd/main.go"
click node_composition "https://github.com/uservseatb/apinfra/blob/main/internal/app/update.go"
click node_hostconfig "https://github.com/uservseatb/apinfra/blob/main/internal/config/host.go"
click node_gitconfig "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/git_source.go"
click node_gitrepo "https://github.com/uservseatb/apinfra/blob/main/internal/git/repo.go"
click node_settings "https://github.com/uservseatb/apinfra/blob/main/internal/config/settings.go"
click node_cycle "https://github.com/uservseatb/apinfra/blob/main/internal/domain/deployment/service.go"
click node_docker "https://github.com/uservseatb/apinfra/blob/main/internal/domain/docker/service.go"
click node_compose "https://github.com/uservseatb/apinfra/blob/main/internal/domain/docker/compose.go"
click node_stackfs "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/stack_fs.go"
click node_cli "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/cli_runner.go"
click node_nginx "https://github.com/uservseatb/apinfra/blob/main/internal/domain/nginx/service.go"
click node_nginxrender "https://github.com/uservseatb/apinfra/blob/main/internal/domain/nginx/render.go"
click node_vhostfs "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/vhost_fs.go"
click node_certs "https://github.com/uservseatb/apinfra/blob/main/internal/domain/certmanagement/service.go"
click node_acmebridge "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/acme_bridge.go"
click node_acme "https://github.com/uservseatb/apinfra/blob/main/internal/acme/client.go"
click node_state "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/yaml_repo.go"
click node_layout "https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/layout.go"
click node_events "https://github.com/uservseatb/apinfra/blob/main/internal/events/events.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_entry,node_composition toneBlue
class node_hostconfig,node_gitconfig,node_gitrepo,node_settings toneAmber
class node_cycle,node_docker,node_compose toneMint
class node_nginx,node_nginxrender,node_certs,node_acme toneRose
class node_stackfs,node_cli,node_vhostfs,node_acmebridge,node_state,node_layout,node_events,node_operator toneIndigo
```

## Components

### Agent runtime

- [Update entrypoint](https://github.com/uservseatb/apinfra/blob/main/cmd/main.go): `cmd/main.go`
- [Service wiring](https://github.com/uservseatb/apinfra/blob/main/internal/app/update.go): `internal/app/update.go`

### Desired state

- [Host configuration](https://github.com/uservseatb/apinfra/blob/main/internal/config/host.go): `internal/config/host.go`
- [Git config loader](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/git_source.go): `internal/infrastructure/adapters/git_source.go`
- [Git repository access](https://github.com/uservseatb/apinfra/blob/main/internal/git/repo.go): `internal/git/repo.go`
- [Project settings](https://github.com/uservseatb/apinfra/blob/main/internal/config/settings.go): `internal/config/settings.go`

### Deployment

- [Update cycle](https://github.com/uservseatb/apinfra/blob/main/internal/domain/deployment/service.go): `internal/domain/deployment/service.go`
- [Compose orchestration](https://github.com/uservseatb/apinfra/blob/main/internal/domain/docker/service.go): `internal/domain/docker/service.go`
- [Compose validation](https://github.com/uservseatb/apinfra/blob/main/internal/domain/docker/compose.go): `internal/domain/docker/compose.go`

### Ingress and TLS

- [Ingress routing](https://github.com/uservseatb/apinfra/blob/main/internal/domain/nginx/service.go): `internal/domain/nginx/service.go`
- [Nginx rendering](https://github.com/uservseatb/apinfra/blob/main/internal/domain/nginx/render.go): `internal/domain/nginx/render.go`
- [Certificate management](https://github.com/uservseatb/apinfra/blob/main/internal/domain/certmanagement/service.go): `internal/domain/certmanagement/service.go`
- [ACME providers](https://github.com/uservseatb/apinfra/blob/main/internal/acme/client.go): `internal/acme/client.go`

### Host adapters

- [Stack filesystem](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/stack_fs.go): `internal/infrastructure/stack_fs.go`
- [Docker and CLI adapter](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/cli_runner.go): `internal/infrastructure/adapters/cli_runner.go`
- [Virtual-host filesystem](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/vhost_fs.go): `internal/infrastructure/vhost_fs.go`
- [ACME adapter](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/acme_bridge.go): `internal/infrastructure/adapters/acme_bridge.go`
- [Certificate state](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/adapters/yaml_repo.go): `internal/infrastructure/adapters/yaml_repo.go`
- [Host layout](https://github.com/uservseatb/apinfra/blob/main/internal/infrastructure/layout.go): `internal/infrastructure/layout.go`
- [Event records](https://github.com/uservseatb/apinfra/blob/main/internal/events/events.go): `internal/events/events.go`

### Other components

- **Host operator**

## Connections

- Host operator → Update entrypoint: starts run
- Update entrypoint → Service wiring: runs update (evidence: `cmd/main.go`)
- Service wiring → Host configuration: loads settings (evidence: `internal/app/update.go`)
- Service wiring → Update cycle: executes cycle (evidence: `internal/app/update.go`)
- Service wiring → Compose orchestration: wires service (evidence: `internal/app/update.go`)
- Service wiring → Git config loader: wires source (evidence: `internal/app/update.go`)
- Service wiring → Host layout: wires layout (evidence: `internal/app/update.go`)
- Service wiring → Certificate management: wires service (evidence: `internal/app/update.go`)
- Service wiring → ACME adapter: wires adapter (evidence: `internal/app/update.go`)
- Service wiring → Certificate state: wires repository (evidence: `internal/app/update.go`)
- Service wiring → Ingress routing: wires ingress (evidence: `internal/app/update.go`)
- Git config loader → Git repository access: loads clone (evidence: `internal/infrastructure/adapters/git_source.go`)
- Git config loader → Project settings: reads projects (evidence: `internal/infrastructure/adapters/git_source.go`)
- Update cycle → Host layout: prepares directories (evidence: `internal/domain/deployment/service.go`)
- Update cycle → Git config loader: loads workspace (evidence: `internal/domain/deployment/service.go`)
- Update cycle → Compose orchestration: validates and applies (evidence: `internal/domain/deployment/service.go`)
- Update cycle → Ingress routing: processes routing (evidence: `internal/domain/deployment/service.go`)
- Update cycle → Compose orchestration: prunes images (evidence: `internal/domain/deployment/service.go`)
- Compose orchestration → Compose validation: validates projects (evidence: `internal/domain/docker/service.go`)
- Ingress routing → Nginx rendering: renders configuration (evidence: `internal/domain/nginx/render.go`)
- Certificate management → ACME adapter: issues certificates (evidence: `internal/infrastructure/adapters/acme_bridge.go`)
- ACME adapter → ACME providers: calls client (evidence: `internal/infrastructure/adapters/acme_bridge.go`)
- Certificate management → Certificate state: persists state (evidence: `internal/infrastructure/adapters/yaml_repo.go`)
- Update cycle → Event records: records activity
- Compose orchestration → Stack filesystem: writes stacks
- Compose orchestration → Docker and CLI adapter: runs Compose
- Ingress routing → Virtual-host filesystem: writes host files