bincio-wiki/docs/architecture/overview.md

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 (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