# datle04/know-vault architecture

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

- Interactive diagram: https://gitdiagram.com/datle04/know-vault
- Repository: https://github.com/datle04/know-vault

## Overview

KnowVault turns saved technical articles into reviewable knowledge: users save from the browser extension or web app, the API stores and processes articles, and users revisit generated questions and concept connections. The README documents the processing stages; sampled source confirms extension save messaging, authentication, embedding persistence, and the review flow. Other processing, search, and concept features are represented only where supported by the README and tree; their internal wiring was not sampled.

Main entry points: [`apps/api/src/modules/ai/providers/ai.module.ts`](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/providers/ai.module.ts) (AI providers), [`apps/web/src/app`](https://github.com/datle04/know-vault/tree/main/apps/web/src/app) (Web dashboard), [`apps/api/src/modules/articles/article-processor.service.ts`](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/article-processor.service.ts) (Article processor), [`apps/api/src/modules/reviews/reviews.service.ts`](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/reviews.service.ts) (Review workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web dashboard"]
  node_extension["Extension popup<br/>[App.tsx]"]
  node_worker["Extension worker<br/>[service-worker.ts]"]
  node_content["Page extraction<br/>[content-script.ts]"]
end

subgraph group_api["API workflows"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_article_api["Article endpoints"]
  node_extension_api["Quick-save endpoints"]
  node_article_service["Article workflow"]
  node_concepts["Concept connections"]
  node_review_api["Review endpoints"]
  node_review_service["Review workflow<br/>[reviews.service.ts]"]
end

subgraph group_knowledge["Knowledge processing"]
  node_processor["Article processor"]
  node_extraction["Content and concepts"]
  node_questions["Question generation"]
  node_embeddings["Concept embeddings"]
  node_search["Semantic search"]
  node_evaluation["Answer evaluation"]
  node_ai["AI providers<br/>[ai.module.ts]"]
end

subgraph group_domain["Domain and persistence"]
  node_sm2["SM-2 scheduling<br/>[sm2.service.ts]"]
  node_repositories["Prisma repositories"]
  node_database[("PostgreSQL<br/>[prisma.service.ts]")]
  node_ai_log[("AI usage log")]
end

node_user(("Learner"))
node_ai_service(("AI services"))

node_user -->|"uses"| node_web
node_user -->|"saves and reviews"| node_extension
node_extension -->|"logs in"| node_auth
node_extension -->|"sends messages"| node_worker
node_worker -->|"extracts page"| node_content
node_worker -->|"checks and saves"| node_extension_api
node_web -->|"authenticates"| node_auth
node_web -->|"manages articles"| node_article_api
node_web -->|"reviews knowledge"| node_review_api
node_web -->|"explores concepts"| node_concepts
node_article_api -->|"dispatches"| node_article_service
node_extension_api -->|"dispatches"| node_article_service
node_article_service -->|"stores article"| node_repositories
node_article_service -->|"starts processing"| node_processor
node_processor -->|"extracts concepts"| node_extraction
node_processor -->|"generates questions"| node_questions
node_processor -->|"embeds concepts"| node_embeddings
node_processor -->|"requests generation"| node_ai
node_extraction -->|"requests extraction"| node_ai
node_questions -->|"requests generation"| node_ai
node_embeddings -->|"requests vectors"| node_ai
node_embeddings -->|"writes vectors"| node_database
node_embeddings -->|"records usage"| node_ai_log
node_concepts -->|"reads and writes"| node_repositories
node_search -.->|"searches content"| node_database
node_review_api -->|"dispatches"| node_review_service
node_review_service -->|"loads and saves reviews"| node_repositories
node_review_service -->|"evaluates answers"| node_evaluation
node_review_service -->|"records attempt"| node_sm2
node_evaluation -->|"requests grading"| node_ai
node_ai -->|"calls providers"| node_ai_service
node_repositories -->|"reads and writes"| node_database

click node_web "https://github.com/datle04/know-vault/tree/main/apps/web/src/app"
click node_extension "https://github.com/datle04/know-vault/blob/main/apps/extension/src/popup/App.tsx"
click node_worker "https://github.com/datle04/know-vault/blob/main/apps/extension/src/background/service-worker.ts"
click node_content "https://github.com/datle04/know-vault/blob/main/apps/extension/src/content/content-script.ts"
click node_auth "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_article_api "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/articles.controller.ts"
click node_extension_api "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/extension/extension.controller.ts"
click node_article_service "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/articles.service.ts"
click node_processor "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/article-processor.service.ts"
click node_extraction "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/prompt-templates/extract-concept.v1.ts"
click node_questions "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/prompt-templates/generate-questions.v1.ts"
click node_embeddings "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/concepts/concept-embedding.service.ts"
click node_concepts "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/concepts/concepts.service.ts"
click node_search "https://github.com/datle04/know-vault/tree/main/apps/api/src/modules/concepts"
click node_review_api "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/reviews.controller.ts"
click node_review_service "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/reviews.service.ts"
click node_evaluation "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/answer-evaluation.service.ts"
click node_sm2 "https://github.com/datle04/know-vault/blob/main/apps/api/src/domain/review/sm2.service.ts"
click node_ai "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/providers/ai.module.ts"
click node_repositories "https://github.com/datle04/know-vault/tree/main/apps/api/src/infrastructure/persistence"
click node_database "https://github.com/datle04/know-vault/blob/main/apps/api/src/infrastructure/persistence/prisma.service.ts"
click node_ai_log "https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/concepts/concept-embedding.service.ts"

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_web,node_extension,node_worker,node_content toneBlue
class node_auth,node_article_api,node_extension_api,node_article_service,node_concepts,node_review_api,node_review_service toneAmber
class node_processor,node_extraction,node_questions,node_embeddings,node_search,node_evaluation,node_ai toneMint
class node_sm2,node_repositories,node_database,node_ai_log toneRose
class node_user,node_ai_service toneIndigo
```

## Components

### User clients

- [Web dashboard](https://github.com/datle04/know-vault/tree/main/apps/web/src/app): `apps/web/src/app`
- [Extension popup](https://github.com/datle04/know-vault/blob/main/apps/extension/src/popup/App.tsx): `apps/extension/src/popup/App.tsx`
- [Extension worker](https://github.com/datle04/know-vault/blob/main/apps/extension/src/background/service-worker.ts): `apps/extension/src/background/service-worker.ts`
- [Page extraction](https://github.com/datle04/know-vault/blob/main/apps/extension/src/content/content-script.ts): `apps/extension/src/content/content-script.ts`

### API workflows

- [Authentication](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Article endpoints](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/articles.controller.ts): `apps/api/src/modules/articles/articles.controller.ts`
- [Quick-save endpoints](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/extension/extension.controller.ts): `apps/api/src/modules/extension/extension.controller.ts`
- [Article workflow](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/articles.service.ts): `apps/api/src/modules/articles/articles.service.ts`
- [Concept connections](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/concepts/concepts.service.ts): `apps/api/src/modules/concepts/concepts.service.ts`
- [Review endpoints](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/reviews.controller.ts): `apps/api/src/modules/reviews/reviews.controller.ts`
- [Review workflow](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/reviews.service.ts): `apps/api/src/modules/reviews/reviews.service.ts`

### Knowledge processing

- [Article processor](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/articles/article-processor.service.ts): `apps/api/src/modules/articles/article-processor.service.ts`
- [Content and concepts](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/prompt-templates/extract-concept.v1.ts): `apps/api/src/modules/ai/prompt-templates/extract-concept.v1.ts`
- [Question generation](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/prompt-templates/generate-questions.v1.ts): `apps/api/src/modules/ai/prompt-templates/generate-questions.v1.ts`
- [Concept embeddings](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/concepts/concept-embedding.service.ts): `apps/api/src/modules/concepts/concept-embedding.service.ts`
- [Semantic search](https://github.com/datle04/know-vault/tree/main/apps/api/src/modules/concepts): `apps/api/src/modules/concepts`
- [Answer evaluation](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/reviews/answer-evaluation.service.ts): `apps/api/src/modules/reviews/answer-evaluation.service.ts`
- [AI providers](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/ai/providers/ai.module.ts): `apps/api/src/modules/ai/providers/ai.module.ts`

### Domain and persistence

- [SM-2 scheduling](https://github.com/datle04/know-vault/blob/main/apps/api/src/domain/review/sm2.service.ts): `apps/api/src/domain/review/sm2.service.ts`
- [Prisma repositories](https://github.com/datle04/know-vault/tree/main/apps/api/src/infrastructure/persistence): `apps/api/src/infrastructure/persistence`
- [PostgreSQL](https://github.com/datle04/know-vault/blob/main/apps/api/src/infrastructure/persistence/prisma.service.ts): `apps/api/src/infrastructure/persistence/prisma.service.ts`
- [AI usage log](https://github.com/datle04/know-vault/blob/main/apps/api/src/modules/concepts/concept-embedding.service.ts): `apps/api/src/modules/concepts/concept-embedding.service.ts`

### Other components

- **Learner**
- **AI services**

## Connections

- Learner → Web dashboard: uses
- Learner → Extension popup: saves and reviews
- Extension popup → Authentication: logs in
- Extension popup → Extension worker: sends messages
- Extension worker → Page extraction: extracts page
- Extension worker → Quick-save endpoints: checks and saves
- Web dashboard → Authentication: authenticates
- Web dashboard → Article endpoints: manages articles
- Web dashboard → Review endpoints: reviews knowledge
- Web dashboard → Concept connections: explores concepts
- Article endpoints → Article workflow: dispatches
- Quick-save endpoints → Article workflow: dispatches
- Article workflow → Prisma repositories: stores article
- Article workflow → Article processor: starts processing
- Article processor → Content and concepts: extracts concepts
- Article processor → Question generation: generates questions
- Article processor → Concept embeddings: embeds concepts
- Article processor → AI providers: requests generation
- Content and concepts → AI providers: requests extraction
- Question generation → AI providers: requests generation
- Concept embeddings → AI providers: requests vectors
- Concept embeddings → PostgreSQL: writes vectors
- Concept embeddings → AI usage log: records usage
- Concept connections → Prisma repositories: reads and writes
- Semantic search → PostgreSQL: searches content
- Review endpoints → Review workflow: dispatches
- Review workflow → Prisma repositories: loads and saves reviews
- Review workflow → Answer evaluation: evaluates answers
- Review workflow → SM-2 scheduling: records attempt
- Answer evaluation → AI providers: requests grading
- AI providers → AI services: calls providers
- Prisma repositories → PostgreSQL: reads and writes