# himavarshithreddy/knowhere architecture

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

- Interactive diagram: https://gitdiagram.com/himavarshithreddy/knowhere
- Repository: https://github.com/himavarshithreddy/knowhere

## Overview

1. **Monorepo shape**
   - This repo is split into three main codebases: `web/` for the client UI, `server/` for the API and background logic, and `shared/` for types/schemas reused across both.
   - The architecture is a classic client/server SaaS with a small shared contract layer, not a microservices setup.

2. **Frontend: single-page app**
   - `web/` is a React + Vite application with route-based pages like `Enter`, `Dashboard`, `Library`, `Missions`, `Settings`, and `Recover`.
   - The UI is state-heavy and productized: contexts (`AuthContext`, `DataContext`, `ThemeContext`, `ToastContext`) provide global app state, while components are organized by workspace features and a separate landing experience.
   - `web/src/lib/api.ts` is the main boundary to the backend; `web/src/lib/firebase.ts` indicates Firebase is also used directly on the client for auth-related flows.

3. **Backend: Express API**
   - `server/` is a Node.js/TypeScript Express service that exposes the application’s core API surface through route modules.
   - Route boundaries are explicit: `auth`, `account`, `me`, `resources`, `files`, `metadata`, `categories`, `interests`, `stats`, `vault`, `push`, `rediscovery`, `export`, and `coordsAuth`.
   - `server/src/index.ts` is the entry point, with `config.ts`, `db.ts`, and `firebase.ts` wiring environment, database, and Firebase integration.

4. **Identity and access model**
   - The README’s “Coords” concept maps to a custom identity layer in `coordsAuth` plus `auth` middleware.
   - Firebase is not the primary day-to-day identity provider; it appears to be used for passwordless recovery and Google SSO, while the app’s own authentication gates the main API.
   - This creates a split auth boundary: client-side Firebase support for recovery/login, server-side auth middleware for enforcing access to the user’s vault.

5. **Primary data model**
   - The system centers on user-owned content stored as “resources” in a vault, with supporting concepts like categories, interests, intents, metadata, and event logs.
   - `server/src/models/EventLog.ts` suggests activity/audit tracking is part of the data model, likely feeding stats and intelligence features.
   - The main persisted subsystem is MongoDB-backed, with the server acting as the authoritative business-logic layer.

6. **Content ingestion and storage**
   - `resources`, `files`, `metadata`, and `export` form the content lifecycle boundary.
   - Files are handled separately from metadata, and the README indicates Firebase Storage is used for file persistence, with the server proxying access securely.
   - The storage architecture therefore splits “blob storage” from “application metadata,” which is important for diagrams: uploads and retrievals are not the same path as CRUD on saved links/notes.

7. **Intelligence and enrichment**
   - The `services/` folder contains most of the product’s differentiating logic: classifier, metadata extraction, browser-based enrichment, AI helpers, and interest/rediscovery logic.
   - `utils/ai.ts` and `services/classifier.ts` indicate an external AI dependency, described in the README as Gemini, used for tagging, grouping, and analysis.
   - This layer sits between raw user input and the curated UI experience, turning incoming resources into structured knowledge objects.

8. **Rediscovery and intent-based surfacing**
   - `interests`, `rediscovery`, and `coordsSuggestions` imply a recommendation/surfacing subsystem that watches patterns and proposes relevant saved items.
   - The README’s “just-in-time surfacing” maps to this backend logic plus the corresponding UI cards and panels on the dashboard.
   - Architecturally, this is a secondary read model: it does not own content, but continuously derives relevance from user behavior and stored metadata.

9. **Missions, analytics, and engagement**
   - `missions`, `analytics`, `stats`, and `push` represent the product’s “behavior change” layer.
   - The app tracks completion/progression signals and uses them to drive reminders, dashboard summaries, and weekly recap experiences on the client.
   - Push notification handling is backed by a dedicated cron/service path (`pushCron.ts`) and a browser/service-worker entry on the frontend (`web/src/sw.ts`).

10. **Background jobs and maintenance**
   - The backend includes explicit job modules: `aging`, `migrate-v2`, and `purgeTrash`, plus a migration script `migrateIntents.ts`.
   - These are operational subsystems that keep long-lived user data consistent, remove stale content, and evolve schemas/logic without putting that burden on request-time endpoints.
   - In an architecture diagram, these should be shown as scheduled/administrative flows feeding the same MongoDB-backed domain model.

11. **Security, throttling, and serialization**
   - `middleware/auth.ts` and `middleware/rateLimit.ts` guard the API boundary, while `utils/security.ts` and `utils/serialize.ts` handle cross-cutting concerns.
   - This indicates the server is responsible for request trust, data shaping, and safe exposure of internal models to the client.
   - The design keeps privileged logic on the backend and exposes only serialized, purpose-built responses to the web app.

12. **Shared contracts and deployment**
   - `shared/` provides the common TypeScript package used by both client and server, likely for Zod schemas and domain types.
   - GitHub Actions workflows (`deploy.yml`, `change-domain.yml`) indicate automated deployment and environment management.
   - For diagramming, the repo’s deployment boundary is: source monorepo → CI/CD → web build + API deployment, with external services for MongoDB, Firebase, and AI/push integrations.

Main entry points: [`server/src/services/storage.ts`](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/services/storage.ts) (Core services), [`web/src/App.tsx`](https://github.com/himavarshithreddy/knowhere/blob/main/web/src/App.tsx) (SPA shell), [`server/src/services/classifier.ts`](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/services/classifier.ts) (Intelligence), [`server/src/index.ts`](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/index.ts) (Server entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_external_db[("MongoDB<br/>data store")]
  node_external_firebase[("Firebase<br/>identity/storage")]
  node_external_ai(("AI service<br/>Gemini/API"))
  node_external_push(("Push platform<br/>notifications"))
  node_ci_cd["CI/CD<br/>GitHub Actions<br/>[deploy.yml]"]
end

subgraph group_web["Web app"]
  node_web_app["SPA shell<br/>React/Vite app<br/>[App.tsx]"]
  node_web_contexts["App state<br/>React contexts"]
  node_web_api["API client<br/>HTTP boundary<br/>[api.ts]"]
  node_web_firebase["Firebase client<br/>auth/recovery<br/>[firebase.ts]"]
  node_web_workspace["Workspace UI<br/>feature views<br/>[Dashboard.tsx]"]
  node_web_landing["Landing UI<br/>marketing shell"]
  node_web_push["Service worker<br/>push/runtime<br/>[sw.ts]"]
end

subgraph group_server["API server"]
  node_server_entry["Server entry<br/>Express bootstrap<br/>[index.ts]"]
  node_server_config["Wiring<br/>config/db/firebase<br/>[config.ts]"]
  node_server_auth["Access control<br/>middleware<br/>[auth.ts]"]
  node_server_routes["API routes<br/>REST surface<br/>[resources.ts]"]
  node_server_models[("Domain model<br/>Mongo models<br/>[EventLog.ts]")]
  node_server_services_core["Core services<br/>business logic<br/>[storage.ts]"]
  node_server_services_intel["Intelligence<br/>enrichment/AI<br/>[classifier.ts]"]
  node_server_jobs["Jobs<br/>scheduled tasks<br/>[aging.ts]"]
  node_server_scripts["Migrations<br/>admin scripts<br/>[migrateIntents.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_contracts["Shared types<br/>schemas/types<br/>[index.ts]"]
end

node_web_app -->|"uses"| node_web_contexts
node_web_app -->|"navigates"| node_web_workspace
node_web_app -->|"shows"| node_web_landing
node_web_app -->|"calls"| node_web_api
node_web_app -->|"auth flows"| node_web_firebase
node_web_push -->|"subscribes"| node_external_push
node_server_entry -->|"wires"| node_server_config
node_server_entry -->|"guards"| node_server_auth
node_server_entry -->|"registers"| node_server_routes
node_server_routes -->|"delegates"| node_server_services_core
node_server_routes -->|"delegates"| node_server_services_intel
node_server_services_core -->|"reads/writes"| node_server_models
node_server_services_core -->|"persists"| node_external_db
node_server_services_core -->|"uploads"| node_external_firebase
node_server_services_intel -->|"analyzes"| node_external_ai
node_server_services_intel -->|"derives"| node_server_models
node_server_services_intel -->|"reads"| node_external_db
node_server_jobs -.->|"maintains"| node_server_models
node_server_jobs -.->|"runs on"| node_external_db
node_server_scripts -.->|"migrates"| node_external_db
node_server_services_core -->|"serializes"| node_shared_contracts
node_web_api -->|"consumes"| node_shared_contracts
node_server_config -->|"integrates"| node_external_firebase
node_server_services_core -->|"feeds"| node_server_services_intel
node_ci_cd -->|"builds"| node_web_app
node_ci_cd -->|"deploys"| node_server_entry

click node_web_app "https://github.com/himavarshithreddy/knowhere/blob/main/web/src/App.tsx"
click node_web_contexts "https://github.com/himavarshithreddy/knowhere/tree/main/web/src/contexts"
click node_web_api "https://github.com/himavarshithreddy/knowhere/blob/main/web/src/lib/api.ts"
click node_web_firebase "https://github.com/himavarshithreddy/knowhere/blob/main/web/src/lib/firebase.ts"
click node_web_workspace "https://github.com/himavarshithreddy/knowhere/blob/main/web/src/pages/Dashboard.tsx"
click node_web_landing "https://github.com/himavarshithreddy/knowhere/tree/main/web/src/components/landing"
click node_web_push "https://github.com/himavarshithreddy/knowhere/blob/main/web/src/sw.ts"
click node_server_entry "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/index.ts"
click node_server_config "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/config.ts"
click node_server_auth "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/middleware/auth.ts"
click node_server_routes "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/routes/resources.ts"
click node_server_models "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/models/EventLog.ts"
click node_server_services_core "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/services/storage.ts"
click node_server_services_intel "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/services/classifier.ts"
click node_server_jobs "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/jobs/aging.ts"
click node_server_scripts "https://github.com/himavarshithreddy/knowhere/blob/main/server/src/scripts/migrateIntents.ts"
click node_shared_contracts "https://github.com/himavarshithreddy/knowhere/blob/main/shared/src/index.ts"
click node_ci_cd "https://github.com/himavarshithreddy/knowhere/blob/main/.github/workflows/deploy.yml"

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_external_db,node_external_firebase,node_external_ai,node_external_push,node_ci_cd toneBlue
class node_web_app,node_web_contexts,node_web_api,node_web_firebase,node_web_workspace,node_web_landing,node_web_push toneAmber
class node_server_entry,node_server_config,node_server_auth,node_server_routes,node_server_models,node_server_services_core,node_server_services_intel,node_server_jobs,node_server_scripts toneMint
class node_shared_contracts toneRose
```

## Components

### Monorepo

Top-level packages and deployment boundary

- **MongoDB**: data store · Authoritative application persistence
- **Firebase**: identity/storage · Recovery, sign-in, and file storage support
- **AI service**: Gemini/API · External model dependency for tagging and analysis
- **Push platform**: notifications · Browser push delivery infrastructure
- [CI/CD](https://github.com/himavarshithreddy/knowhere/blob/main/.github/workflows/deploy.yml): GitHub Actions · Build, deploy, and domain-change automation · `.github/workflows/deploy.yml`

### Web app

React/Vite client and UI state

- [SPA shell](https://github.com/himavarshithreddy/knowhere/blob/main/web/src/App.tsx): React/Vite app · Client entry, routing, and page composition · `web/src/App.tsx`
- [App state](https://github.com/himavarshithreddy/knowhere/tree/main/web/src/contexts): React contexts · Auth, data, theme, and toast state · `web/src/contexts`
- [API client](https://github.com/himavarshithreddy/knowhere/blob/main/web/src/lib/api.ts): HTTP boundary · Primary client bridge to the backend · `web/src/lib/api.ts`
- [Firebase client](https://github.com/himavarshithreddy/knowhere/blob/main/web/src/lib/firebase.ts): auth/recovery · Client-side Firebase integration for recovery and sign-in flows · `web/src/lib/firebase.ts`
- [Workspace UI](https://github.com/himavarshithreddy/knowhere/blob/main/web/src/pages/Dashboard.tsx): feature views · Dashboard, library, missions, settings, and resource screens · `web/src/pages/Dashboard.tsx`
- [Landing UI](https://github.com/himavarshithreddy/knowhere/tree/main/web/src/components/landing): marketing shell · Public-facing discovery and entry experience · `web/src/components/landing`
- [Service worker](https://github.com/himavarshithreddy/knowhere/blob/main/web/src/sw.ts): push/runtime · Browser background support for notifications and offline behavior · `web/src/sw.ts`

### API server

Express service, domain logic, and jobs

- [Server entry](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/index.ts): Express bootstrap · Process startup, app wiring, and route registration · `server/src/index.ts`
- [Wiring](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/config.ts): config/db/firebase · Environment, database, and Firebase setup · `server/src/config.ts`
- [Access control](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/middleware/auth.ts): middleware · Auth and rate limiting at the API boundary · `server/src/middleware/auth.ts`
- [API routes](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/routes/resources.ts): REST surface · Auth, account, vault, resources, files, stats, push, and related endpoints · `server/src/routes/resources.ts`
- [Domain model](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/models/EventLog.ts): Mongo models · Persistent user content and event log structures · `server/src/models/EventLog.ts`
- [Core services](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/services/storage.ts): business logic · Users, storage, metadata, analytics, and serialization helpers · `server/src/services/storage.ts`
- [Intelligence](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/services/classifier.ts): enrichment/AI · Classifier, browser enrichment, interests, suggestions, and rediscovery · `server/src/services/classifier.ts`
- [Jobs](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/jobs/aging.ts): scheduled tasks · Aging, migration, purge, and push cron maintenance · `server/src/jobs/aging.ts`
- [Migrations](https://github.com/himavarshithreddy/knowhere/blob/main/server/src/scripts/migrateIntents.ts): admin scripts · One-off schema and intent migration utilities · `server/src/scripts/migrateIntents.ts`

### Shared contracts

Types and schemas reused by client and server

- [Shared types](https://github.com/himavarshithreddy/knowhere/blob/main/shared/src/index.ts): schemas/types · Common contract layer used by client and server · `shared/src/index.ts`

## Connections

- SPA shell → App state: uses · App shell composes global state providers
- SPA shell → Workspace UI: navigates · Route-based product screens
- SPA shell → Landing UI: shows · Public entry experience
- SPA shell → API client: calls · Primary backend access
- SPA shell → Firebase client: auth flows · Recovery and sign-in support
- Service worker → Push platform: subscribes · Browser notification runtime
- Server entry → Wiring: wires · Bootstraps environment, DB, and Firebase
- Server entry → Access control: guards · Applies request trust and limits
- Server entry → API routes: registers · Mounts feature endpoints
- API routes → Core services: delegates · Routes invoke domain services
- API routes → Intelligence: delegates · Routes expose enrichment and recommendation logic
- Core services → Domain model: reads/writes · Business logic persists domain state
- Core services → MongoDB: persists · Mongo-backed storage
- Core services → Firebase: uploads · File storage integration
- Intelligence → AI service: analyzes · Classifier and metadata inference
- Intelligence → Domain model: derives · Builds secondary read models from content and events
- Intelligence → MongoDB: reads · Uses stored resources and logs for surfacing
- Jobs → Domain model: maintains · Scheduled cleanup and evolution of domain data
- Jobs → MongoDB: runs on · Background maintenance against MongoDB
- Migrations → MongoDB: migrates · One-off data/schema updates
- Core services → Shared types: serializes · Backend responses follow shared contracts
- API client → Shared types: consumes · Client uses shared types and schemas
- Wiring → Firebase: integrates · Server-side Firebase support for auth and storage
- Core services → Intelligence: feeds · Content lifecycle produces enrichment inputs
- CI/CD → SPA shell: builds · Deploys client application
- CI/CD → Server entry: deploys · Deploys API service