Newer
Older
gnexus-book / CLAUDE.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 1 day ago 9 KB docs: record Phase 3 completion

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 read interfaces, pending_changes_db.py implements draft/apply changesets transactionally, documents.py provides history/version/diff/restore, validation.py validates the database, importer.py copies the repository into PostgreSQL, parity.py compares both backends, and cli.py exposes import, parity, and counts. factory.py selects docs/inventory/pending repositories from GNEXUS_BOOK_STORAGE_BACKEND. Alembic lives in server/alembic/. In db mode all knowledge writes go through changesets; commit_changes is a no-op. Validation, freshness, and relationships use the selected backend.

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_db_storage.py covers read parity, tests/test_db_changesets.py covers versioning/changesets/history/diff/restore, and 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.