Newer
Older
gnexus-book / CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

Gnexus Book is a Git-backed personal infrastructure knowledge base plus the tooling that operates on it: a FastAPI backend, an MCP server for AI agents, and a Vue UI. The repository root is the data store — Markdown docs (numbered directories), YAML inventory in 40-inventory/, JSON Schemas in schemas/, and an audit/pending-change area in 90-maintenance/pending-changes/.

Two consumers must keep working:

  • humans reading Markdown/YAML from Git;
  • AI agents calling the MCP tools, which must not bypass validation or Git safety checks.

Platform handbook (mandatory)

Rules for the whole Gnexus ecosystem live in ~/Projects/gnexus-handbook (https://git.gnexus.space/root/gnexus-handbook), not here. Before changing authentication, MCP/keys, UI, secrets, backups, health, deployment, or documentation policy, read the handbook README and the relevant section. Link to the handbook instead of copying its rules.

Notable for this repository:

  • Commit messages follow 10-platform/git.md; it overrides Claude Code's default attribution (no co-authorship lines).
  • This file-backed prototype predates several handbook conventions (SSO, per-user MCP keys, streamable-HTTP MCP, off-host verified backups). 50-decisions/ADR-0002-postgres-storage-and-versioning.md tracks the gaps and the planned move to PostgreSQL.

Common commands

Server

cd server
python3 -m venv .venv && . .venv/bin/activate   # or: uv venv --python 3.11
pip install -e ".[dev]"

# Run all tests
.venv/bin/python -m pytest -q

# Run a single test
.venv/bin/python -m pytest tests/test_api.py::test_health_endpoint -q

# Dev API (README uses 8080; the Vite proxy expects 3005)
.venv/bin/python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 3005

# MCP server (stdio by default)
.venv/bin/python -m app.mcp_server

MCP environment: GNEXUS_BOOK_REPO_ROOT (defaults to the repo root derived from server/app/config.py) and GNEXUS_BOOK_MCP_TRANSPORT (stdio | sse | streamable-http).

PostgreSQL read backend (Phase 1)

# From the repo root: local dev cluster on 127.0.0.1:5433
./scripts/dev-db.sh start

cd server
export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)"
.venv/bin/alembic upgrade head
.venv/bin/python -m app.storage.cli import --replace
.venv/bin/python -m app.storage.cli parity     # exits 1 on a file/DB difference

GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005

GNEXUS_BOOK_STORAGE_BACKEND defaults to file. Dumps go to the off-host NFS via scripts/backup-db.sh; scripts/restore-db.sh requires GNEXUS_BOOK_RESTORE_YES=1.

UI

cd ui
npm install
npm run dev     # port 3006, proxies /api -> http://127.0.0.1:3005
npm run build   # outputs dist/

gnexus-ui-kit is a local file:../../gnexus-ui-kit dependency (sibling of the repo root), built from https://git.gnexus.space/root/gnexus-ui-kit. ui/vite.config.js dedupes Vue, resolves Vue's ESM bundler build, and serves the kit's fonts from node_modules/gnexus-ui-kit/dist/assets/fonts.

Deploy (VPS)

./scripts/install.sh   # uv + Python 3.11, nvm/Node, clone/build ui-kit, venv, UI build, systemd user units
./scripts/deploy.sh    # git pull, rebuild kit + UI, sync UI dist to /var/www/gnexus-book, restart backend, reload nginx

systemd/*.service hardcodes /home/ubuntu/gnexus-book paths — adjust them if the deployment user differs. Nginx (nginx/gnexus-book.conf) serves ui/dist on port 80, proxies /api/ to the backend on 8000 and /mcp/ to the MCP server on 8001.

Backend architecture

server/app/main.py is the FastAPI composition root. Every route depends on a repository class constructed from app/config.py:Settings; Settings() defaults repo_root to server/../.., and tests pass Settings(tmp_path) to build isolated fake repositories.

The domain layer is split by responsibility:

  • docs_repository.py + markdown.py — list/read/search Markdown under the repo root, skipping .git, .venv, node_modules, etc. The frontmatter parser is deliberately simple: only a flat key: value block between the first --- fences is parsed. Nested YAML or typed values in frontmatter are not supported.
  • inventory.py — reads 40-inventory/<type>.yml; each file is a YAML list and items are looked up by id.
  • relationships.py — builds a graph whose node ids are <inventory-type>/<id> and whose edges come from known cross-record fields (host, hypervisor_host, runs_services, points_to, destination, related_*, etc.). References to unknown ids are returned in unresolved_references rather than failing the request.
  • freshness.py — checks required frontmatter fields and staleness (last_reviewed + review_interval, e.g. 90d), and reports inventory docs: targets that do not exist.
  • validation.py — the full-repo gate used before apply/commit: schemas parse as Draft 2020-12, every inventory file validates against its schema (SCHEMA_BY_INVENTORY), Markdown has required frontmatter, ids are unique per inventory file, and a regex scan detects raw secret assignments/private-key blocks. The separate inventory docs-link validator (_validate_inventory_doc_links) is intentionally disabled; freshness still reports those missing targets.
  • pending_changes.py — the write path. A proposal is a JSON file in 90-maintenance/pending-changes/; apply() writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only doc and inventory-item kinds can be applied; full-file inventory replacement is not implemented.
  • git_adapter.py — status/diff/commit. Commit requires an explicit file list, rejects absolute/traversal/denied paths, runs validation first, stages only the named files, and creates a local commit only (never pushes).
  • storage/ — the PostgreSQL layer introduced for the migration. models.py defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), db_repositories.py implements the same read interfaces as the file repositories, importer.py copies the current repository into the database, parity.py compares both backends, and cli.py exposes import, parity, and counts. factory.py chooses the backend from GNEXUS_BOOK_STORAGE_BACKEND. Alembic lives in server/alembic/. Reads can use either backend; in db mode write endpoints/tools are blocked until Phase 2, and validation/freshness still read files until Phase 3.

MCP server

server/app/mcp_server.py exposes the same domain functions (not HTTP) as 17 MCP tools plus gnexus-book://* resources. The long tool descriptions and MCP_INSTRUCTIONS/AGENT_USAGE_GUIDE strings are covered by tests in tests/test_mcp_server.py; update the tests when changing that guidance. GET /mcp/info reflects the registered tools and instructions.

The MCP guidance tells external agents never to edit repository files directly and to use propose → apply → validate → commit. That rule is for MCP clients; normal development in this checkout edits files directly, but still run validation before committing.

Documentation and data conventions

  • Every knowledge document needs frontmatter with owner, status, last_reviewed, review_interval, confidence, source_of_truth. Validation skips README.md and server/**; other Markdown (including ui/README.md) is checked.
  • Inventory files are YAML sequences beginning with ---. Item ids must be unique within a file. Adding a new inventory type requires both 40-inventory/<type>.yml and an entry in validation.SCHEMA_BY_INVENTORY.
  • Never store raw passwords, tokens, private keys, recovery codes, or session cookies. Describe where a secret lives using reference values such as unknown, redacted, password manager, vault, or ref:....
  • Some inventory schemas require a docs link. When creating such an item, create the Markdown document first (the MCP inventory-creation guidance codifies this).
  • Update last_reviewed only after the information was actually verified.
  • 60-generated/inventory-index.md is still a placeholder; no generator exists yet.

UI architecture

The entire frontend is a single Vue 3 app in ui/src/main.js (no router). It renders tabbed, read-focused views — docs, inventory, changes, git — using components from gnexus-ui-kit/vue. All data goes through /api (apiGet/apiPost). Avoid copying UI-kit styles locally; prefer upstream changes in the kit.

Testing notes

Tests run from server/ with pythonpath = ["."]. Most tests read the real repository, so they assert on real inventory/docs content; fixture-based tests use Settings(tmp_path) and copy schemas from the real repo.

Database tests use GNEXUS_BOOK_TEST_DATABASE_URL (default postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test) and skip when PostgreSQL is unavailable. tests/test_migrations.py applies the Alembic migration to a temporary database.

tests/test_docs_repository.py::test_freshness_report_is_clean_for_knowledge_docs is date-dependent: it fails once documents pass their review_interval. When it fails, refresh last_reviewed only for docs whose content was actually reviewed, or treat the failure as genuine staleness.