# Kontra — System Architecture

A news-opinion site (GOTH stack: **Go + templ + htmx + Tailwind-tokens**) with markdown
content, a Decap CMS admin, Gitea-backed git deploy with automatic content sync, and
Garage S3 media — all on the home-lab network.

> Interactive map: `docs/kontra-architecture-map.html` — also published at:
> https://maps.lab.audasmedia.com.au/kontra/docs/kontra-architecture-map.html

## Diagram (Mermaid)

```mermaid
flowchart LR
  subgraph editors["Content Editors"]
    O[Obsidian vault<br/>/obsidian/kontra_content] -->|git push| G
    N[Neovim / CLI] -->|git push| G
    D[Decap CMS<br/>admin.kontra.lab] -->|OAuth + git commit| G
  end

  subgraph gitea["Gitea (192.168.20.35 :3001 Docker)"]
    G[(sam/kontra-content<br/>markdown origin of truth)]
  end

  subgraph prod["Kontra container (192.168.20.13 :8600 Docker)"]
    P[git pull loop<br/>every 30s] -->|restart on change| B
    B[Go binary<br/>templ + htmx + Goldmark]
    B --> MD[(Markdown render<br/>front-matter + shortcodes)]
  end

  subgraph media["Media (Garage S3 on .13)"]
    F[(Images beside articles<br/>in the content repo)]
  end

  G -->|"SSH git"| P
  B -->|"shortcode: media"| F
  B -->|"emits HTML"| CB[Caddy master<br/>.35 :80/:443]
  CB -->|"reverse_proxy :8600"| B

  subgraph net["Network"]
    CB -->|https| WWW[kontra.lab.audasmedia.com.au]
    CB -->|https| ADM[admin.kontra.lab.audasmedia.com.au]
  end

  WWW -->|browser| B
  ADM -->|browser| D
```

## Rendered image

![Kontra architecture](diagrams/kontra-architecture.png)

## Key facts

| Layer | Where | What |
|---|---|---|
| Content origin | Gitea `.35:3001` | `sam/kontra-content` (markdown + front-matter) |
| App binary | Docker on `.13:8600` | Go (golang) + templ + htmx + Goldmark markdown |
| Content deploy | pull loop | `git pull` every 30s → restart server on change |
| Media | Garage S3 on `.13` | `kontra-day` bucket via `{{shortcode}}` |
| Admin | Decap CMS | at `admin.kontra.lab.audasmedia.com.au/web/admin/`, Gitea OAuth login |
| Reverse proxy | Caddy on `.35` | master :80/:443 → reverse_proxy `.13:8600` |
| Obsidian | `.27` vault | `obsidian/kontra_content` → content repo (git-sync) |

## Mermaid source

`docs/kontra-architecture.mmd` (single source of truth). Render:
`mmdc -i docs/kontra-architecture.mmd -o docs/diagrams/kontra-architecture.png --scale 2 -b white`