himavarshithreddy/knowhere

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.