# kyan9400/opsmind architecture

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

- Interactive diagram: https://gitdiagram.com/kyan9400/opsmind
- Repository: https://github.com/kyan9400/opsmind

## Overview

OpsMind is a multi-tenant operations platform combining document-grounded answers, document indexing, KPI analytics and anomaly summaries. The main user flow is browser → API: users upload documents for asynchronous indexing, then ask questions and receive cited answers; the analytics dashboard shows KPI trends and anomalies. The API also handles identity, tenant/role checks, audit and exports. The README documents the API/worker/AI-service boundaries and storage, but several route and web implementations were not sampled, so some documented links use the README as evidence.

Main entry points: [`services/ai/app/main.py`](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/main.py) (AI service endpoints), [`apps/api/src/lib/db.ts`](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/db.ts) (Postgres and pgvector), [`apps/api/src/app.ts`](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/app.ts) (Express API), [`apps/api/src/routes/metrics.ts`](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/metrics.ts) (KPI and reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web["Next.js dashboard<br/>[page.tsx]"]
  node_webdocs["Documents view<br/>[page.tsx]"]
  node_webask["Ask view<br/>[page.tsx]"]
  node_analytics["Analytics view<br/>[page.tsx]"]
  node_authui["Sign-in view<br/>[page.tsx]"]
end

subgraph group_api["API and tenancy"]
  node_auth["Authentication routes<br/>[auth.ts]"]
  node_authmw["Auth and role checks<br/>[auth.ts]"]
  node_documents["Document routes<br/>[documents.ts]"]
  node_ask["Question routes<br/>[ask.ts]"]
  node_metrics["KPI and reports<br/>[metrics.ts]"]
  node_app["Express API<br/>[app.ts]"]
end

subgraph group_indexing["Document indexing"]
  node_worker["Ingest worker<br/>[worker.ts]"]
  node_ingest["Ingest orchestration<br/>[ingest.ts]"]
  node_queue["Job queue<br/>[queue.ts]"]
end

subgraph group_ai["AI and analytics"]
  node_ai["AI service endpoints<br/>[main.py]"]
  node_extract["Text extraction<br/>[extract.py]"]
  node_chunk["Text chunking<br/>[chunking.py]"]
  node_embed["Embedding providers<br/>[embeddings.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_llm["Cited answer generation<br/>[llm.py]"]
  node_insights["Anomaly and summaries<br/>[insights.py]"]
end

subgraph group_state["Shared state"]
  node_db[("Postgres and pgvector<br/>[db.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
end

node_browser(("Business user"))
node_providers["LLM and embedding providers"]

node_browser -->|"uses"| node_web
node_web -->|"calls REST API"| node_app
node_browser -->|"signs in"| node_authui
node_authui -.->|"authenticates"| node_auth
node_app -->|"mounts"| node_auth
node_app -->|"mounts"| node_documents
node_app -->|"mounts"| node_ask
node_app -->|"mounts"| node_metrics
node_auth -->|"reads and writes"| node_db
node_auth -->|"protects profile"| node_authmw
node_authmw -->|"checks membership"| node_db
node_documents -->|"enqueues uploads"| node_queue
node_documents -->|"stores document state"| node_db
node_queue -->|"dispatches jobs"| node_worker
node_worker -->|"runs ingestion"| node_ingest
node_ingest -->|"posts ingest request"| node_ai
node_ai -->|"extracts text"| node_extract
node_ai -->|"chunks text"| node_chunk
node_ai -->|"embeds chunks"| node_embed
node_ai -->|"stores chunks and vectors"| node_db
node_webask -.->|"submits questions"| node_ask
node_ask -->|"requests cited answer"| node_ai
node_ai -->|"embeds query"| node_embed
node_ai -->|"searches candidates"| node_retrieval
node_retrieval -->|"searches tenant chunks"| node_db
node_ai -->|"generates answer"| node_llm
node_llm -->|"calls configured provider"| node_providers
node_web -->|"opens analytics"| node_analytics
node_analytics -.->|"requests KPI data"| node_metrics
node_metrics -->|"requests insights"| node_ai
node_ai -->|"computes summaries"| node_insights
node_insights -->|"summarizes metrics"| node_llm
node_metrics -->|"reads KPI data"| node_db
node_metrics -->|"uses cache"| node_redis

click node_web "https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/page.tsx"
click node_webdocs "https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/documents/page.tsx"
click node_webask "https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/ask/page.tsx"
click node_analytics "https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/analytics/page.tsx"
click node_authui "https://github.com/kyan9400/opsmind/blob/main/apps/web/app/login/page.tsx"
click node_auth "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/auth.ts"
click node_authmw "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/middleware/auth.ts"
click node_documents "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/documents.ts"
click node_ask "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/ask.ts"
click node_metrics "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/metrics.ts"
click node_app "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/app.ts"
click node_worker "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/worker.ts"
click node_ingest "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/ingest.ts"
click node_queue "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/queue.ts"
click node_ai "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/main.py"
click node_extract "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/extract.py"
click node_chunk "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/chunking.py"
click node_embed "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/embeddings.py"
click node_retrieval "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/retrieval.py"
click node_llm "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/llm.py"
click node_insights "https://github.com/kyan9400/opsmind/blob/main/services/ai/app/insights.py"
click node_db "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/db.ts"
click node_redis "https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/redis.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_web,node_webdocs,node_webask,node_analytics,node_authui,node_browser toneBlue
class node_auth,node_authmw,node_documents,node_ask,node_metrics,node_app toneAmber
class node_worker,node_ingest,node_queue toneMint
class node_ai,node_extract,node_chunk,node_embed,node_retrieval,node_llm,node_insights toneRose
class node_db,node_redis,node_providers toneIndigo
```

## Components

### Web experience

- [Next.js dashboard](https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/page.tsx): `apps/web/app/dashboard/page.tsx`
- [Documents view](https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/documents/page.tsx): `apps/web/app/dashboard/documents/page.tsx`
- [Ask view](https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/ask/page.tsx): `apps/web/app/dashboard/ask/page.tsx`
- [Analytics view](https://github.com/kyan9400/opsmind/blob/main/apps/web/app/dashboard/analytics/page.tsx): `apps/web/app/dashboard/analytics/page.tsx`
- [Sign-in view](https://github.com/kyan9400/opsmind/blob/main/apps/web/app/login/page.tsx): `apps/web/app/login/page.tsx`

### API and tenancy

- [Authentication routes](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/auth.ts): `apps/api/src/routes/auth.ts`
- [Auth and role checks](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`
- [Document routes](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/documents.ts): `apps/api/src/routes/documents.ts`
- [Question routes](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/ask.ts): `apps/api/src/routes/ask.ts`
- [KPI and reports](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/routes/metrics.ts): `apps/api/src/routes/metrics.ts`
- [Express API](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`

### Document indexing

- [Ingest worker](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/worker.ts): `apps/api/src/worker.ts`
- [Ingest orchestration](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/ingest.ts): `apps/api/src/lib/ingest.ts`
- [Job queue](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/queue.ts): `apps/api/src/lib/queue.ts`

### AI and analytics

- [AI service endpoints](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/main.py): `services/ai/app/main.py`
- [Text extraction](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/extract.py): `services/ai/app/extract.py`
- [Text chunking](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/chunking.py): `services/ai/app/chunking.py`
- [Embedding providers](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/embeddings.py): `services/ai/app/embeddings.py`
- [Hybrid retrieval](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/retrieval.py): `services/ai/app/retrieval.py`
- [Cited answer generation](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/llm.py): `services/ai/app/llm.py`
- [Anomaly and summaries](https://github.com/kyan9400/opsmind/blob/main/services/ai/app/insights.py): `services/ai/app/insights.py`

### Shared state

- [Postgres and pgvector](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/db.ts): `apps/api/src/lib/db.ts`
- [Redis](https://github.com/kyan9400/opsmind/blob/main/apps/api/src/lib/redis.ts): `apps/api/src/lib/redis.ts`

### Other components

- **Business user**
- **LLM and embedding providers**

## Connections

- Business user → Next.js dashboard: uses
- Next.js dashboard → Express API: calls REST API
- Business user → Sign-in view: signs in
- Sign-in view → Authentication routes: authenticates
- Express API → Authentication routes: mounts (evidence: `apps/api/src/app.ts`)
- Express API → Document routes: mounts (evidence: `apps/api/src/app.ts`)
- Express API → Question routes: mounts (evidence: `apps/api/src/app.ts`)
- Express API → KPI and reports: mounts (evidence: `apps/api/src/app.ts`)
- Authentication routes → Postgres and pgvector: reads and writes (evidence: `apps/api/src/routes/auth.ts`)
- Authentication routes → Auth and role checks: protects profile (evidence: `apps/api/src/routes/auth.ts`)
- Auth and role checks → Postgres and pgvector: checks membership (evidence: `apps/api/src/middleware/auth.ts`)
- Document routes → Job queue: enqueues uploads (evidence: `apps/api/src/routes/documents.ts`)
- Document routes → Postgres and pgvector: stores document state (evidence: `apps/api/src/routes/documents.ts`)
- Job queue → Ingest worker: dispatches jobs (evidence: `apps/api/src/worker.ts`)
- Ingest worker → Ingest orchestration: runs ingestion (evidence: `apps/api/src/worker.ts`)
- Ingest orchestration → AI service endpoints: posts ingest request (evidence: `apps/api/src/lib/ingest.ts`)
- AI service endpoints → Text extraction: extracts text (evidence: `services/ai/app/main.py`)
- AI service endpoints → Text chunking: chunks text (evidence: `services/ai/app/main.py`)
- AI service endpoints → Embedding providers: embeds chunks (evidence: `services/ai/app/main.py`)
- AI service endpoints → Postgres and pgvector: stores chunks and vectors
- Ask view → Question routes: submits questions
- Question routes → AI service endpoints: requests cited answer
- AI service endpoints → Embedding providers: embeds query (evidence: `services/ai/app/main.py`)
- AI service endpoints → Hybrid retrieval: searches candidates (evidence: `services/ai/app/main.py`)
- Hybrid retrieval → Postgres and pgvector: searches tenant chunks (evidence: `services/ai/app/retrieval.py`)
- AI service endpoints → Cited answer generation: generates answer (evidence: `services/ai/app/main.py`)
- Cited answer generation → LLM and embedding providers: calls configured provider (evidence: `services/ai/app/llm.py`)
- Next.js dashboard → Analytics view: opens analytics
- Analytics view → KPI and reports: requests KPI data
- KPI and reports → AI service endpoints: requests insights
- AI service endpoints → Anomaly and summaries: computes summaries (evidence: `services/ai/app/main.py`)
- Anomaly and summaries → Cited answer generation: summarizes metrics (evidence: `services/ai/app/insights.py`)
- KPI and reports → Postgres and pgvector: reads KPI data (evidence: `apps/api/src/routes/metrics.ts`)
- KPI and reports → Redis: uses cache (evidence: `apps/api/src/routes/metrics.ts`)