# carolenache/frontend-node-evolution-dashboard architecture

> Architecture diagram of the GitHub repository carolenache/frontend-node-evolution-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carolenache/frontend-node-evolution-dashboard
- Repository: https://github.com/carolenache/frontend-node-evolution-dashboard

## Overview

Evolution is a local frontend-platform and Node.js change dashboard. Its main workflow is scheduled source polling, source-specific change extraction, normalization and deduplication, optional local AI enrichment, persistence, then filtered timeline and worth-learning views. The graph includes documented capabilities such as conditional fetches, source coverage, cache revalidation, and the optional summary integrations. Some subsystem links rely on the README because their implementation files were not sampled.

Main entry points: [`apps/worker/src/run.ts`](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/worker/src/run.ts) (Ingest runner), [`packages/ai/src/enrich.ts`](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ai/src/enrich.ts) (AI enrichment), [`packages/ingest/src/sources`](https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ingest/src/sources) (Source adapters), [`apps/web/src/components/dashboard.tsx`](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/components/dashboard.tsx) (Dashboard views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Change collection"]
  node_scheduler["Ingest scheduler<br/>[schedule.ts]"]
  node_worker["Ingest runner<br/>[run.ts]"]
  node_sources["Source adapters"]
  node_fetch["Conditional fetch"]
end

subgraph group_processing["Entry processing"]
  node_normalize["Entry normalization<br/>[normalise.ts]"]
  node_dedupe["Entry deduplication<br/>[dedupe.ts]"]
end

subgraph group_storage["Persistence"]
  node_database[("Entry and source-state store")]
end

subgraph group_dashboard["Dashboard"]
  node_timeline["Timeline page<br/>[page.tsx]"]
  node_worth_page["Worth-learning page<br/>[page.tsx]"]
  node_dashboard_view["Dashboard views<br/>[dashboard.tsx]"]
  node_filters["Filter parsing<br/>[filters.ts]"]
  node_entries_api["Entries JSON API<br/>[route.ts]"]
  node_revalidation["Cache revalidation route<br/>[route.ts]"]
end

subgraph group_intelligence["Learning signals"]
  node_enrichment["AI enrichment<br/>[enrich.ts]"]
  node_embeddings["Embeddings and similarity"]
  node_classification["Gap classification<br/>[classify.ts]"]
  node_summaries["Summary providers"]
  node_worth_strategy["Worth-learning strategy<br/>[worth-learning.ts]"]
end

node_source_services(("Public source feeds"))
node_profile["Skills profile<br/>[skills.json]"]
node_user(("Dashboard user"))
node_webhook(("Web revalidation endpoint"))

node_scheduler -->|"runs ingest"| node_worker
node_worker -->|"dispatches sources"| node_sources
node_sources -->|"fetches conditionally"| node_fetch
node_source_services -->|"provides updates"| node_sources
node_sources -->|"normalizes drafts"| node_normalize
node_sources -->|"deduplicates entries"| node_dedupe
node_worker -->|"stores entries and state"| node_database
node_worker -.->|"enriches optionally"| node_enrichment
node_enrichment -->|"embeds and compares"| node_embeddings
node_enrichment -->|"classifies gaps"| node_classification
node_enrichment -->|"generates summaries"| node_summaries
node_enrichment -->|"compares skills"| node_profile
node_worker -->|"posts revalidation"| node_webhook
node_webhook -->|"calls route"| node_revalidation
node_timeline -->|"renders timeline"| node_dashboard_view
node_worth_page -->|"renders recommendations"| node_dashboard_view
node_dashboard_view -->|"reads entries"| node_database
node_dashboard_view -->|"selects worth learning"| node_worth_strategy
node_user -->|"opens view"| node_timeline
node_user -->|"opens view"| node_worth_page
node_user -->|"requests filtered data"| node_entries_api
node_entries_api -->|"parses query"| node_filters
node_entries_api -->|"queries entries"| node_database
node_user -->|"sets filters"| node_dashboard_view
node_worker -->|"reads source state"| node_database

click node_scheduler "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/worker/src/schedule.ts"
click node_worker "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/worker/src/run.ts"
click node_sources "https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ingest/src/sources"
click node_fetch "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ingest/src/fetch-if-changed.ts"
click node_normalize "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ingest/src/normalise.ts"
click node_dedupe "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ingest/src/dedupe.ts"
click node_enrichment "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ai/src/enrich.ts"
click node_embeddings "https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ai/src"
click node_classification "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ai/src/classify.ts"
click node_summaries "https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ai/src"
click node_profile "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/profile/skills.json"
click node_worth_strategy "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/shared-types/src/worth-learning.ts"
click node_database "https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/db/src"
click node_timeline "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/page.tsx"
click node_worth_page "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/worth-learning/page.tsx"
click node_dashboard_view "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/components/dashboard.tsx"
click node_filters "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/lib/filters.ts"
click node_entries_api "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/api/entries/route.ts"
click node_revalidation "https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/api/revalidate/route.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_scheduler,node_worker,node_sources,node_fetch,node_user toneBlue
class node_normalize,node_dedupe toneAmber
class node_database toneMint
class node_timeline,node_worth_page,node_dashboard_view,node_filters,node_entries_api,node_revalidation toneRose
class node_enrichment,node_embeddings,node_classification,node_summaries,node_worth_strategy,node_source_services,node_webhook toneIndigo
class node_profile toneTeal
```

## Components

### Change collection

- [Ingest scheduler](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/worker/src/schedule.ts): `apps/worker/src/schedule.ts`
- [Ingest runner](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/worker/src/run.ts): `apps/worker/src/run.ts`
- [Source adapters](https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ingest/src/sources): `packages/ingest/src/sources`
- [Conditional fetch](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ingest/src/fetch-if-changed.ts): `packages/ingest/src/fetch-if-changed.ts`

### Entry processing

- [Entry normalization](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ingest/src/normalise.ts): `packages/ingest/src/normalise.ts`
- [Entry deduplication](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ingest/src/dedupe.ts): `packages/ingest/src/dedupe.ts`

### Persistence

- [Entry and source-state store](https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/db/src): `packages/db/src`

### Dashboard

- [Timeline page](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Worth-learning page](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/worth-learning/page.tsx): `apps/web/src/app/worth-learning/page.tsx`
- [Dashboard views](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/components/dashboard.tsx): `apps/web/src/components/dashboard.tsx`
- [Filter parsing](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/lib/filters.ts): `apps/web/src/lib/filters.ts`
- [Entries JSON API](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/api/entries/route.ts): `apps/web/src/app/api/entries/route.ts`
- [Cache revalidation route](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/apps/web/src/app/api/revalidate/route.ts): `apps/web/src/app/api/revalidate/route.ts`

### Learning signals

- [AI enrichment](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ai/src/enrich.ts): `packages/ai/src/enrich.ts`
- [Embeddings and similarity](https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ai/src): `packages/ai/src`
- [Gap classification](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/ai/src/classify.ts): `packages/ai/src/classify.ts`
- [Summary providers](https://github.com/carolenache/frontend-node-evolution-dashboard/tree/main/packages/ai/src): `packages/ai/src`
- [Worth-learning strategy](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/packages/shared-types/src/worth-learning.ts): `packages/shared-types/src/worth-learning.ts`

### Other components

- **Public source feeds**
- [Skills profile](https://github.com/carolenache/frontend-node-evolution-dashboard/blob/main/profile/skills.json): `profile/skills.json`
- **Dashboard user**
- **Web revalidation endpoint**

## Connections

- Ingest scheduler → Ingest runner: runs ingest
- Ingest runner → Source adapters: dispatches sources
- Source adapters → Conditional fetch: fetches conditionally (evidence: `packages/ingest/src/sources/mdn-bcd.ts`)
- Public source feeds → Source adapters: provides updates
- Source adapters → Entry normalization: normalizes drafts (evidence: `packages/ingest/src/sources/mdn-bcd.ts`)
- Source adapters → Entry deduplication: deduplicates entries (evidence: `packages/ingest/src/sources/mdn-bcd.ts`)
- Ingest runner → Entry and source-state store: stores entries and state
- Ingest runner → AI enrichment: enriches optionally
- AI enrichment → Embeddings and similarity: embeds and compares (evidence: `packages/ai/src/enrich.ts`)
- AI enrichment → Gap classification: classifies gaps (evidence: `packages/ai/src/enrich.ts`)
- AI enrichment → Summary providers: generates summaries (evidence: `packages/ai/src/enrich.ts`)
- AI enrichment → Skills profile: compares skills
- Ingest runner → Web revalidation endpoint: posts revalidation
- Web revalidation endpoint → Cache revalidation route: calls route
- Timeline page → Dashboard views: renders timeline
- Worth-learning page → Dashboard views: renders recommendations
- Dashboard views → Entry and source-state store: reads entries
- Dashboard views → Worth-learning strategy: selects worth learning
- Dashboard user → Timeline page: opens view
- Dashboard user → Worth-learning page: opens view
- Dashboard user → Entries JSON API: requests filtered data
- Entries JSON API → Filter parsing: parses query (evidence: `apps/web/src/app/api/entries/route.ts`)
- Entries JSON API → Entry and source-state store: queries entries (evidence: `apps/web/src/app/api/entries/route.ts`)
- Dashboard user → Dashboard views: sets filters
- Ingest runner → Entry and source-state store: reads source state
