Add MkDocs documentation: architecture, deployment, development, decisions

2026-05-08 10:07:20 +02:00
parent fd2d81328f
commit ccec23c3a3
10 changed files with 591 additions and 102 deletions
@@ -0,0 +1,57 @@
+# System Overview
+
+## Components
+
+```
+Browser
+  │
+  │  HTTPS (443)
+  ▼
+nginx  ─── static files ──► /var/www/bincio-wiki/   (Astro build output)
+  │
+  │  proxy_pass (127.0.0.1:4042)
+  ▼
+FastAPI sidecar  (edit/server.py)
+  ├── reads/writes ──► pages/   (wiki markdown)
+  ├── reads/writes ──► blog/    (blog markdown)
+  ├── reads/writes ──► assets/  (uploaded images)
+  ├── git add + commit ──► /opt/bincio-wiki-repo.git  (bare repo)
+  └── reads/writes ──► /var/bincio/data/instance.db  (shared SQLite)
+```
+
+## Request flow
+
+1. Browser requests `wiki.bincio.org/entries/some-page/`.
+2. nginx serves the pre-built static HTML from `/var/www/bincio-wiki/`.
+3. The page's inline JavaScript calls `GET /api/me` on load. nginx proxies this to FastAPI.
+4. If FastAPI returns 401/403 (no valid session), JS redirects to `/login/`.
+5. On a page edit, the browser `POST /pages/{slug}` with new Markdown content. FastAPI writes the file, runs `git commit`, then `POST /rebuild` triggers `astro build --force`.
+6. nginx serves the rebuilt static output immediately on next request.
+
+## Technology stack
+
+| Layer | Technology |
+|-------|------------|
+| Frontend framework | [Astro 6](https://astro.build) (static output) |
+| CSS | Tailwind CSS |
+| Interactive editor | Svelte (PageEditor component) |
+| Markdown extensions | `remark-wikirefs`, `remark-caml` |
+| Wikibonsai integration | Custom TypeScript (`site/src/wikibonsai/`) |
+| API / sidecar | FastAPI + uvicorn |
+| Python packaging | uv |
+| Database | SQLite (shared with `bincio_activity`) |
+| Passwords | bcrypt |
+| VCS | Git (two bare repos on VPS) |
+| Web server | nginx + Let's Encrypt (Certbot) |
+| Process manager | systemd |
+| VPS | Hetzner, Debian 12 |
+
+## Port map
+
+| Port | Service |
+|------|---------|
+| 443 | nginx (HTTPS, wiki.bincio.org) |
+| 4042 | bincio-wiki FastAPI (production) |
+| 8001 | bincio-wiki FastAPI (local dev) |
+| 4321 | Astro dev server (local dev only) |
+| 4041 | bincio_activity FastAPI |