Documentation · Platform

Platform & API (Phase 1)

Stack: FastAPI (backend/nims), PostgreSQL, Prisma for migrations only, React + Vite (web/). Build output web/dist can be served by the API under /app/.

Web console (behavioral summary)

Global search in the sidebar — GET /v1/search?q=&limit=
Pinned pages at the top of the sidebar from User.preferences.pinnedPages — Pin / Unpin in each page header (⋯ menu), not in the nav. Example: PATCH /v1/me with {"preferences":{"pinnedPages":[{"path":"/dcim/devices","label":"Devices"}]}}
Sidebar sections are collapsible; state in localStorage (nims.sidebar.*)
List pages use a shared header: Add, bulk import (CSV/JSON via ⋯), bulk export — backed by bulk routes (see bulk.py in the repo)
Object view — GET /v1/resource-view/{resourceType}/{id} (fields + graph)
Graph only — GET /v1/resource-graph/{resourceType}/{id}
Validation & templates — DCIM forms use schemas exported from OpenAPI (AJV on the client); referential checks via GET /v1/validation/…. Admins edit object templates under Platform (/app/platform/object-templates): visual custom attribute rules plus full-definition JSON. Design: design-validation.md.

Sign-in & identity (summary)

The console supports local email/password (optional) and at most one of LDAP, Microsoft Entra, or OIDC, configured under Administration → Sign-in & identity and/or AUTH_* env (env wins; UI is read-only for those fields). Unauthenticated: GET /v1/auth/providers. Admin: GET/PATCH /v1/admin/identity. Full contract: design-auth-user-management.md.

AI assistant, LLM, and optional MCP

The Intent Center copilot (in the web app) uses an OpenAI-style API with tool calls to search, show object view and graph, run composable catalog_breakdown and catalog_list queries, and surface change previews. Next step chip suggestions use page context and the recent chat. Admins configure the model at GET/PATCH /v1/admin/llm; environment variables LLM_* override the database when set. With NIMS_MCP_ENABLED=1, the same process mounts Streamable HTTP MCP at /mcp for clients that speak the Model Context Protocol, using API tokens as with REST.

AI assistant chat: devices without interfaces, bar chart of circuits by location, map of locations with coordinates — The assistant can answer inventory questions, render **chart** blocks (e.g. aggregations from `catalog_breakdown`), and **map** blocks (e.g. `list_location_hierarchy` when locations have coordinates).

Chat: POST /v1/copilot/chat, POST /v1/copilot/chat/stream
Next steps (chips): POST /v1/copilot/suggest_next_steps (body includes page context and messages)
Admin LLM config: GET/PATCH /v1/admin/llm, POST /v1/admin/llm/test, GET /v1/admin/llm/metrics
Skills, import assist, triage, titles: /v1/copilot/skills, …/assist/import-mapping, …/assist/ticket-triage, …/suggest_thread_title
Design: design-llm-assistant.md, design-mcp-server.md.

Extensibility & jobs

UI: GET /v1/ui/page-registry, GET /v1/ui/placements, GET /v1/ui/navigation, GET /v1/ui/federation (builtin-only manifest).
Admin: /v1/admin/plugin-placements, /v1/connectors, GET /v1/plugins.
Jobs: /v1/jobs, POST /v1/jobs/{key}/run (returns queued: true when JOB_EXECUTION_MODE=async), /v1/job-runs; run nims-worker as a second process to drain the queue.
Reserved: POST /v1/plugins/install returns 501 until signing and an artifact store exist.

REST touchpoints (UI-centric)

Feature	Endpoint
Search	`GET /v1/search?q=&limit=`
Me / preferences	`GET /v1/me`, `PATCH /v1/me`
Sign-in catalog	`GET /v1/auth/providers`
Identity (admin)	`GET /v1/admin/identity`, `PATCH /v1/admin/identity`
UI registry / slots / nav	`GET /v1/ui/page-registry`, `/v1/ui/placements`, `/v1/ui/navigation`, `/v1/ui/federation`
Plugins (list)	`GET /v1/plugins`
Connectors	`GET/POST/PATCH/DELETE /v1/connectors` (admin for writes)
Jobs & runs	`GET /v1/jobs`, `POST /v1/jobs/{key}/run`, `GET /v1/job-runs`
LLM (admin)	`GET /v1/admin/llm`, `PATCH /v1/admin/llm`, `POST /v1/admin/llm/test`
Copilot (chat, next steps, skills)	`POST /v1/copilot/chat`, `POST /v1/copilot/suggest_next_steps`, `/v1/copilot/skills` (see OpenAPI for full list)
Bulk CSV/JSON	`GET /v1/bulk/{resourceType}/export`, `POST /v1/bulk/{resourceType}/import/csv`, `POST /v1/bulk/{resourceType}/import/json`
Object view	`GET /v1/resource-view/{resourceType}/{id}`
Graph only	`GET /v1/resource-graph/{resourceType}/{id}`
Referential validation	`GET /v1/validation/{location-type\|location\|rack\|device-type\|device-role\|interface\|cable-ends}` (query params per route)
Object templates	`GET /v1/templates/resource-types`, `GET/POST /v1/templates`, `GET/PATCH/DELETE /v1/templates/{id}`, `POST /v1/templates/{id}/set-default`

Future work: see Wishlist & future work for deferred features (SSO, federation, plugin install, GraphQL auth parity, copilot consent/RAG, MCP policy, etc.).

Authoritative detail: platform/README.md

← Documentation home