# Repository layout

[The README](https://noelmcloughlin.github.io/ai-linkmo/) says what AI-LinkMO is for. This is the tree behind it. Three toolchains live here: Python and uv at the root, Node in `lib/frontend/`, and a second uv project in `.lokf/`. [CONTRIBUTING.md](https://github.com/noelmcloughlin/ai-linkmo/blob/0d8d49f45be30e5f8e9d661d9edeacba9446570a/CONTRIBUTING.md) has the development setup and the checklist to run before a pull request.

```text
ai                      the CLI entry point (runs the linkmo project's command line through uv, asking the API by default)
justfile                build steps: the API contract and the UI entity list, which are committed; the graph, the store, the browse database and the schema's pages, which are not
scripts/                the scripts behind those recipes, and the test runner
ai-risk-ontology-linkmo/ the linkmo project, a uv workspace member: the exposure file, the CLI and API kernels, the server, the browse build and the schema's pages
  docs/elements/            the schema's pages, one example on each class page, written by `just gen-doc`, not committed
lib/api/                ai-linkmo's handlers behind the API: the related-risk lookups, the hand-written operations and the library instances they share
lib/frontend/           Svelte 5 web UI (Vite; proxies to the API on :8000)
lib/store/              the DuckDB store behind the listings and the search, built by `just load-store`, not committed
lib/test/               pytest suite; its API-mode CLI cases are the documented CLI examples, checked
graph/                  the exported ontology and crosswalk CSVs; cypher/ receives the fetched Neo4j export, not committed
byo/data/               nine governance frameworks encoded for the AI Risk Ontology
byo/notes/EXAMPLES.md   a scripted walk through all four access patterns
docs/
  openapi.json              the API contract, written by `just gen-openapi` and checked against the server
  key-concepts.md           the vocabulary the four doors share
  working-with-the-data.md  bring your own data, crosswalks, search and dumps, browsing, the schema's pages, the graph export
  neo4j.md                  load the graph into Neo4j in a container
  cli-examples.md           every entity type, one command away
  install-notes.md          compilers, CUDA, corporate package indexes
  llm-inferencing.md        LLM inference and ARES, on infrastructure you run
  for-the-curious.md        what this adds over AI Atlas Nexus, what it leaves out, where it could go
  status.md                 status and caveats, the full list
  releasing.md              how this repository releases
  threat-model.md           why the application and the automation are held as SECURITY.md says
  repository-layout.md      this page
.assets/                screenshots of each door, the architecture diagram, and the logos
.lokf/                  the sidecar: this repository's own knowledge bundle (knowledge/) and its tooling; its README has the layout
knowledge_bundle        -> .lokf/knowledge, the bundle under a visible name, for folder pickers and Obsidian
.github/workflows/      tests, lint, the knowledge-bundle gates, releases
```

## Tests

The test suite runs 101 CLI cases in API mode and in local mode, and starts the API server for you. CI runs `uv run pytest lib/test -m "not slow"`, which takes about two minutes. `./scripts/tests.sh` has the narrower modes. The browse tests need the `browse` extra and skip without it, so CI installs it beside `test`. The web UI (`npm run check`, `npm run lint`, `npm test` in `lib/frontend/`) and the bundle (`cd .lokf && just lokf-validate`) have their own gates. [lib/test/README.md](https://github.com/noelmcloughlin/ai-linkmo/blob/0d8d49f45be30e5f8e9d661d9edeacba9446570a/lib/test/README.md) has the detail. The `slow` and `byod_required` markers are defined in `pyproject.toml` under `[tool.pytest.ini_options]`; `pytest-timeout` is installed, but no default timeout is set.