# cyberbount/ai-lems architecture

> Architecture diagram of the GitHub repository cyberbount/ai-lems, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyberbount/ai-lems
- Repository: https://github.com/cyberbount/ai-lems

## Overview

AI-LEMS is a laboratory equipment management system with a React interface and FastAPI backend. The principal workflow is role-based sign-in, browsing equipment, creating and processing borrow/return requests, and recording maintenance; statistics and usage history support oversight. A separate local-AI workflow retrieves document or operational context and queries Ollama. The README documents the API capabilities, but sampled router and frontend excerpts are incomplete, so feature-level UI-to-route wiring is not inferred.

Main entry points: [`backend/app/main.py`](https://github.com/cyberbount/ai-lems/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/models.py`](https://github.com/cyberbount/ai-lems/blob/main/backend/app/models.py) (Domain models), [`backend/app/routers/auth.py`](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/auth.py) (Authentication), [`backend/app/services/ai_service.py`](https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/ai_service.py) (Context and retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_webapp["React application<br/>[App.jsx]"]
  node_apiclient["API client<br/>[api.js]"]
end

subgraph group_backend["API and access"]
  node_api["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_access["JWT and roles<br/>[deps.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("SQL database<br/>[db.py]")]
end

subgraph group_operations["Lab operations"]
  node_users["User management<br/>[users.py]"]
  node_catalog["Equipment catalog<br/>[catalog.py]"]
  node_devices["Equipment management<br/>[devices.py]"]
  node_requests["Borrow and return<br/>[requests.py]"]
  node_maintenance["Maintenance<br/>[maintenance.py]"]
  node_stats["Usage statistics<br/>[stats.py]"]
  node_audit["Audit history<br/>[audit.py]"]
  node_auditservice["Audit recording<br/>[audit_service.py]"]
end

subgraph group_ai["Local AI"]
  node_ai["AI chat route<br/>[ai.py]"]
  node_aiservice["Context and retrieval<br/>[ai_service.py]"]
  node_documents["SOP document chunks"]
  node_ollama["Ollama local service<br/>[ollama_provider.py]"]
end

node_people(("Lab users"))
node_ollamasvc["Ollama HTTP API"]

node_people -->|"use"| node_webapp
node_webapp -->|"request"| node_apiclient
node_apiclient -->|"HTTP calls"| node_api
node_api -->|"dispatch"| node_auth
node_api -->|"dispatch"| node_users
node_api -->|"dispatch"| node_catalog
node_api -->|"dispatch"| node_devices
node_api -->|"dispatch"| node_requests
node_api -->|"dispatch"| node_maintenance
node_api -->|"dispatch"| node_stats
node_api -->|"dispatch"| node_audit
node_api -->|"dispatch"| node_ai
node_auth -->|"verify identity"| node_access
node_auth -->|"read and write"| node_models
node_auth -->|"record events"| node_auditservice
node_users -->|"read and write"| node_models
node_catalog -->|"read and write"| node_models
node_devices -->|"read and write"| node_models
node_requests -->|"read and write"| node_models
node_maintenance -->|"read and write"| node_models
node_stats -->|"query"| node_models
node_audit -->|"query"| node_models
node_auditservice -->|"create log"| node_models
node_models -->|"persist"| node_database
node_ai -->|"invoke"| node_aiservice
node_aiservice -->|"query context"| node_models
node_aiservice -->|"send prompt"| node_ollama
node_ollama -->|"HTTP inference"| node_ollamasvc
node_documents -->|"seed chunks"| node_database

click node_webapp "https://github.com/cyberbount/ai-lems/blob/main/frontend/src/App.jsx"
click node_apiclient "https://github.com/cyberbount/ai-lems/blob/main/frontend/src/lib/api.js"
click node_api "https://github.com/cyberbount/ai-lems/blob/main/backend/app/main.py"
click node_auth "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/auth.py"
click node_access "https://github.com/cyberbount/ai-lems/blob/main/backend/app/deps.py"
click node_users "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/users.py"
click node_catalog "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/catalog.py"
click node_devices "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/devices.py"
click node_requests "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/requests.py"
click node_maintenance "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/maintenance.py"
click node_stats "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/stats.py"
click node_audit "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/audit.py"
click node_auditservice "https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/audit_service.py"
click node_models "https://github.com/cyberbount/ai-lems/blob/main/backend/app/models.py"
click node_database "https://github.com/cyberbount/ai-lems/blob/main/backend/app/db.py"
click node_ai "https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/ai.py"
click node_aiservice "https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/ai_service.py"
click node_documents "https://github.com/cyberbount/ai-lems/blob/main/scripts/seed_sop_documents.py"
click node_ollama "https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/ollama_provider.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_apiclient,node_people toneBlue
class node_api,node_auth,node_access,node_models,node_database toneAmber
class node_users,node_catalog,node_devices,node_requests,node_maintenance,node_stats,node_audit,node_auditservice,node_ollamasvc toneMint
class node_ai,node_aiservice,node_documents,node_ollama toneRose
```

## Components

### Web interface

- [React application](https://github.com/cyberbount/ai-lems/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/cyberbount/ai-lems/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`

### API and access

- [FastAPI app](https://github.com/cyberbount/ai-lems/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [JWT and roles](https://github.com/cyberbount/ai-lems/blob/main/backend/app/deps.py): `backend/app/deps.py`
- [Domain models](https://github.com/cyberbount/ai-lems/blob/main/backend/app/models.py): `backend/app/models.py`
- [SQL database](https://github.com/cyberbount/ai-lems/blob/main/backend/app/db.py): `backend/app/db.py`

### Lab operations

- [User management](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/users.py): `backend/app/routers/users.py`
- [Equipment catalog](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/catalog.py): `backend/app/routers/catalog.py`
- [Equipment management](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/devices.py): `backend/app/routers/devices.py`
- [Borrow and return](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/requests.py): `backend/app/routers/requests.py`
- [Maintenance](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/maintenance.py): `backend/app/routers/maintenance.py`
- [Usage statistics](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/stats.py): `backend/app/routers/stats.py`
- [Audit history](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/audit.py): `backend/app/routers/audit.py`
- [Audit recording](https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`

### Local AI

- [AI chat route](https://github.com/cyberbount/ai-lems/blob/main/backend/app/routers/ai.py): `backend/app/routers/ai.py`
- [Context and retrieval](https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/ai_service.py): `backend/app/services/ai_service.py`
- [SOP document chunks](https://github.com/cyberbount/ai-lems/blob/main/scripts/seed_sop_documents.py): `scripts/seed_sop_documents.py`
- [Ollama local service](https://github.com/cyberbount/ai-lems/blob/main/backend/app/services/ollama_provider.py): `backend/app/services/ollama_provider.py`

### Other components

- **Lab users**
- **Ollama HTTP API**

## Connections

- Lab users → React application: use
- React application → API client: request
- API client → FastAPI app: HTTP calls
- FastAPI app → Authentication: dispatch
- FastAPI app → User management: dispatch
- FastAPI app → Equipment catalog: dispatch
- FastAPI app → Equipment management: dispatch
- FastAPI app → Borrow and return: dispatch
- FastAPI app → Maintenance: dispatch
- FastAPI app → Usage statistics: dispatch
- FastAPI app → Audit history: dispatch
- FastAPI app → AI chat route: dispatch
- Authentication → JWT and roles: verify identity
- Authentication → Domain models: read and write
- Authentication → Audit recording: record events
- User management → Domain models: read and write
- Equipment catalog → Domain models: read and write
- Equipment management → Domain models: read and write
- Borrow and return → Domain models: read and write
- Maintenance → Domain models: read and write
- Usage statistics → Domain models: query
- Audit history → Domain models: query
- Audit recording → Domain models: create log
- Domain models → SQL database: persist
- AI chat route → Context and retrieval: invoke
- Context and retrieval → Domain models: query context
- Context and retrieval → Ollama local service: send prompt
- Ollama local service → Ollama HTTP API: HTTP inference
- SOP document chunks → SQL database: seed chunks