# Gnexus Book Server

FastAPI backend for reading Gnexus Book documentation and inventory.

## Development

From the repository root:

```bash
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.

Inventory includes broad records for hosts, services, domains, traffic routes, endpoints, integrations, projects, databases, backups, networks, hardware, and virtual machines.

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