# bhuvan-s-prasad/intelliops architecture

> Architecture diagram of the GitHub repository bhuvan-s-prasad/intelliops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhuvan-s-prasad/intelliops
- Repository: https://github.com/bhuvan-s-prasad/intelliops

## Overview

1. **What this repo is**
   - IntelliOps is a multi-tenant Next.js 16 application for operational intelligence: users join workspaces, upload operational documents, query them with AI, and view workspace-level insights and telemetry.
   - The architecture centers on a single web app that combines UI, server routes, background-style processing, and AI retrieval logic in one codebase.

2. **Top-level application boundaries**
   - `app/(auth)` contains public authentication flows backed by Clerk sign-in/sign-up pages.
   - `app/(dashboard)` is the protected product surface: workspace dashboard, chat, files, search, insights, settings, and workspace-scoped routes under `app/(dashboard)/[workspaceSlug]`.
   - `app/onboarding` handles post-auth workspace setup or first-run flow.
   - `app/api` contains all server-side business logic exposed as Next.js route handlers.

3. **Workspace is the main tenant boundary**
   - Nearly all business data is scoped to a workspace, and the route structure mirrors that boundary.
   - Workspace pages and API routes use workspace identifiers/slugs to isolate files, conversations, members, insights, and stats.
   - `components/workspace-provider.tsx` and the dashboard shell coordinate active workspace context in the client.

4. **Authentication and identity sync**
   - Clerk is the identity system; `app/api/webhooks/clerk/route.ts` syncs user lifecycle changes into the app database.
   - `lib/auth.ts` centralizes server-side auth checks used by protected API routes.
   - The app treats Clerk as the source of truth for identity, while Prisma/Postgres stores app-specific relationships like workspace membership and content ownership.

5. **Core backend surface**
   - The API is organized around workspace resources:
     - workspaces and members
     - files and file-specific insights
     - conversations and streamed messages
     - search and stats
     - insight generation
   - This is a REST-style route layer built on Next.js App Router handlers, not a separate backend service.

6. **Data persistence layer**
   - Prisma is the ORM, backed by PostgreSQL in Neon according to the README.
   - `prisma/schema.prisma` and migrations define the main entities: User, Workspace, WorkspaceMember, File, Chunk, Conversation, Message, Insight, and AuditLog.
   - Chunks store embeddings, so the database is not just relational storage; it is also the retrieval index for semantic search.

7. **File ingestion pipeline**
   - Uploaded files are stored externally, likely through `lib/storage.ts` and pre-signed upload flow in the files API.
   - `lib/file-processor.ts` and the parsers under `lib/parsers/*` normalize multiple formats: PDF, CSV, JSON, logs, text, and images.
   - `lib/chunker.ts` splits extracted content into searchable chunks, which are then embedded by `lib/embedder.ts` and persisted through Prisma.
   - This pipeline is asynchronous in spirit: upload first, then process/index, then expose the file as ready for search and insight generation.

8. **Retrieval and chat flow**
   - User chat requests hit `app/api/workspaces/[workspaceId]/conversations/[conversationId]/messages/route.ts`, which is the main RAG entrypoint.
   - The retrieval stack is split into distinct steps in `lib/query-rewriter.ts`, `lib/reranker.ts`, and related search logic:
     - rewrite the query
     - retrieve relevant chunks from vector/full-text search
     - rerank results
     - stream an AI response back to the client
   - The README describes hybrid retrieval and streamed completions; the UI likely consumes these streams in the dashboard chat experience.

9. **Search, insights, and telemetry**
   - Search is available both as a dedicated workspace endpoint and as a dashboard page.
   - Insight generation is a separate concern from chat: `lib/insight-generator.ts` and the insights API produce reusable file/workspace insights, likely stored as `Insight` records.
   - `app/api/workspaces/[workspaceId]/stats/route.ts` and the dashboard views support operational telemetry such as file counts, storage, and activity.

10. **Cross-cutting infrastructure**
   - `lib/rate-limit.ts` and `lib/cache.ts` suggest Redis-backed protection and caching for expensive endpoints like AI search, uploads, and stats.
   - Supabase is used as S3-compatible object storage for uploaded files.
   - The `proxy.ts` file indicates request-level routing or protection at the edge, likely for auth/session gating.
   - `lib/utils.ts` and the shared UI components under `components/ui` support consistency across pages but do not define core architecture.

11. **Client-side composition**
   - `components/dashboard-shell.tsx`, `components/command-palette.tsx`, and `components/empty-state.tsx` provide the main authenticated UX frame.
   - `components/insights/insight-card.tsx` and `components/skeleton.tsx` are presentation primitives for the dashboard and loading states.
   - The app uses a component-library style approach (`components/ui/*`) rather than bespoke UI per screen.

12. **Operational and codebase signals**
   - Prisma migrations show schema evolution around the initial data model, insights, and image file support.
   - `scratch/test-rag.ts` suggests retrieval behavior has been tested or prototyped locally outside the main app flow.
   - Overall, the system is best diagrammed as: browser UI → Next.js route handlers → auth/RBAC checks → Prisma/Postgres + Redis + storage + AI provider, with workspace isolation enforced at every boundary.

Main entry points: [`app/api/workspaces/[workspaceId]`](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/api/workspaces/[workspaceId]) (Workspace API), [`lib/file-processor.ts`](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/file-processor.ts) (File processor), [`lib/prisma.ts`](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/prisma.ts) (Prisma client), [`app`](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app) (IntelliOps)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Next app"]
  node_node_auth["Auth UI<br/>public routes"]
  node_node_dashboard["Dashboard<br/>protected routes"]
  node_node_workspace_pages["Workspace pages<br/>workspace UI"]
  node_node_onboarding["Onboarding<br/>first-run flow"]
  node_node_api["API surface<br/>route handlers"]
  node_node_webhook["Clerk webhook<br/>identity sync<br/>[route.ts]"]
  node_node_workspace_api["Workspace API<br/>tenant REST"]
end

subgraph group_grp_lib["Core logic"]
  node_node_auth_lib["Auth checks<br/>server auth<br/>[auth.ts]"]
  node_node_processor["File processor<br/>ingestion pipeline<br/>[file-processor.ts]"]
  node_node_parsers["Parsers<br/>format adapters"]
  node_node_chunker["Chunker<br/>document split<br/>[chunker.ts]"]
  node_node_embedder["Embedder<br/>vector model<br/>[embedder.ts]"]
  node_node_query["Query stack<br/>rag pipeline<br/>[query-rewriter.ts]"]
  node_node_insights["Insight generator<br/>analysis engine"]
  node_node_storage["Storage<br/>object store<br/>[storage.ts]"]
  node_node_cache["Cache<br/>[cache.ts]"]
  node_node_rate_limit["Rate limit<br/>request guard<br/>[rate-limit.ts]"]
  node_node_prisma["Prisma client<br/>db access<br/>[prisma.ts]"]
end

subgraph group_grp_ui["Shared UI"]
  node_node_dashboard_shell["Dashboard shell<br/>client shell"]
  node_node_workspace_provider["Workspace provider<br/>context"]
  node_node_command_palette["Command palette<br/>ux utility"]
  node_node_insight_card["Insight card<br/>presentation<br/>[insight-card.tsx]"]
end

subgraph group_grp_data["Data layer"]
  node_node_schema["Schema<br/>postgres model<br/>[schema.prisma]"]
  node_node_migrations["Migrations<br/>schema history"]
end

node_node_root["IntelliOps<br/>nextjs app"]

node_node_root -->|"public auth"| node_node_auth
node_node_root -->|"product app"| node_node_dashboard
node_node_root -->|"first run"| node_node_onboarding
node_node_root -->|"server routes"| node_node_api
node_node_dashboard -->|"uses"| node_node_dashboard_shell
node_node_dashboard_shell -->|"context"| node_node_workspace_provider
node_node_dashboard -->|"workspace routes"| node_node_workspace_pages
node_node_dashboard_shell -->|"includes"| node_node_command_palette
node_node_workspace_pages -->|"renders"| node_node_insight_card
node_node_api -->|"clerk sync"| node_node_webhook
node_node_api -->|"tenant api"| node_node_workspace_api
node_node_workspace_api -->|"guards"| node_node_auth_lib
node_node_workspace_api -->|"reads/writes"| node_node_prisma
node_node_webhook -->|"syncs users"| node_node_prisma
node_node_processor -->|"normalizes"| node_node_parsers
node_node_processor -->|"splits"| node_node_chunker
node_node_processor -->|"indexes"| node_node_embedder
node_node_processor -->|"stores files"| node_node_storage
node_node_processor -->|"persists"| node_node_prisma
node_node_workspace_api -->|"ingest files"| node_node_processor
node_node_workspace_api -->|"chat/search"| node_node_query
node_node_workspace_api -->|"generate insights"| node_node_insights
node_node_query -->|"retrieves chunks"| node_node_prisma
node_node_query -->|"caches"| node_node_cache
node_node_query -->|"throttles"| node_node_rate_limit
node_node_insights -->|"stores insights"| node_node_prisma
node_node_prisma -->|"models"| node_node_schema
node_node_schema -->|"evolves via"| node_node_migrations

click node_node_root "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app"
click node_node_auth "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/(auth)"
click node_node_dashboard "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/(dashboard)"
click node_node_workspace_pages "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/(dashboard)/[workspaceSlug]"
click node_node_onboarding "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/onboarding"
click node_node_api "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/api"
click node_node_webhook "https://github.com/bhuvan-s-prasad/intelliops/blob/main/app/api/webhooks/clerk/route.ts"
click node_node_workspace_api "https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/api/workspaces/[workspaceId]"
click node_node_dashboard_shell "https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/dashboard-shell.tsx"
click node_node_workspace_provider "https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/workspace-provider.tsx"
click node_node_command_palette "https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/command-palette.tsx"
click node_node_insight_card "https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/insights/insight-card.tsx"
click node_node_auth_lib "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/auth.ts"
click node_node_processor "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/file-processor.ts"
click node_node_parsers "https://github.com/bhuvan-s-prasad/intelliops/tree/main/lib/parsers"
click node_node_chunker "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/chunker.ts"
click node_node_embedder "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/embedder.ts"
click node_node_query "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/query-rewriter.ts"
click node_node_insights "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/insight-generator.ts"
click node_node_storage "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/storage.ts"
click node_node_cache "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/cache.ts"
click node_node_rate_limit "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/rate-limit.ts"
click node_node_prisma "https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/prisma.ts"
click node_node_schema "https://github.com/bhuvan-s-prasad/intelliops/blob/main/prisma/schema.prisma"
click node_node_migrations "https://github.com/bhuvan-s-prasad/intelliops/tree/main/prisma/migrations"

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_node_auth,node_node_dashboard,node_node_workspace_pages,node_node_onboarding,node_node_api,node_node_webhook,node_node_workspace_api toneBlue
class node_node_auth_lib,node_node_processor,node_node_parsers,node_node_chunker,node_node_embedder,node_node_query,node_node_insights,node_node_storage,node_node_cache,node_node_rate_limit,node_node_prisma toneAmber
class node_node_dashboard_shell,node_node_workspace_provider,node_node_command_palette,node_node_insight_card toneMint
class node_node_schema,node_node_migrations toneRose
class node_node_root toneNeutral
```

## Components

### Next app

Route groups and page surfaces for auth, onboarding, dashboard, and API handlers.

- [Auth UI](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/(auth)): public routes · Clerk-backed sign-in and sign-up flows. · `app/(auth)`
- [Dashboard](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/(dashboard)): protected routes · Workspace product surface for chat, files, search, insights, and settings. · `app/(dashboard)`
- [Workspace pages](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/(dashboard)/[workspaceSlug]): workspace UI · Workspace-slug routes for dashboard, chat, files, search, and insights. · `app/(dashboard)/[workspaceSlug]`
- [Onboarding](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/onboarding): first-run flow · Post-auth workspace setup and entry flow. · `app/onboarding`
- [API surface](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/api): route handlers · Next.js route handlers for workspaces, files, conversations, search, stats, insights, and webhooks. · `app/api`
- [Clerk webhook](https://github.com/bhuvan-s-prasad/intelliops/blob/main/app/api/webhooks/clerk/route.ts): identity sync · Syncs Clerk user lifecycle events into app data. · `app/api/webhooks/clerk/route.ts`
- [Workspace API](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app/api/workspaces/[workspaceId]): tenant REST · Workspace-scoped CRUD and query endpoints for members, files, conversations, search, stats, and insights. · `app/api/workspaces/[workspaceId]`

### Core logic

Shared server-side services for auth, ingestion, retrieval, caching, and persistence.

- [Auth checks](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/auth.ts): server auth · Server-side workspace and user authorization helpers. · `lib/auth.ts`
- [File processor](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/file-processor.ts): ingestion pipeline · Orchestrates file normalization, parsing, chunking, and indexing. · `lib/file-processor.ts`
- [Parsers](https://github.com/bhuvan-s-prasad/intelliops/tree/main/lib/parsers): format adapters · Input adapters for PDF, CSV, JSON, logs, text, and images. · `lib/parsers`
- [Chunker](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/chunker.ts): document split · Splits extracted content into retrieval-ready chunks. · `lib/chunker.ts`
- [Embedder](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/embedder.ts): vector model · Generates embeddings for chunk storage and semantic retrieval. · `lib/embedder.ts`
- [Query stack](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/query-rewriter.ts): rag pipeline · Query rewriting, reranking, and streamed response assembly for chat and search. · `lib/query-rewriter.ts`
- [Insight generator](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/insight-generator.ts): analysis engine · Produces reusable file and workspace insights. · `lib/insight-generator.ts`
- [Storage](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/storage.ts): object store · External file storage and pre-signed upload support. · `lib/storage.ts`
- [Cache](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/cache.ts): redis cache · Caching and rate protection for expensive operations. · `lib/cache.ts`
- [Rate limit](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/rate-limit.ts): request guard · Protects AI, upload, and stats endpoints from abuse. · `lib/rate-limit.ts`
- [Prisma client](https://github.com/bhuvan-s-prasad/intelliops/blob/main/lib/prisma.ts): db access · Database access layer for workspace, file, conversation, and insight records. · `lib/prisma.ts`

### Shared UI

Reusable dashboard shell and presentation components.

- [Dashboard shell](https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/dashboard-shell.tsx): client shell · Authenticated UI frame and active workspace context provider. · `components/dashboard-shell.tsx`
- [Workspace provider](https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/workspace-provider.tsx): context · Client-side active workspace state and selection coordination. · `components/workspace-provider.tsx`
- [Command palette](https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/command-palette.tsx): ux utility · Global dashboard navigation and quick actions. · `components/command-palette.tsx`
- [Insight card](https://github.com/bhuvan-s-prasad/intelliops/blob/main/components/insights/insight-card.tsx): presentation · Reusable insight display component for dashboard views. · `components/insights/insight-card.tsx`

### Data layer

Database schema and migration history for the app domain.

- [Schema](https://github.com/bhuvan-s-prasad/intelliops/blob/main/prisma/schema.prisma): postgres model · Core entities for users, workspaces, files, chunks, conversations, messages, insights, and audit logs. · `prisma/schema.prisma`
- [Migrations](https://github.com/bhuvan-s-prasad/intelliops/tree/main/prisma/migrations): schema history · Database evolution for the initial model, insights, and image file support. · `prisma/migrations`

### Other components

- [IntelliOps](https://github.com/bhuvan-s-prasad/intelliops/tree/main/app): nextjs app · Multi-tenant operational intelligence app with workspace-scoped AI search and insights. · `app`

## Connections

- IntelliOps → Auth UI: public auth · Routes unauthenticated users into sign-in and sign-up.
- IntelliOps → Dashboard: product app · Main authenticated application surface.
- IntelliOps → Onboarding: first run · Guides new users through workspace setup.
- IntelliOps → API surface: server routes · App API is the backend surface of the monorepo-style Next app.
- Dashboard → Dashboard shell: uses · Dashboard pages are wrapped by the shared shell.
- Dashboard shell → Workspace provider: context · Shell coordinates active workspace state.
- Dashboard → Workspace pages: workspace routes · Workspace-slug pages render the tenant-scoped product views.
- Dashboard shell → Command palette: includes · Global navigation and command entry.
- Workspace pages → Insight card: renders · Workspace views reuse insight presentation.
- API surface → Clerk webhook: clerk sync · Webhook endpoint ingests identity lifecycle events.
- API surface → Workspace API: tenant api · Workspace endpoints implement core business operations.
- Workspace API → Auth checks: guards · Protected routes validate user and workspace access.
- Workspace API → Prisma client: reads/writes · Workspace operations persist through Prisma.
- Clerk webhook → Prisma client: syncs users · Clerk events update app identity records.
- File processor → Parsers: normalizes · File processor delegates format-specific extraction.
- File processor → Chunker: splits · Extracted content is chunked for retrieval.
- File processor → Embedder: indexes · Chunks are embedded before persistence.
- File processor → Storage: stores files · Uploaded originals are kept in external object storage.
- File processor → Prisma client: persists · File, chunk, and processing state are saved in the database.
- Workspace API → File processor: ingest files · File upload endpoints trigger processing pipeline.
- Workspace API → Query stack: chat/search · Conversation and search endpoints use the retrieval pipeline.
- Workspace API → Insight generator: generate insights · Insight endpoints build reusable analysis artifacts.
- Query stack → Prisma client: retrieves chunks · Hybrid retrieval reads indexed workspace data.
- Query stack → Cache: caches · Expensive query work may be cached.
- Query stack → Rate limit: throttles · Protects high-cost conversational endpoints.
- Insight generator → Prisma client: stores insights · Generated insights are persisted for later display.
- Prisma client → Schema: models · Prisma client is backed by the schema definition.
- Schema → Migrations: evolves via · Schema changes are tracked through migrations.
