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