# kadhiravan-k/learnup architecture

> Architecture diagram of the GitHub repository kadhiravan-k/learnup, 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/kadhiravan-k/learnup
- Repository: https://github.com/kadhiravan-k/learnup

## Overview

LearnUp is a personal learning platform: users authenticate, import YouTube videos or playlists into a private library, and study them with ordered playback. Its broader product includes calendar planning, focus sessions, notes, roadmaps, analytics, AI assistance, rewards, skills, and connector sync. The map combines documented capabilities with sampled import, authentication, focus, calendar, and MCP code; several feature paths are present in the tree but their implementation details were not sampled.

Main entry points: [`app/api/mcp/route.ts`](https://github.com/kadhiravan-k/learnup/blob/main/app/api/mcp/route.ts) (MCP interface), [`lib/services/import-service.ts`](https://github.com/kadhiravan-k/learnup/blob/main/lib/services/import-service.ts) (YouTube import), [`app/api/learning-items/route.ts`](https://github.com/kadhiravan-k/learnup/blob/main/app/api/learning-items/route.ts) (Import endpoint), [`lib/db/repository.ts`](https://github.com/kadhiravan-k/learnup/blob/main/lib/db/repository.ts) (Learning item repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; app shell"]
  node_auth_pages["Login and signup<br/>[page.tsx]"]
  node_auth_service["Session authentication<br/>[index.ts]"]
  node_app_shell["Protected app shell<br/>[layout.tsx]"]
end

subgraph group_learning["Library &amp; playback"]
  node_library_page["Personal library<br/>[page.tsx]"]
  node_import_api["Import endpoint<br/>[route.ts]"]
  node_import_service["YouTube import<br/>[import-service.ts]"]
  node_youtube["YouTube metadata<br/>[client.ts]"]
  node_library_service["Library operations<br/>[library-service.ts]"]
  node_player["Playlist player<br/>[YouTubePlayer.tsx]"]
end

subgraph group_study["Study workflows"]
  node_calendar["Calendar planning<br/>[page.tsx]"]
  node_calendar_service["Calendar logic"]
  node_focus["Focus sessions<br/>[page.tsx]"]
  node_focus_widget["Focus timer widget"]
  node_focus_hook["Focus timer state<br/>[useFocusTimer.ts]"]
  node_notes["Notes<br/>[page.tsx]"]
end

subgraph group_insights["Insights &amp; planning"]
  node_roadmaps["Learning roadmaps<br/>[page.tsx]"]
  node_analytics["Learning analytics<br/>[page.tsx]"]
  node_assistant["AI assistant<br/>[page.tsx]"]
  node_rewards["Rewards<br/>[page.tsx]"]
  node_skills["Skills<br/>[page.tsx]"]
end

subgraph group_platform["Data &amp; integrations"]
  node_learning_store["Learning item repository<br/>[repository.ts]"]
  node_calendar_store["Calendar repository"]
  node_notes_store["Notes repository"]
  node_mcp["MCP interface<br/>[route.ts]"]
  node_connectors["Connector dispatch<br/>[index.ts]"]
  node_postgres[("Supabase PostgreSQL")]
end

node_learner(("Learner"))
node_youtube_service["YouTube Data API"]

node_learner -->|"signs in"| node_auth_pages
node_auth_pages -.->|"authenticates"| node_auth_service
node_learner -.->|"uses"| node_app_shell
node_import_api -->|"requires auth"| node_auth_service
node_import_api -->|"imports URL"| node_import_service
node_import_service -->|"fetches metadata"| node_youtube
node_youtube -->|"requests metadata"| node_youtube_service
node_import_service -->|"saves items"| node_learning_store
node_library_page -.->|"imports items"| node_import_api
node_library_page -->|"opens playback"| node_player
node_player -->|"embeds video"| node_youtube_service
node_calendar -->|"uses calendar logic"| node_calendar_service
node_calendar_service -.->|"persists calendar data"| node_calendar_store
node_focus_widget -->|"reads timer state"| node_focus_hook
node_focus -.->|"uses timer"| node_focus_hook
node_mcp -->|"requires auth"| node_auth_service
node_mcp -->|"reads courses"| node_learning_store
node_mcp -->|"reads notes"| node_notes_store
node_mcp -->|"dispatches sync"| node_connectors
node_connectors -.->|"syncs study data"| node_learner
node_learning_store -.->|"reads and writes"| node_postgres
node_calendar_store -.->|"reads and writes"| node_postgres
node_notes_store -.->|"reads and writes"| node_postgres

click node_auth_pages "https://github.com/kadhiravan-k/learnup/blob/main/app/(auth)/login/page.tsx"
click node_auth_service "https://github.com/kadhiravan-k/learnup/blob/main/lib/auth/index.ts"
click node_app_shell "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/layout.tsx"
click node_library_page "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/library/page.tsx"
click node_import_api "https://github.com/kadhiravan-k/learnup/blob/main/app/api/learning-items/route.ts"
click node_import_service "https://github.com/kadhiravan-k/learnup/blob/main/lib/services/import-service.ts"
click node_youtube "https://github.com/kadhiravan-k/learnup/blob/main/lib/youtube/client.ts"
click node_library_service "https://github.com/kadhiravan-k/learnup/blob/main/lib/services/library-service.ts"
click node_learning_store "https://github.com/kadhiravan-k/learnup/blob/main/lib/db/repository.ts"
click node_player "https://github.com/kadhiravan-k/learnup/blob/main/components/player/YouTubePlayer.tsx"
click node_calendar "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/calendar/page.tsx"
click node_calendar_service "https://github.com/kadhiravan-k/learnup/blob/main/lib/services/calendar-service.ts"
click node_calendar_store "https://github.com/kadhiravan-k/learnup/blob/main/lib/db/calendar-repository.ts"
click node_focus "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/focus/page.tsx"
click node_focus_widget "https://github.com/kadhiravan-k/learnup/blob/main/components/dashboard/FocusEngineWidget.tsx"
click node_focus_hook "https://github.com/kadhiravan-k/learnup/blob/main/lib/hooks/useFocusTimer.ts"
click node_notes "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/notes/page.tsx"
click node_notes_store "https://github.com/kadhiravan-k/learnup/blob/main/lib/db/notes-repository.ts"
click node_roadmaps "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/roadmaps/page.tsx"
click node_analytics "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/analytics/page.tsx"
click node_assistant "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/assistant/page.tsx"
click node_rewards "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/rewards/page.tsx"
click node_skills "https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/skills/page.tsx"
click node_mcp "https://github.com/kadhiravan-k/learnup/blob/main/app/api/mcp/route.ts"
click node_connectors "https://github.com/kadhiravan-k/learnup/blob/main/lib/connectors/index.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_auth_pages,node_auth_service,node_app_shell toneBlue
class node_library_page,node_import_api,node_import_service,node_youtube,node_library_service,node_player toneAmber
class node_calendar,node_calendar_service,node_focus,node_focus_widget,node_focus_hook,node_notes,node_youtube_service toneMint
class node_roadmaps,node_analytics,node_assistant,node_rewards,node_skills toneRose
class node_learning_store,node_calendar_store,node_notes_store,node_mcp,node_connectors,node_postgres,node_learner toneIndigo
```

## Components

### Identity & app shell

- [Login and signup](https://github.com/kadhiravan-k/learnup/blob/main/app/(auth)/login/page.tsx): `app/(auth)/login/page.tsx`
- [Session authentication](https://github.com/kadhiravan-k/learnup/blob/main/lib/auth/index.ts): `lib/auth/index.ts`
- [Protected app shell](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/layout.tsx): `app/(app)/layout.tsx`

### Library & playback

- [Personal library](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/library/page.tsx): `app/(app)/library/page.tsx`
- [Import endpoint](https://github.com/kadhiravan-k/learnup/blob/main/app/api/learning-items/route.ts): `app/api/learning-items/route.ts`
- [YouTube import](https://github.com/kadhiravan-k/learnup/blob/main/lib/services/import-service.ts): `lib/services/import-service.ts`
- [YouTube metadata](https://github.com/kadhiravan-k/learnup/blob/main/lib/youtube/client.ts): `lib/youtube/client.ts`
- [Library operations](https://github.com/kadhiravan-k/learnup/blob/main/lib/services/library-service.ts): `lib/services/library-service.ts`
- [Playlist player](https://github.com/kadhiravan-k/learnup/blob/main/components/player/YouTubePlayer.tsx): `components/player/YouTubePlayer.tsx`

### Study workflows

- [Calendar planning](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/calendar/page.tsx): `app/(app)/calendar/page.tsx`
- [Calendar logic](https://github.com/kadhiravan-k/learnup/blob/main/lib/services/calendar-service.ts): `lib/services/calendar-service.ts`
- [Focus sessions](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/focus/page.tsx): `app/(app)/focus/page.tsx`
- [Focus timer widget](https://github.com/kadhiravan-k/learnup/blob/main/components/dashboard/FocusEngineWidget.tsx): `components/dashboard/FocusEngineWidget.tsx`
- [Focus timer state](https://github.com/kadhiravan-k/learnup/blob/main/lib/hooks/useFocusTimer.ts): `lib/hooks/useFocusTimer.ts`
- [Notes](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/notes/page.tsx): `app/(app)/notes/page.tsx`

### Insights & planning

- [Learning roadmaps](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/roadmaps/page.tsx): `app/(app)/roadmaps/page.tsx`
- [Learning analytics](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/analytics/page.tsx): `app/(app)/analytics/page.tsx`
- [AI assistant](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/assistant/page.tsx): `app/(app)/assistant/page.tsx`
- [Rewards](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/rewards/page.tsx): `app/(app)/rewards/page.tsx`
- [Skills](https://github.com/kadhiravan-k/learnup/blob/main/app/(app)/skills/page.tsx): `app/(app)/skills/page.tsx`

### Data & integrations

- [Learning item repository](https://github.com/kadhiravan-k/learnup/blob/main/lib/db/repository.ts): `lib/db/repository.ts`
- [Calendar repository](https://github.com/kadhiravan-k/learnup/blob/main/lib/db/calendar-repository.ts): `lib/db/calendar-repository.ts`
- [Notes repository](https://github.com/kadhiravan-k/learnup/blob/main/lib/db/notes-repository.ts): `lib/db/notes-repository.ts`
- [MCP interface](https://github.com/kadhiravan-k/learnup/blob/main/app/api/mcp/route.ts): `app/api/mcp/route.ts`
- [Connector dispatch](https://github.com/kadhiravan-k/learnup/blob/main/lib/connectors/index.ts): `lib/connectors/index.ts`
- **Supabase PostgreSQL**

### Other components

- **Learner**
- **YouTube Data API**

## Connections

- Learner → Login and signup: signs in (evidence: `README.md`)
- Login and signup → Session authentication: authenticates
- Learner → Protected app shell: uses
- Import endpoint → Session authentication: requires auth (evidence: `app/api/learning-items/route.ts`)
- Import endpoint → YouTube import: imports URL (evidence: `app/api/learning-items/route.ts`)
- YouTube import → YouTube metadata: fetches metadata (evidence: `lib/services/import-service.ts`)
- YouTube metadata → YouTube Data API: requests metadata (evidence: `README.md`)
- YouTube import → Learning item repository: saves items (evidence: `lib/services/import-service.ts`)
- Personal library → Import endpoint: imports items
- Personal library → Playlist player: opens playback (evidence: `README.md`)
- Playlist player → YouTube Data API: embeds video (evidence: `README.md`)
- Calendar planning → Calendar logic: uses calendar logic (evidence: `app/(app)/calendar/page.tsx`)
- Calendar logic → Calendar repository: persists calendar data
- Focus timer widget → Focus timer state: reads timer state (evidence: `components/dashboard/FocusEngineWidget.tsx`)
- Focus sessions → Focus timer state: uses timer
- MCP interface → Session authentication: requires auth (evidence: `app/api/mcp/route.ts`)
- MCP interface → Learning item repository: reads courses (evidence: `app/api/mcp/route.ts`)
- MCP interface → Notes repository: reads notes (evidence: `app/api/mcp/route.ts`)
- MCP interface → Connector dispatch: dispatches sync (evidence: `app/api/mcp/route.ts`)
- Connector dispatch → Learner: syncs study data
- Learning item repository → Supabase PostgreSQL: reads and writes
- Calendar repository → Supabase PostgreSQL: reads and writes
- Notes repository → Supabase PostgreSQL: reads and writes
