bincio-wiki/CLAUDE.md

bincio_wiki — development notes

Project overview

A private wiki for the bincio group of friends. Built on Astro 6 using the brutsalvadi/astro-bloomz fork as a git submodule at site/. Content lives in pages/ and blog/ at the repo root; Astro loads them via glob loaders pointing to ../pages and ../blog (outside the submodule). No symlinks.

Directory layout

bincio_wiki/
  pages/          wiki content (*.md files the community edits)
    _docs/        software documentation (shown as separate section)
  blog/           blog/stories content (*.md files)
  site/           Astro 6 app (git submodule → brutsalvadi/astro-bloomz)
  edit/           FastAPI edit server (Python, port 8001)
  pyproject.toml  Python dependencies (managed by uv)
  uv.lock         uv lockfile (committed)
  scripts/        dev.sh — starts both Astro and FastAPI together
  docs/           repo-level documentation (not served as wiki pages)

Running locally

bash scripts/dev.sh          # Astro only (port 4321)
bash scripts/dev.sh --edit   # Astro + FastAPI edit sidecar (port 8001)

Python dependencies are managed by uv. uv sync is called automatically by dev.sh --edit — no manual setup needed. To add a dependency: uv add <package> (updates pyproject.toml and uv.lock).

Content architecture

• Wiki pages: pages/*.md (IDs in Astro content store are the bare filename without extension, e.g. digital-garden)
• Docs section: pages/_docs/*.md (IDs start with _docs/)
• Blog/stories: blog/*.md
• Bonsai index: stored in site/src/content/index/ — the i.bonsai.md file defines the semantic tree structure
• The homepage (site/src/pages/index.astro) splits entries by _docs/ prefix into "Pagine recenti" and "Documentazione" sections

Astro 6 content layer notes

• Collections use glob loaders in site/src/content.config.ts
• entries collection base is ../pages (relative to site/), resolving to bincio_wiki/pages/. Vite is configured with server.fs.allow: ['..'] to permit serving files from outside the project root.
• blog collection base is ../blog (same pattern)
• index collection base is ./src/content/index (stays inside site/)
• Custom generateId on entries and index — see content.config.ts for details. index preserves dots so i.bonsai is not mangled by githubSlug.
• Use entry.id not entry.slug
• Use import { render } from 'astro:content'; render(entry) not entry.render()

Language / i18n

Italian is the default language. All documentation in pages/_docs/ is in Italian. Technical terms (WikiRefs, Astro, plugin names, wikilink syntax, code) stay in English. See docs/lingua.md for the full rationale.

Authentication

Current approach (same as bincio_activity)

Not yet implemented in bincio_wiki — pending.

Planned pattern:

• nginx serves the static Astro build publicly (no nginx-level auth)
• Every Astro page layout calls GET /api/me on load
• If the API returns 401/error, the page JS redirects to /login/
• FastAPI (edit/server.py) handles sessions: SQLite users table, bcrypt passwords, HTTP-only session cookie
• Login page at /login/ — a static Astro page that POSTs credentials to /api/auth/login

Security assessment

This is client-side enforcement only. The HTML is technically accessible to anyone who:

• Uses curl or wget directly
• Disables JavaScript in the browser
• Views page source

For bincio_wiki this is an acceptable tradeoff. The content is community memories and shared activities (not financial/medical data), members are not adversarial, and the goal is keeping casual visitors and search engine crawlers out — not resisting determined attackers.

Future: making specific pages public

With this architecture, making a page public later is trivial: just use a layout variant that skips the /api/me check. No nginx changes needed since nginx already serves everything publicly at the static file level.

For stricter enforcement on genuinely sensitive pages, the alternative is Astro SSR with a server middleware that checks the session cookie before rendering any HTML. This would require migrating from static output to SSR mode — a bigger change, not warranted for now.

VPS deployment target

Debian 12 VPS. nginx serves the built site from /var/www/bincio/wiki/. FastAPI proxied from localhost:8001 via nginx location /api/ { proxy_pass }. See docs/vps.md for full nginx config and deployment steps.

Git conventions

• No Co-Authored-By: Claude trailers in commits
• Commit messages in English
• Do not push without explicit user instruction