# hjariwala25/intellivault architecture

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

- Interactive diagram: https://gitdiagram.com/hjariwala25/intellivault
- Repository: https://github.com/hjariwala25/intellivault

## Overview

IntelliVault is a team-scoped document knowledge base: users upload and manage files, documents move through review and processing, and users search or chat with cited answers. The Next.js frontend calls a Hono API; API services coordinate PostgreSQL, Gemini, file storage, and email. The graph includes documented admin, audit, analytics, team, and user-management capabilities. Some subsystem links rely on the README because their implementation files were not sampled; no unsampled source behavior is assumed.

Main entry points: [`apps/web/src/hooks`](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/hooks) (API client hooks), [`apps/api/src/controllers/documents.controller.ts`](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/documents.controller.ts) (Document handling), [`apps/api/src/workers/document-processor.ts`](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/workers/document-processor.ts) (Document processor), [`apps/api/src/services/rag.service.ts`](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/rag.service.ts) (RAG orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webui["Knowledge UI"]
  node_webdocs["Document workspace"]
  node_webchat["Chat interface"]
  node_websearch["Search interface"]
  node_webadmin["Admin console"]
  node_webhooks["API client hooks"]
end

subgraph group_api["API workflows"]
  node_apiserver["Hono API<br/>[app.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_documentapi["Document handling"]
  node_documentservice["Document service"]
  node_processor["Document processor"]
  node_extract["Text extraction"]
  node_chunker["Text chunking<br/>[text-chunker.ts]"]
end

subgraph group_ai["Search and AI"]
  node_ragcontroller["RAG endpoints<br/>[rag.controller.ts]"]
  node_rag["RAG orchestration<br/>[rag.service.ts]"]
  node_search["Semantic search<br/>[search.service.ts]"]
  node_embedding["Embedding service"]
  node_llm["Answer generation<br/>[llm.service.ts]"]
end

subgraph group_governance["Teams and governance"]
  node_approval["Approval workflow"]
  node_teamsusers["Team and user management"]
  node_analytics["Analytics and audit<br/>[audit.service.ts]"]
end

subgraph group_data["Persistence and integrations"]
  node_db[("PostgreSQL and pgvector<br/>[index.ts]")]
  node_schemas[("Domain tables")]
  node_uploadthing["File storage<br/>[uploadthing.ts]"]
  node_email["Email notifications<br/>[email.service.ts]"]
  node_gemini{{"Google Gemini"}}
  node_resend{{"Resend"}}
  node_shared["Shared types and validators"]
end

node_user(("Employee or admin"))

node_user -->|"uses"| node_webui
node_webui -.->|"requests data"| node_webhooks
node_webdocs -.->|"requests document APIs"| node_webhooks
node_webchat -.->|"requests RAG APIs"| node_webhooks
node_websearch -.->|"requests search APIs"| node_webhooks
node_webadmin -.->|"requests admin APIs"| node_webhooks
node_webhooks -->|"REST / JSON"| node_apiserver
node_apiserver -.->|"authenticates"| node_auth
node_apiserver -->|"routes requests"| node_documentapi
node_documentapi -->|"calls"| node_documentservice
node_documentapi -->|"starts processing"| node_processor
node_documentapi -->|"uses file storage"| node_uploadthing
node_processor -->|"extracts text"| node_extract
node_processor -->|"chunks text"| node_chunker
node_processor -->|"generates vectors"| node_embedding
node_documentapi -->|"records actions"| node_analytics
node_webdocs -->|"review workflow"| node_approval
node_approval -->|"sends notifications"| node_email
node_email -->|"delivers email"| node_resend
node_webadmin -->|"views metrics and audit"| node_analytics
node_webadmin -->|"manages users and teams"| node_teamsusers
node_ragcontroller -->|"calls"| node_rag
node_rag -->|"retrieves context"| node_search
node_rag -->|"generates answer"| node_llm
node_search -->|"embeds query"| node_embedding
node_embedding -->|"requests embeddings"| node_gemini
node_llm -->|"generates response"| node_gemini
node_ragcontroller -->|"returns cited answers"| node_webchat
node_search -->|"serves semantic results"| node_websearch
node_documentservice -->|"reads and writes"| node_db
node_documentservice -->|"queries tables"| node_schemas
node_embedding -->|"stores vectors"| node_db
node_rag -->|"stores conversations"| node_db
node_db -->|"uses schema"| node_schemas
node_auth -->|"records auth events"| node_analytics
node_teamsusers -->|"records actions"| node_analytics
node_webhooks -.->|"uses shared contracts"| node_shared
node_ragcontroller -->|"uses shared types"| node_shared

click node_webui "https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/app"
click node_webdocs "https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/components/documents"
click node_webchat "https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/components/chat"
click node_websearch "https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/components/search"
click node_webadmin "https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/app/(dashboard)/admin"
click node_webhooks "https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/hooks"
click node_apiserver "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/app.ts"
click node_auth "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/auth.service.ts"
click node_documentapi "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/documents.controller.ts"
click node_documentservice "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/document.service.ts"
click node_processor "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/workers/document-processor.ts"
click node_extract "https://github.com/hjariwala25/intellivault/tree/master/apps/api/src/workers/extractors"
click node_chunker "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/workers/chunking/text-chunker.ts"
click node_approval "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/approval.service.ts"
click node_teamsusers "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/users.controller.ts"
click node_analytics "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/audit.service.ts"
click node_ragcontroller "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/rag.controller.ts"
click node_rag "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/rag.service.ts"
click node_search "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/search.service.ts"
click node_embedding "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/embedding.service.ts"
click node_llm "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/llm.service.ts"
click node_db "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/db/index.ts"
click node_schemas "https://github.com/hjariwala25/intellivault/tree/master/apps/api/src/db/schema"
click node_uploadthing "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/lib/uploadthing.ts"
click node_email "https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/email.service.ts"
click node_shared "https://github.com/hjariwala25/intellivault/tree/master/packages/shared/src"

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_webui,node_webdocs,node_webchat,node_websearch,node_webadmin,node_webhooks toneBlue
class node_apiserver,node_auth,node_documentapi,node_documentservice,node_processor,node_extract,node_chunker toneAmber
class node_ragcontroller,node_rag,node_search,node_embedding,node_llm toneMint
class node_approval,node_teamsusers,node_analytics toneRose
class node_db,node_schemas,node_uploadthing,node_email,node_gemini,node_resend,node_shared,node_user toneIndigo
```

## Components

### Web application

- [Knowledge UI](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/app): `apps/web/src/app`
- [Document workspace](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/components/documents): `apps/web/src/components/documents`
- [Chat interface](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/components/chat): `apps/web/src/components/chat`
- [Search interface](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/components/search): `apps/web/src/components/search`
- [Admin console](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/app/(dashboard)/admin): `apps/web/src/app/(dashboard)/admin`
- [API client hooks](https://github.com/hjariwala25/intellivault/tree/master/apps/web/src/hooks): `apps/web/src/hooks`

### API workflows

- [Hono API](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/auth.service.ts): `apps/api/src/services/auth.service.ts`
- [Document handling](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/documents.controller.ts): `apps/api/src/controllers/documents.controller.ts`
- [Document service](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/document.service.ts): `apps/api/src/services/document.service.ts`
- [Document processor](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/workers/document-processor.ts): `apps/api/src/workers/document-processor.ts`
- [Text extraction](https://github.com/hjariwala25/intellivault/tree/master/apps/api/src/workers/extractors): `apps/api/src/workers/extractors`
- [Text chunking](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/workers/chunking/text-chunker.ts): `apps/api/src/workers/chunking/text-chunker.ts`

### Search and AI

- [RAG endpoints](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/rag.controller.ts): `apps/api/src/controllers/rag.controller.ts`
- [RAG orchestration](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/rag.service.ts): `apps/api/src/services/rag.service.ts`
- [Semantic search](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/search.service.ts): `apps/api/src/services/search.service.ts`
- [Embedding service](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/embedding.service.ts): `apps/api/src/services/embedding.service.ts`
- [Answer generation](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/llm.service.ts): `apps/api/src/services/llm.service.ts`

### Teams and governance

- [Approval workflow](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/approval.service.ts): `apps/api/src/services/approval.service.ts`
- [Team and user management](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/controllers/users.controller.ts): `apps/api/src/controllers/users.controller.ts`
- [Analytics and audit](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/audit.service.ts): `apps/api/src/services/audit.service.ts`

### Persistence and integrations

- [PostgreSQL and pgvector](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/db/index.ts): `apps/api/src/db/index.ts`
- [Domain tables](https://github.com/hjariwala25/intellivault/tree/master/apps/api/src/db/schema): `apps/api/src/db/schema`
- [File storage](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/lib/uploadthing.ts): `apps/api/src/lib/uploadthing.ts`
- [Email notifications](https://github.com/hjariwala25/intellivault/blob/master/apps/api/src/services/email.service.ts): `apps/api/src/services/email.service.ts`
- **Google Gemini**
- **Resend**
- [Shared types and validators](https://github.com/hjariwala25/intellivault/tree/master/packages/shared/src): `packages/shared/src`

### Other components

- **Employee or admin**

## Connections

- Employee or admin → Knowledge UI: uses (evidence: `README.md`)
- Knowledge UI → API client hooks: requests data
- Document workspace → API client hooks: requests document APIs
- Chat interface → API client hooks: requests RAG APIs
- Search interface → API client hooks: requests search APIs
- Admin console → API client hooks: requests admin APIs
- API client hooks → Hono API: REST / JSON (evidence: `README.md`)
- Hono API → Authentication: authenticates
- Hono API → Document handling: routes requests (evidence: `apps/api/src/app.ts`)
- Document handling → Document service: calls (evidence: `apps/api/src/controllers/documents.controller.ts`)
- Document handling → Document processor: starts processing (evidence: `apps/api/src/controllers/documents.controller.ts`)
- Document handling → File storage: uses file storage (evidence: `apps/api/src/controllers/documents.controller.ts`)
- Document processor → Text extraction: extracts text (evidence: `apps/api/src/workers/document-processor.ts`)
- Document processor → Text chunking: chunks text (evidence: `apps/api/src/workers/document-processor.ts`)
- Document processor → Embedding service: generates vectors (evidence: `apps/api/src/workers/document-processor.ts`)
- Document handling → Analytics and audit: records actions (evidence: `apps/api/src/controllers/documents.controller.ts`)
- Document workspace → Approval workflow: review workflow (evidence: `README.md`)
- Approval workflow → Email notifications: sends notifications (evidence: `README.md`)
- Email notifications → Resend: delivers email (evidence: `README.md`)
- Admin console → Analytics and audit: views metrics and audit (evidence: `README.md`)
- Admin console → Team and user management: manages users and teams (evidence: `README.md`)
- RAG endpoints → RAG orchestration: calls (evidence: `apps/api/src/controllers/rag.controller.ts`)
- RAG orchestration → Semantic search: retrieves context (evidence: `apps/api/src/services/rag.service.ts`)
- RAG orchestration → Answer generation: generates answer (evidence: `apps/api/src/services/rag.service.ts`)
- Semantic search → Embedding service: embeds query (evidence: `apps/api/src/services/search.service.ts`)
- Embedding service → Google Gemini: requests embeddings (evidence: `apps/api/src/services/embedding.service.ts`)
- Answer generation → Google Gemini: generates response (evidence: `apps/api/src/services/llm.service.ts`)
- RAG endpoints → Chat interface: returns cited answers (evidence: `README.md`)
- Semantic search → Search interface: serves semantic results (evidence: `README.md`)
- Document service → PostgreSQL and pgvector: reads and writes (evidence: `apps/api/src/services/document.service.ts`)
- Document service → Domain tables: queries tables (evidence: `apps/api/src/services/document.service.ts`)
- Embedding service → PostgreSQL and pgvector: stores vectors (evidence: `apps/api/src/services/embedding.service.ts`)
- RAG orchestration → PostgreSQL and pgvector: stores conversations (evidence: `apps/api/src/services/rag.service.ts`)
- PostgreSQL and pgvector → Domain tables: uses schema (evidence: `apps/api/src/db/index.ts`)
- Authentication → Analytics and audit: records auth events (evidence: `apps/api/src/services/auth.service.ts`)
- Team and user management → Analytics and audit: records actions (evidence: `apps/api/src/controllers/users.controller.ts`)
- API client hooks → Shared types and validators: uses shared contracts
- RAG endpoints → Shared types and validators: uses shared types (evidence: `apps/api/src/controllers/rag.controller.ts`)
