# Documentation

Technical documentation for the PhD-research demo website. The site is a single Django + Vue Docker container deployed to a Hugging Face [Space](glossary.md#hf-space) (`Bani57/website` → <https://bani57-website.hf.space>) and showcases three research methods from the thesis _Scalable Methods for Knowledge Graph Reasoning and Generation_ (Andrej Janchevski, EPFL, 2025): [COINs](glossary.md#coins), [MultiProxAn](glossary.md#multiproxan) and [KG anomaly correction](glossary.md#task-kg-anomaly).

This document is a routing layer. Pick the document type that matches your goal — definitions, understanding, lookup, or task.

## Glossary

[glossary.md](glossary.md) defines every domain term used in the rest of the docs and in the source. Other documents link into the glossary on first mention rather than restating definitions.

## Explanation — understand the system

For background, design rationale and how pieces fit together.

- [explanation/architecture.md](explanation/architecture.md) — overall request flow and container topology.
- [explanation/research-methods.md](explanation/research-methods.md) — what each demo demonstrates scientifically and why the implementation is shaped the way it is.
- [explanation/inference-lifecycle.md](explanation/inference-lifecycle.md) — boot sequence, lazy model loading, the single-process [inference lock](glossary.md#inference-lock).

## Reference — look up exact behaviour

For specifications you need to consult, not read end-to-end.

- [reference/api.md](reference/api.md) — REST endpoints, request and response shapes (the OpenAPI spec lives at [`docs/api.yaml`](api.yaml); this is the human-readable companion).
- [reference/sse-protocol.md](reference/sse-protocol.md) — `text/event-stream` event schema for streaming inference.
- [reference/backend-services.md](reference/backend-services.md) — `api/services/` modules: `ModelRegistry`, inference helpers, constants.
- [reference/frontend-modules.md](reference/frontend-modules.md) — Vite project layout, Pinia stores, `useSseStream` composable, axios client.

## Guides — accomplish a task

Step-by-step, goal-oriented.

- [guides/local-development.md](guides/local-development.md) — install the `website_c` mamba env, run the Django dev server and the Vite dev server.
- [guides/deploy.md](guides/deploy.md) — push a new version to the HF Space, including the one-time checkpoint upload to HF Hub.

## Project artefacts

- [`api.yaml`](api.yaml) — OpenAPI 3.0.3 specification.
- [`postman/collection.json`](postman/collection.json), [`postman/environment.json`](postman/environment.json) — Postman bundle for hand-testing the API.
- [`../plans/`](../plans/) — implementation plans for major deployment / refactor work.

## Audience

The docs assume a reader who knows Python, Django, Vue 3, and basic graph ML; they do not assume prior knowledge of the thesis methods.