Gnexus Book Server

FastAPI backend for reading Gnexus Book documentation and inventory.

Development

From the repository root:

cd server
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
uvicorn app.main:app --reload --host 127.0.0.1 --port 8080

Current API

• Swagger UI: GET /api-docs
• GET /health
• GET /docs
• GET /docs/read?path=...
• GET /search?q=...
• GET /inventory
• GET /inventory/{type}
• GET /inventory/{type}/{id}
• GET /traffic-routes
• GET /relationships
• GET /health/freshness
• GET /validate
• GET /changes
• GET /changes/{id}
• POST /changes
• POST /changes/{id}/apply
• GET /git/status
• GET /git/diff
• POST /commit

Inventory parsing requires PyYAML.

Current Limitations

• Main documentation and inventory files are read-only.
• POST /changes can create pending change records under 90-maintenance/pending-changes/.
• POST /changes/{id}/apply can apply kind=doc and kind=inventory-item changes after validation.
• No authentication yet.
• POST /commit creates a local Git commit only. It does not push.
• Commit requests must provide an explicit file list.
• Validation uses JSON Schema 2020-12 for inventory files.

Validation

GET /validate checks:

• schema validity for schemas/*.json;
• required Markdown frontmatter;
• inventory YAML against JSON Schema;
• inventory docs links;
• duplicate inventory item IDs;
• common raw secret assignment patterns in Markdown, YAML, JSON, and dotenv-style files.

POST /changes/{id}/apply and POST /commit both rely on validation to block unsafe repository states.