# prosofproest/lablens architecture

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

- Interactive diagram: https://gitdiagram.com/prosofproest/lablens
- Repository: https://github.com/prosofproest/lablens

## Overview

LabLens AI turns laboratory equipment faults into tracked maintenance tickets: users authenticate, submit structured reports with optional photos and AI-assisted triage, and follow status; administrators review institutional metrics, assign technicians, override triage, and audit changes. The graph separates intake, operations, AI, and shared platform services. Sampled source confirms key route-handler calls; several UI and data subsystems are represented from README claims and the source index, so their undocumented wiring is not asserted.

Main entry points: [`src/lib/firebase/reports.ts`](https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/reports.ts) (Report persistence), [`src/app/(dashboard)/admin/page.tsx`](https://github.com/prosofproest/lablens/blob/main/src/app/(dashboard)/admin/page.tsx) (Admin operations hub), [`src/components/reports/ReportFaultForm.tsx`](https://github.com/prosofproest/lablens/blob/main/src/components/reports/ReportFaultForm.tsx) (Fault report intake), [`src/app/api/reports/analyze/route.ts`](https://github.com/prosofproest/lablens/blob/main/src/app/api/reports/analyze/route.ts) (Report analysis endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Reporting and access"]
  node_authui["Sign-in and registration<br/>[page.tsx]"]
  node_reportform["Fault report intake"]
end

subgraph group_operations["Maintenance operations"]
  node_userdash["User ticket dashboard<br/>[page.tsx]"]
  node_adminhub["Admin operations hub<br/>[page.tsx]"]
  node_triagemodal["Administrative triage"]
  node_demomode["Isolated demo state<br/>[DemoContext.tsx]"]
end

subgraph group_intelligence["AI assistance"]
  node_reportapi["Report analysis endpoint<br/>[route.ts]"]
  node_triage["AI fault triage<br/>[triage.ts]"]
  node_groq["Groq inference client<br/>[client.ts]"]
  node_chatui["Floating AI assistant"]
  node_chatapi["Chat endpoint<br/>[route.ts]"]
end

subgraph group_platform["Identity and persistence"]
  node_authstate["Authentication context<br/>[AuthContext.tsx]"]
  node_reportstore[("Report persistence<br/>[reports.ts]")]
  node_audit[("Administrative audit trail<br/>[audit.ts]")]
  node_firebase["Firebase client services<br/>[client.ts]"]
  node_serverauth["Server token verification<br/>[serverAuth.ts]"]
  node_rate["Distributed rate limiting<br/>[rateLimit.ts]"]
end

subgraph group_media["Media uploads"]
  node_uploadui["Photo attachment UI<br/>[ImageUpload.tsx]"]
  node_uploadapi["Validated upload endpoint<br/>[route.ts]"]
  node_signature["Image signature validation<br/>[imageSignature.ts]"]
  node_cloudinary["Cloudinary media storage<br/>[server.ts]"]
end

node_visitor(("Visitor or user"))
node_groqservice["Groq AI service"]
node_cloudinaryservice["Cloudinary service"]
node_firebaseauth["Firebase Authentication"]
node_firestore[("Cloud Firestore")]

node_visitor -->|"signs in"| node_authui
node_authui -->|"uses auth"| node_authstate
node_authstate -->|"reads client services"| node_firebase
node_authstate -->|"authenticates"| node_firebaseauth
node_visitor -->|"reports fault"| node_reportform
node_reportform -->|"requests analysis"| node_reportapi
node_reportapi -->|"verifies token"| node_serverauth
node_reportapi -->|"checks limit"| node_rate
node_reportapi -->|"analyzes fault"| node_triage
node_triage -.->|"uses inference"| node_groq
node_groq -->|"sends inference"| node_groqservice
node_reportform -->|"creates report"| node_reportstore
node_reportform -->|"offers attachment"| node_uploadui
node_uploadui -.->|"uploads image"| node_uploadapi
node_uploadapi -->|"verifies token"| node_serverauth
node_uploadapi -->|"validates bytes"| node_signature
node_uploadapi -->|"uploads buffer"| node_cloudinary
node_cloudinary -->|"stores image"| node_cloudinaryservice
node_userdash -->|"subscribes reports"| node_reportstore
node_adminhub -->|"updates triage"| node_reportstore
node_adminhub -->|"opens triage"| node_triagemodal
node_adminhub -->|"views audit trail"| node_audit
node_adminhub -->|"uses simulated data"| node_demomode
node_demomode -->|"avoids live writes"| node_reportstore
node_chatui -->|"sends messages"| node_chatapi
node_chatapi -->|"verifies token"| node_serverauth
node_chatapi -->|"checks limit"| node_rate
node_chatapi -->|"requests completion"| node_groq
node_reportstore -->|"stores reports"| node_firestore
node_audit -->|"appends audit records"| node_firestore
node_serverauth -->|"verifies ID tokens"| node_firebaseauth

click node_authui "https://github.com/prosofproest/lablens/blob/main/src/app/(auth)/login/page.tsx"
click node_authstate "https://github.com/prosofproest/lablens/blob/main/src/context/AuthContext.tsx"
click node_reportform "https://github.com/prosofproest/lablens/blob/main/src/components/reports/ReportFaultForm.tsx"
click node_reportapi "https://github.com/prosofproest/lablens/blob/main/src/app/api/reports/analyze/route.ts"
click node_triage "https://github.com/prosofproest/lablens/blob/main/src/lib/groq/triage.ts"
click node_groq "https://github.com/prosofproest/lablens/blob/main/src/lib/groq/client.ts"
click node_chatui "https://github.com/prosofproest/lablens/blob/main/src/components/chat/FloatingChatbot.tsx"
click node_chatapi "https://github.com/prosofproest/lablens/blob/main/src/app/api/chat/route.ts"
click node_userdash "https://github.com/prosofproest/lablens/blob/main/src/app/(dashboard)/dashboard/page.tsx"
click node_adminhub "https://github.com/prosofproest/lablens/blob/main/src/app/(dashboard)/admin/page.tsx"
click node_triagemodal "https://github.com/prosofproest/lablens/blob/main/src/components/admin/AdminTriageModal.tsx"
click node_demomode "https://github.com/prosofproest/lablens/blob/main/src/context/DemoContext.tsx"
click node_reportstore "https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/reports.ts"
click node_audit "https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/audit.ts"
click node_firebase "https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/client.ts"
click node_serverauth "https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/serverAuth.ts"
click node_uploadui "https://github.com/prosofproest/lablens/blob/main/src/components/reports/ImageUpload.tsx"
click node_uploadapi "https://github.com/prosofproest/lablens/blob/main/src/app/api/upload/route.ts"
click node_signature "https://github.com/prosofproest/lablens/blob/main/src/lib/security/imageSignature.ts"
click node_cloudinary "https://github.com/prosofproest/lablens/blob/main/src/lib/cloudinary/server.ts"
click node_rate "https://github.com/prosofproest/lablens/blob/main/src/lib/groq/rateLimit.ts"

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_authui,node_reportform,node_visitor toneBlue
class node_userdash,node_adminhub,node_triagemodal,node_demomode,node_firestore toneAmber
class node_reportapi,node_triage,node_groq,node_chatui,node_chatapi toneMint
class node_authstate,node_reportstore,node_audit,node_firebase,node_serverauth,node_rate toneRose
class node_uploadui,node_uploadapi,node_signature,node_cloudinary,node_groqservice,node_cloudinaryservice,node_firebaseauth toneIndigo
```

## Components

### Reporting and access

- [Sign-in and registration](https://github.com/prosofproest/lablens/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Fault report intake](https://github.com/prosofproest/lablens/blob/main/src/components/reports/ReportFaultForm.tsx): `src/components/reports/ReportFaultForm.tsx`

### Maintenance operations

- [User ticket dashboard](https://github.com/prosofproest/lablens/blob/main/src/app/(dashboard)/dashboard/page.tsx): `src/app/(dashboard)/dashboard/page.tsx`
- [Admin operations hub](https://github.com/prosofproest/lablens/blob/main/src/app/(dashboard)/admin/page.tsx): `src/app/(dashboard)/admin/page.tsx`
- [Administrative triage](https://github.com/prosofproest/lablens/blob/main/src/components/admin/AdminTriageModal.tsx): `src/components/admin/AdminTriageModal.tsx`
- [Isolated demo state](https://github.com/prosofproest/lablens/blob/main/src/context/DemoContext.tsx): `src/context/DemoContext.tsx`

### AI assistance

- [Report analysis endpoint](https://github.com/prosofproest/lablens/blob/main/src/app/api/reports/analyze/route.ts): `src/app/api/reports/analyze/route.ts`
- [AI fault triage](https://github.com/prosofproest/lablens/blob/main/src/lib/groq/triage.ts): `src/lib/groq/triage.ts`
- [Groq inference client](https://github.com/prosofproest/lablens/blob/main/src/lib/groq/client.ts): `src/lib/groq/client.ts`
- [Floating AI assistant](https://github.com/prosofproest/lablens/blob/main/src/components/chat/FloatingChatbot.tsx): `src/components/chat/FloatingChatbot.tsx`
- [Chat endpoint](https://github.com/prosofproest/lablens/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`

### Identity and persistence

- [Authentication context](https://github.com/prosofproest/lablens/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Report persistence](https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/reports.ts): `src/lib/firebase/reports.ts`
- [Administrative audit trail](https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/audit.ts): `src/lib/firebase/audit.ts`
- [Firebase client services](https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/client.ts): `src/lib/firebase/client.ts`
- [Server token verification](https://github.com/prosofproest/lablens/blob/main/src/lib/firebase/serverAuth.ts): `src/lib/firebase/serverAuth.ts`
- [Distributed rate limiting](https://github.com/prosofproest/lablens/blob/main/src/lib/groq/rateLimit.ts): `src/lib/groq/rateLimit.ts`

### Media uploads

- [Photo attachment UI](https://github.com/prosofproest/lablens/blob/main/src/components/reports/ImageUpload.tsx): `src/components/reports/ImageUpload.tsx`
- [Validated upload endpoint](https://github.com/prosofproest/lablens/blob/main/src/app/api/upload/route.ts): `src/app/api/upload/route.ts`
- [Image signature validation](https://github.com/prosofproest/lablens/blob/main/src/lib/security/imageSignature.ts): `src/lib/security/imageSignature.ts`
- [Cloudinary media storage](https://github.com/prosofproest/lablens/blob/main/src/lib/cloudinary/server.ts): `src/lib/cloudinary/server.ts`

### Other components

- **Visitor or user**
- **Groq AI service**
- **Cloudinary service**
- **Firebase Authentication**
- **Cloud Firestore**

## Connections

- Visitor or user → Sign-in and registration: signs in (evidence: `src/app/(auth)/login/page.tsx`)
- Sign-in and registration → Authentication context: uses auth (evidence: `src/app/(auth)/login/page.tsx`)
- Authentication context → Firebase client services: reads client services (evidence: `src/context/AuthContext.tsx`)
- Authentication context → Firebase Authentication: authenticates (evidence: `src/context/AuthContext.tsx`)
- Visitor or user → Fault report intake: reports fault (evidence: `README.md`)
- Fault report intake → Report analysis endpoint: requests analysis (evidence: `README.md`)
- Report analysis endpoint → Server token verification: verifies token (evidence: `src/app/api/reports/analyze/route.ts`)
- Report analysis endpoint → Distributed rate limiting: checks limit (evidence: `src/app/api/reports/analyze/route.ts`)
- Report analysis endpoint → AI fault triage: analyzes fault (evidence: `src/app/api/reports/analyze/route.ts`)
- AI fault triage → Groq inference client: uses inference
- Groq inference client → Groq AI service: sends inference (evidence: `README.md`)
- Fault report intake → Report persistence: creates report (evidence: `src/components/reports/ReportFaultForm.tsx`)
- Fault report intake → Photo attachment UI: offers attachment (evidence: `src/components/reports/ReportFaultForm.tsx`)
- Photo attachment UI → Validated upload endpoint: uploads image
- Validated upload endpoint → Server token verification: verifies token (evidence: `src/app/api/upload/route.ts`)
- Validated upload endpoint → Image signature validation: validates bytes (evidence: `src/app/api/upload/route.ts`)
- Validated upload endpoint → Cloudinary media storage: uploads buffer (evidence: `src/app/api/upload/route.ts`)
- Cloudinary media storage → Cloudinary service: stores image (evidence: `src/lib/cloudinary/server.ts`)
- User ticket dashboard → Report persistence: subscribes reports (evidence: `src/app/(dashboard)/dashboard/page.tsx`)
- Admin operations hub → Report persistence: updates triage (evidence: `src/app/(dashboard)/admin/page.tsx`)
- Admin operations hub → Administrative triage: opens triage (evidence: `src/app/(dashboard)/admin/page.tsx`)
- Admin operations hub → Administrative audit trail: views audit trail (evidence: `README.md`)
- Admin operations hub → Isolated demo state: uses simulated data (evidence: `src/app/(dashboard)/admin/page.tsx`)
- Isolated demo state → Report persistence: avoids live writes (evidence: `README.md`)
- Floating AI assistant → Chat endpoint: sends messages (evidence: `README.md`)
- Chat endpoint → Server token verification: verifies token (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Distributed rate limiting: checks limit (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Groq inference client: requests completion (evidence: `src/app/api/chat/route.ts`)
- Report persistence → Cloud Firestore: stores reports (evidence: `README.md`)
- Administrative audit trail → Cloud Firestore: appends audit records (evidence: `README.md`)
- Server token verification → Firebase Authentication: verifies ID tokens (evidence: `src/lib/firebase/serverAuth.ts`)
