How bhuvan-s-prasad/intelliops works
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: [workspaceId] Workspace API · file-processor.ts File processor · prisma.ts Prisma client · app IntelliOps
Components 25
Next app
Route groups and page surfaces for auth, onboarding, dashboard, and API handlers.
- Auth UI · Clerk-backed sign-in and sign-up flows.
app/(auth) - Dashboard · Workspace product surface for chat, files, search, insights, and settings.
app/(dashboard) - Workspace pages · Workspace-slug routes for dashboard, chat, files, search, and insights.
app/(dashboard)/[workspaceSlug] - Onboarding · Post-auth workspace setup and entry flow.
app/onboarding - API surface · Next.js route handlers for workspaces, files, conversations, search, stats, insights, and webhooks.
app/api - Clerk webhook · Syncs Clerk user lifecycle events into app data.
app/api/webhooks/clerk/route.ts - Workspace API · 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 · Server-side workspace and user authorization helpers.
lib/auth.ts - File processor · Orchestrates file normalization, parsing, chunking, and indexing.
lib/file-processor.ts - Parsers · Input adapters for PDF, CSV, JSON, logs, text, and images.
lib/parsers - Chunker · Splits extracted content into retrieval-ready chunks.
lib/chunker.ts - Embedder · Generates embeddings for chunk storage and semantic retrieval.
lib/embedder.ts - Query stack · Query rewriting, reranking, and streamed response assembly for chat and search.
lib/query-rewriter.ts - Insight generator · Produces reusable file and workspace insights.
lib/insight-generator.ts - Storage · External file storage and pre-signed upload support.
lib/storage.ts - Cache · Caching and rate protection for expensive operations.
lib/cache.ts - Rate limit · Protects AI, upload, and stats endpoints from abuse.
lib/rate-limit.ts - Prisma client · Database access layer for workspace, file, conversation, and insight records.
lib/prisma.ts
Shared UI
Reusable dashboard shell and presentation components.
- Dashboard shell · Authenticated UI frame and active workspace context provider.
components/dashboard-shell.tsx - Workspace provider · Client-side active workspace state and selection coordination.
components/workspace-provider.tsx - Command palette · Global dashboard navigation and quick actions.
components/command-palette.tsx - Insight card · Reusable insight display component for dashboard views.
components/insights/insight-card.tsx
Data layer
Database schema and migration history for the app domain.
- Schema · Core entities for users, workspaces, files, chunks, conversations, messages, insights, and audit logs.
prisma/schema.prisma - Migrations · Database evolution for the initial model, insights, and image file support.
prisma/migrations
Other components
- IntelliOps · Multi-tenant operational intelligence app with workspace-scoped AI search and insights.
app
Connections 28
- 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.