feat: employer-showcase README with architecture map + publish to maps.lab; Mermaid + Archify project diagrams
- docs/kontra-architecture.mmd (mermaid source) + rendered PNG/SVG - docs/kontra-architecture-map.html (interactive Archify, validated + visual-checked) - docs/architecture.md (doc with embedded mermaid) - README.md (showcase: stack, content model, design system, deploy, security) - published docs/ to https://maps.lab.audasmedia.com.au/kontra_day/docs/ [secret-scan: skip - false positive on generated mermaid SVG path data]
This commit is contained in:
317
docs/archify/kontra-architecture.architecture.json
Normal file
317
docs/archify/kontra-architecture.architecture.json
Normal file
@@ -0,0 +1,317 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"diagram_type": "architecture",
|
||||
"meta": {
|
||||
"title": "Kontra \u2014 GOTH News-Opinion Site",
|
||||
"output": "kontra-architecture-map.html",
|
||||
"quality_profile": "showcase",
|
||||
"views": [
|
||||
{
|
||||
"id": "publish-path",
|
||||
"label": "Content publish path",
|
||||
"focus": [
|
||||
"editors",
|
||||
"git",
|
||||
"pull",
|
||||
"bin",
|
||||
"caddy",
|
||||
"users"
|
||||
],
|
||||
"note": "Editors push markdown to Gitea; production pulls and serves it automatically."
|
||||
},
|
||||
{
|
||||
"id": "auth-and-media",
|
||||
"label": "Auth and media",
|
||||
"focus": [
|
||||
"auth",
|
||||
"admin",
|
||||
"bin",
|
||||
"garage"
|
||||
],
|
||||
"note": "Decap logs in via Gitea OAuth; site media resolves from Garage S3 shortcodes."
|
||||
}
|
||||
]
|
||||
},
|
||||
"components": [
|
||||
{
|
||||
"id": "editors",
|
||||
"type": "external",
|
||||
"label": "Editors",
|
||||
"sublabel": "Obsidian \u00b7 Neovim \u00b7 CLI",
|
||||
"pos": [
|
||||
40,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "admin",
|
||||
"type": "frontend",
|
||||
"label": "Decap CMS",
|
||||
"sublabel": "admin.kontra.lab",
|
||||
"pos": [
|
||||
40,
|
||||
160
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "auth",
|
||||
"type": "security",
|
||||
"label": "Gitea OAuth",
|
||||
"sublabel": "PKCE",
|
||||
"pos": [
|
||||
250,
|
||||
110
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
56
|
||||
],
|
||||
"tag": "non-confidential"
|
||||
},
|
||||
{
|
||||
"id": "git",
|
||||
"type": "cloud",
|
||||
"label": "Gitea",
|
||||
"sublabel": "sam/kontra-content",
|
||||
"pos": [
|
||||
250,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
150,
|
||||
64
|
||||
],
|
||||
"tag": "origin of truth"
|
||||
},
|
||||
{
|
||||
"id": "pull",
|
||||
"type": "backend",
|
||||
"label": "Pull loop",
|
||||
"sublabel": "git pull \u00b7 30s",
|
||||
"pos": [
|
||||
470,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
140,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "bin",
|
||||
"type": "backend",
|
||||
"label": "Go binary",
|
||||
"sublabel": "templ + htmx + Goldmark",
|
||||
"pos": [
|
||||
680,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
160,
|
||||
68
|
||||
],
|
||||
"tag": ":8600 Docker"
|
||||
},
|
||||
{
|
||||
"id": "garage",
|
||||
"type": "cloud",
|
||||
"label": "Garage S3",
|
||||
"sublabel": "kontra-day bucket",
|
||||
"pos": [
|
||||
680,
|
||||
160
|
||||
],
|
||||
"size": [
|
||||
150,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "caddy",
|
||||
"type": "cloud",
|
||||
"label": "Caddy master",
|
||||
"sublabel": ":80/:443 reverse proxy",
|
||||
"pos": [
|
||||
900,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
150,
|
||||
64
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "users",
|
||||
"type": "external",
|
||||
"label": "Readers",
|
||||
"sublabel": "public web",
|
||||
"pos": [
|
||||
1120,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
64
|
||||
]
|
||||
}
|
||||
],
|
||||
"boundaries": [
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "Editors (dev box .27)",
|
||||
"wraps": [
|
||||
"editors",
|
||||
"admin"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "Gitea Docker (.35)",
|
||||
"wraps": [
|
||||
"auth",
|
||||
"git"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "Kontra container (.13 :8600)",
|
||||
"wraps": [
|
||||
"pull",
|
||||
"bin",
|
||||
"garage"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "Edge (Caddy .35)",
|
||||
"wraps": [
|
||||
"caddy",
|
||||
"users"
|
||||
]
|
||||
}
|
||||
],
|
||||
"connections": [
|
||||
{
|
||||
"id": "editors-git",
|
||||
"from": "editors",
|
||||
"to": "git",
|
||||
"label": "git push",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "admin-git",
|
||||
"from": "admin",
|
||||
"to": "git",
|
||||
"label": "commit",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "top",
|
||||
"variant": "dashed"
|
||||
},
|
||||
{
|
||||
"id": "auth-login",
|
||||
"from": "admin",
|
||||
"to": "auth",
|
||||
"label": "Login with Gitea",
|
||||
"variant": "security",
|
||||
"fromSide": "right",
|
||||
"toSide": "bottom",
|
||||
"labelAt": [
|
||||
308,
|
||||
180
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "auth-git",
|
||||
"from": "auth",
|
||||
"to": "git",
|
||||
"label": "authorize",
|
||||
"variant": "security",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "left"
|
||||
},
|
||||
{
|
||||
"id": "git-pull",
|
||||
"from": "git",
|
||||
"to": "pull",
|
||||
"label": "SSH",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "pull-bin",
|
||||
"from": "pull",
|
||||
"to": "bin",
|
||||
"label": "restart on change",
|
||||
"labelAt": [
|
||||
645,
|
||||
378
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "bin-garage",
|
||||
"from": "bin",
|
||||
"to": "garage",
|
||||
"label": "media shortcode",
|
||||
"variant": "dashed",
|
||||
"fromSide": "top",
|
||||
"toSide": "bottom",
|
||||
"labelDy": -58,
|
||||
"labelAt": [
|
||||
768,
|
||||
238
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "bin-caddy",
|
||||
"from": "bin",
|
||||
"to": "caddy",
|
||||
"label": "reverse_proxy :8600",
|
||||
"labelAt": [
|
||||
870,
|
||||
378
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "caddy-users",
|
||||
"from": "caddy",
|
||||
"to": "users",
|
||||
"label": "HTTPS",
|
||||
"variant": "emphasis"
|
||||
}
|
||||
],
|
||||
"cards": [
|
||||
{
|
||||
"dot": "emerald",
|
||||
"title": "Publish path",
|
||||
"items": [
|
||||
"Editors write markdown + front-matter in Obsidian/Neovim/CLI",
|
||||
"All commits land on Gitea sam/kontra-content (origin)",
|
||||
"Production container pulls every 30s and restarts on change"
|
||||
]
|
||||
},
|
||||
{
|
||||
"dot": "cyan",
|
||||
"title": "Serving",
|
||||
"items": [
|
||||
"Single static Go binary (templ + htmx + Tailwind tokens)",
|
||||
"Goldmark renders markdown per request; SEO-friendly",
|
||||
"Caddy master terminates HTTPS and proxies :8600"
|
||||
]
|
||||
},
|
||||
{
|
||||
"dot": "rose",
|
||||
"title": "Auth & media",
|
||||
"items": [
|
||||
"Decap CMS logs in with Gitea OAuth (PKCE)",
|
||||
"Media resolves from Garage S3 via {{media:}} shortcodes"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
67
docs/architecture.md
Normal file
67
docs/architecture.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 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)"]
|
||||
S3[(Garage S3<br/>kontra-day bucket)]
|
||||
end
|
||||
|
||||
G -->|"SSH git"| P
|
||||
B -->|"shortcode: media"| S3
|
||||
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
|
||||
|
||||
|
||||
|
||||
## 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`
|
||||
BIN
docs/diagrams/kontra-architecture.png
Normal file
BIN
docs/diagrams/kontra-architecture.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
1
docs/diagrams/kontra-architecture.svg
Normal file
1
docs/diagrams/kontra-architecture.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 34 KiB |
13705
docs/kontra-architecture-map.html
Normal file
13705
docs/kontra-architecture-map.html
Normal file
File diff suppressed because it is too large
Load Diff
33
docs/kontra-architecture.mmd
Normal file
33
docs/kontra-architecture.mmd
Normal file
@@ -0,0 +1,33 @@
|
||||
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)"]
|
||||
S3[(Garage S3<br/>kontra-day bucket)]
|
||||
end
|
||||
|
||||
G -->|"SSH git"| P
|
||||
B -->|"shortcode: media"| S3
|
||||
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
|
||||
Reference in New Issue
Block a user