# kaushikappani/ascend architecture

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

- Interactive diagram: https://gitdiagram.com/kaushikappani/ascend
- Repository: https://github.com/kaushikappani/ascend

## Overview

Ascend is a local-first desktop interview-training app. The learner onboards and builds a roadmap, opens generated lessons, answers adaptive questions, and receives grading and mastery updates; practice, company preparation, mock interviews, coach chat, and progress tracking are parallel product workflows. The React renderer reaches Electron main-process services through the preload/API boundary; those services use Claude Agent SDK capabilities and local persistence. The README documents several unsampled capabilities, so their subsystem nodes are retained, while uncertain internal call paths are omitted.

Main entry points: [`src/renderer/src/App.tsx`](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/App.tsx) (App routing), [`src/main/services/lessons.ts`](https://github.com/kaushikappani/ascend/blob/main/src/main/services/lessons.ts) (Lesson service), [`src/main/agent/runtime.ts`](https://github.com/kaushikappani/ascend/blob/main/src/main/agent/runtime.ts) (Claude runtime), [`src/renderer/src/lib/store.ts`](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/lib/store.ts) (UI state and API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Learner experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_learn["Roadmaps"]
  node_lessonui["Lesson player<br/>[LessonPlayer.tsx]"]
  node_practiceui["Practice"]
  node_interviewui["Mock interviews<br/>[InterviewPage.tsx]"]
  node_targetui["Company prep"]
  node_coachui["Coach chat"]
  node_progressui["Progress view"]
  node_settingsui["Settings"]
  node_rendererstate["UI state and API<br/>[store.ts]"]
  node_onboarding["Onboarding<br/>[Onboarding.tsx]"]
end

subgraph group_main["Application services"]
  node_lessons["Lesson service<br/>[lessons.ts]"]
  node_tracks["Track service<br/>[tracks.ts]"]
  node_targets["Target service<br/>[targets.ts]"]
  node_interviews["Interview service<br/>[interviews.ts]"]
  node_chat["Chat service<br/>[chat.ts]"]
  node_insights["Insights service<br/>[insights.ts]"]
  node_jobs["Background jobs<br/>[jobs.ts]"]
  node_events["Events and snapshots<br/>[events.ts]"]
end

subgraph group_ai["AI and learning engine"]
  node_agent["Claude runtime<br/>[runtime.ts]"]
  node_prompts["Agent prompts<br/>[prompts.ts]"]
  node_agenttools["Coach tools<br/>[coachTools.ts]"]
  node_grading["Answer grading<br/>[grading.ts]"]
  node_mastery["Mastery and review<br/>[mastery.ts]"]
  node_planner["Lesson planning<br/>[planner.ts]"]
  node_gamification["XP and rewards<br/>[gamification.ts]"]
end

subgraph group_platform["Desktop and state"]
  node_preload["Preload bridge<br/>[index.ts]"]
  node_mainentry["Main process<br/>[index.ts]"]
  node_ipc["IPC handlers<br/>[ipc.ts]"]
  node_store[("Local learner data<br/>[store.ts]")]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_learn
node_app -->|"routes to"| node_practiceui
node_app -->|"routes to"| node_interviewui
node_app -->|"routes to"| node_targetui
node_app -->|"routes to"| node_coachui
node_app -->|"routes to"| node_progressui
node_app -->|"routes to"| node_settingsui
node_app -->|"opens lesson"| node_lessonui
node_app -->|"shows first"| node_onboarding
node_learn -->|"uses API state"| node_rendererstate
node_lessonui -->|"uses API state"| node_rendererstate
node_interviewui -->|"uses API state"| node_rendererstate
node_progressui -->|"uses API state"| node_rendererstate
node_rendererstate -.->|"invokes bridge"| node_preload
node_preload -.->|"forwards RPC"| node_ipc
node_mainentry -->|"registers handlers"| node_ipc
node_mainentry -->|"imports service"| node_lessons
node_mainentry -->|"imports service"| node_interviews
node_mainentry -->|"imports service"| node_chat
node_lessons -->|"runs generation"| node_agent
node_lessons -->|"builds primer prompt"| node_prompts
node_lessons -->|"grades answers"| node_grading
node_lessons -->|"updates mastery"| node_mastery
node_lessons -->|"plans questions"| node_planner
node_lessons -->|"announces rewards"| node_gamification
node_lessons -->|"starts jobs"| node_jobs
node_lessons -->|"emits updates"| node_events
node_lessons -->|"reads and writes"| node_store
node_interviews -->|"runs sessions"| node_agent
node_interviews -->|"uses prompts"| node_prompts
node_interviews -->|"reads and writes"| node_store
node_tracks -.->|"generates roadmaps"| node_agent
node_targets -.->|"researches companies"| node_agent
node_chat -.->|"runs coach chat"| node_agent
node_agent -.->|"registers MCP tools"| node_agenttools
node_agent -->|"reports activity"| node_jobs
node_agent -->|"streams events"| node_events
node_agent -->|"uses learner data"| node_store
node_store -->|"schedules snapshots"| node_events
node_learner -.->|"sets prep target"| node_targets
node_learner -.->|"views insights"| node_insights

click node_app "https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/App.tsx"
click node_learn "https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/learn"
click node_lessonui "https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/features/lesson/LessonPlayer.tsx"
click node_practiceui "https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/practice"
click node_interviewui "https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/features/interview/InterviewPage.tsx"
click node_targetui "https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/targets"
click node_coachui "https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/coach"
click node_progressui "https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/progress"
click node_settingsui "https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/settings"
click node_rendererstate "https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/lib/store.ts"
click node_preload "https://github.com/kaushikappani/ascend/blob/main/src/preload/index.ts"
click node_mainentry "https://github.com/kaushikappani/ascend/blob/main/src/main/index.ts"
click node_ipc "https://github.com/kaushikappani/ascend/blob/main/src/main/ipc.ts"
click node_lessons "https://github.com/kaushikappani/ascend/blob/main/src/main/services/lessons.ts"
click node_tracks "https://github.com/kaushikappani/ascend/blob/main/src/main/services/tracks.ts"
click node_targets "https://github.com/kaushikappani/ascend/blob/main/src/main/services/targets.ts"
click node_interviews "https://github.com/kaushikappani/ascend/blob/main/src/main/services/interviews.ts"
click node_chat "https://github.com/kaushikappani/ascend/blob/main/src/main/services/chat.ts"
click node_insights "https://github.com/kaushikappani/ascend/blob/main/src/main/services/insights.ts"
click node_agent "https://github.com/kaushikappani/ascend/blob/main/src/main/agent/runtime.ts"
click node_prompts "https://github.com/kaushikappani/ascend/blob/main/src/main/agent/prompts.ts"
click node_agenttools "https://github.com/kaushikappani/ascend/blob/main/src/main/agent/coachTools.ts"
click node_grading "https://github.com/kaushikappani/ascend/blob/main/src/main/engine/grading.ts"
click node_mastery "https://github.com/kaushikappani/ascend/blob/main/src/main/engine/mastery.ts"
click node_planner "https://github.com/kaushikappani/ascend/blob/main/src/main/engine/planner.ts"
click node_gamification "https://github.com/kaushikappani/ascend/blob/main/src/main/engine/gamification.ts"
click node_jobs "https://github.com/kaushikappani/ascend/blob/main/src/main/jobs.ts"
click node_events "https://github.com/kaushikappani/ascend/blob/main/src/main/events.ts"
click node_store "https://github.com/kaushikappani/ascend/blob/main/src/main/store.ts"
click node_onboarding "https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/features/onboarding/Onboarding.tsx"

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_app,node_learn,node_lessonui,node_practiceui,node_interviewui,node_targetui,node_coachui,node_progressui,node_settingsui,node_rendererstate,node_onboarding toneBlue
class node_lessons,node_tracks,node_targets,node_interviews,node_chat,node_insights,node_jobs,node_events toneAmber
class node_agent,node_prompts,node_agenttools,node_grading,node_mastery,node_planner,node_gamification toneMint
class node_preload,node_mainentry,node_ipc,node_store toneRose
class node_learner toneIndigo
```

## Components

### Learner experience

- [App routing](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/App.tsx): `src/renderer/src/App.tsx`
- [Roadmaps](https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/learn): `src/renderer/src/features/learn`
- [Lesson player](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/features/lesson/LessonPlayer.tsx): `src/renderer/src/features/lesson/LessonPlayer.tsx`
- [Practice](https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/practice): `src/renderer/src/features/practice`
- [Mock interviews](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/features/interview/InterviewPage.tsx): `src/renderer/src/features/interview/InterviewPage.tsx`
- [Company prep](https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/targets): `src/renderer/src/features/targets`
- [Coach chat](https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/coach): `src/renderer/src/features/coach`
- [Progress view](https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/progress): `src/renderer/src/features/progress`
- [Settings](https://github.com/kaushikappani/ascend/tree/main/src/renderer/src/features/settings): `src/renderer/src/features/settings`
- [UI state and API](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/lib/store.ts): `src/renderer/src/lib/store.ts`
- [Onboarding](https://github.com/kaushikappani/ascend/blob/main/src/renderer/src/features/onboarding/Onboarding.tsx): `src/renderer/src/features/onboarding/Onboarding.tsx`

### Application services

- [Lesson service](https://github.com/kaushikappani/ascend/blob/main/src/main/services/lessons.ts): `src/main/services/lessons.ts`
- [Track service](https://github.com/kaushikappani/ascend/blob/main/src/main/services/tracks.ts): `src/main/services/tracks.ts`
- [Target service](https://github.com/kaushikappani/ascend/blob/main/src/main/services/targets.ts): `src/main/services/targets.ts`
- [Interview service](https://github.com/kaushikappani/ascend/blob/main/src/main/services/interviews.ts): `src/main/services/interviews.ts`
- [Chat service](https://github.com/kaushikappani/ascend/blob/main/src/main/services/chat.ts): `src/main/services/chat.ts`
- [Insights service](https://github.com/kaushikappani/ascend/blob/main/src/main/services/insights.ts): `src/main/services/insights.ts`
- [Background jobs](https://github.com/kaushikappani/ascend/blob/main/src/main/jobs.ts): `src/main/jobs.ts`
- [Events and snapshots](https://github.com/kaushikappani/ascend/blob/main/src/main/events.ts): `src/main/events.ts`

### AI and learning engine

- [Claude runtime](https://github.com/kaushikappani/ascend/blob/main/src/main/agent/runtime.ts): `src/main/agent/runtime.ts`
- [Agent prompts](https://github.com/kaushikappani/ascend/blob/main/src/main/agent/prompts.ts): `src/main/agent/prompts.ts`
- [Coach tools](https://github.com/kaushikappani/ascend/blob/main/src/main/agent/coachTools.ts): `src/main/agent/coachTools.ts`
- [Answer grading](https://github.com/kaushikappani/ascend/blob/main/src/main/engine/grading.ts): `src/main/engine/grading.ts`
- [Mastery and review](https://github.com/kaushikappani/ascend/blob/main/src/main/engine/mastery.ts): `src/main/engine/mastery.ts`
- [Lesson planning](https://github.com/kaushikappani/ascend/blob/main/src/main/engine/planner.ts): `src/main/engine/planner.ts`
- [XP and rewards](https://github.com/kaushikappani/ascend/blob/main/src/main/engine/gamification.ts): `src/main/engine/gamification.ts`

### Desktop and state

- [Preload bridge](https://github.com/kaushikappani/ascend/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Main process](https://github.com/kaushikappani/ascend/blob/main/src/main/index.ts): `src/main/index.ts`
- [IPC handlers](https://github.com/kaushikappani/ascend/blob/main/src/main/ipc.ts): `src/main/ipc.ts`
- [Local learner data](https://github.com/kaushikappani/ascend/blob/main/src/main/store.ts): `src/main/store.ts`

### Other components

- **Learner**

## Connections

- Learner → App routing: uses (evidence: `src/renderer/src/App.tsx`)
- App routing → Roadmaps: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Practice: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Mock interviews: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Company prep: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Coach chat: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Progress view: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Settings: routes to (evidence: `src/renderer/src/App.tsx`)
- App routing → Lesson player: opens lesson (evidence: `src/renderer/src/App.tsx`)
- App routing → Onboarding: shows first (evidence: `src/renderer/src/App.tsx`)
- Roadmaps → UI state and API: uses API state (evidence: `src/renderer/src/features/learn/PathView.tsx`)
- Lesson player → UI state and API: uses API state (evidence: `src/renderer/src/features/lesson/LessonPlayer.tsx`)
- Mock interviews → UI state and API: uses API state (evidence: `src/renderer/src/features/interview/InterviewPage.tsx`)
- Progress view → UI state and API: uses API state (evidence: `src/renderer/src/features/progress/ProgressPage.tsx`)
- UI state and API → Preload bridge: invokes bridge
- Preload bridge → IPC handlers: forwards RPC
- Main process → IPC handlers: registers handlers (evidence: `src/main/index.ts`)
- Main process → Lesson service: imports service (evidence: `src/main/index.ts`)
- Main process → Interview service: imports service (evidence: `src/main/index.ts`)
- Main process → Chat service: imports service (evidence: `src/main/index.ts`)
- Lesson service → Claude runtime: runs generation (evidence: `src/main/services/lessons.ts`)
- Lesson service → Agent prompts: builds primer prompt (evidence: `src/main/services/lessons.ts`)
- Lesson service → Answer grading: grades answers (evidence: `src/main/services/lessons.ts`)
- Lesson service → Mastery and review: updates mastery (evidence: `src/main/services/lessons.ts`)
- Lesson service → Lesson planning: plans questions (evidence: `src/main/services/lessons.ts`)
- Lesson service → XP and rewards: announces rewards (evidence: `src/main/services/lessons.ts`)
- Lesson service → Background jobs: starts jobs (evidence: `src/main/services/lessons.ts`)
- Lesson service → Events and snapshots: emits updates (evidence: `src/main/services/lessons.ts`)
- Lesson service → Local learner data: reads and writes (evidence: `src/main/services/lessons.ts`)
- Interview service → Claude runtime: runs sessions (evidence: `src/main/services/interviews.ts`)
- Interview service → Agent prompts: uses prompts (evidence: `src/main/services/interviews.ts`)
- Interview service → Local learner data: reads and writes (evidence: `src/main/services/interviews.ts`)
- Track service → Claude runtime: generates roadmaps
- Target service → Claude runtime: researches companies
- Chat service → Claude runtime: runs coach chat
- Claude runtime → Coach tools: registers MCP tools
- Claude runtime → Background jobs: reports activity (evidence: `src/main/agent/runtime.ts`)
- Claude runtime → Events and snapshots: streams events (evidence: `src/main/agent/runtime.ts`)
- Claude runtime → Local learner data: uses learner data (evidence: `src/main/agent/runtime.ts`)
- Local learner data → Events and snapshots: schedules snapshots (evidence: `src/main/events.ts`)
- Learner → Target service: sets prep target
- Learner → Insights service: views insights
