# neruaka/atlas architecture

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

- Interactive diagram: https://gitdiagram.com/neruaka/atlas
- Repository: https://github.com/neruaka/atlas
- Video tour (about a minute): https://gitdiagram.com/neruaka/atlas/video

## Overview

Atlas is a self-hosted personal ML learning platform. Its core learner journey spans course lessons and interactive code, persistent progress, and spaced review; the app also exposes planning, projects, career, and orientation tools. The graph emphasizes those product stages and the shared server/data layer. Source excerpts confirm selected API, auth, review, and runtime connections; unsampled feature wiring is shown only where the README documents the capability, not as invented call chains.

Main entry points: [`lib/actions/route.ts`](https://github.com/neruaka/atlas/blob/main/lib/actions/route.ts) (API guards), [`lib/auth/server.ts`](https://github.com/neruaka/atlas/blob/main/lib/auth/server.ts) (Auth service), [`app/api/me/exports/progress/route.ts`](https://github.com/neruaka/atlas/blob/main/app/api/me/exports/progress/route.ts) (Progress export), [`components/lesson/lesson-reader.tsx`](https://github.com/neruaka/atlas/blob/main/components/lesson/lesson-reader.tsx) (Lesson experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning journey"]
  node_lesson["Lessons and labs<br/>[page.tsx]"]
  node_content["Course content<br/>[loader.ts]"]
  node_lesson_ui["Lesson experience<br/>[lesson-reader.tsx]"]
  node_interactive["Interactive content<br/>[index.ts]"]
  node_runtime_ui["Code runner UI<br/>[lesson-runtime.tsx]"]
  node_runtime_engine["Python execution<br/>[pyodide-engine.ts]"]
  node_worker["Browser worker<br/>[pyodide.worker.ts]"]
end

subgraph group_practice["Practice and review"]
  node_progress["Progress tracking<br/>[lesson-state.ts]"]
  node_review_page["Review session<br/>[page.tsx]"]
  node_review_ui["Review controls<br/>[review-session.tsx]"]
  node_fsrs["Spaced repetition<br/>[session.ts]"]
end

subgraph group_planning["Planning and career"]
  node_planning["Study planning<br/>[index.ts]"]
  node_career["Career and projects<br/>[page.tsx]"]
  node_orientation["Orientation report<br/>[index.ts]"]
end

subgraph group_platform["Server and data"]
  node_lesson_state_api["Lesson state API<br/>[route.ts]"]
  node_review_api["Review API<br/>[route.ts]"]
  node_activity_api["Study heartbeat<br/>[route.ts]"]
  node_auth_api["Authentication API<br/>[route.ts]"]
  node_auth["Auth service<br/>[server.ts]"]
  node_route_guard["API guards<br/>[route.ts]"]
  node_database[("Application database<br/>[client.ts]")]
  node_export_api["Progress export<br/>[route.ts]"]
  node_exports["Export service<br/>[index.ts]"]
end

subgraph group_discovery["Learning resources"]
  node_resources["Search and reference<br/>[page.tsx]"]
end

node_learner(("Learner"))

node_learner -->|"opens lessons"| node_lesson
node_lesson -->|"presents lesson"| node_lesson_ui
node_lesson_ui -->|"loads content"| node_content
node_lesson_ui -->|"renders activities"| node_interactive
node_interactive -->|"starts exercises"| node_runtime_ui
node_runtime_ui -->|"dispatches runs"| node_worker
node_worker -->|"runs Python"| node_runtime_engine
node_lesson_state_api -->|"uses guards"| node_route_guard
node_route_guard -->|"checks session"| node_auth
node_route_guard -->|"opens database"| node_database
node_lesson_state_api -->|"reads state"| node_progress
node_learner -->|"reviews cards"| node_review_page
node_review_page -->|"shows session"| node_review_ui
node_review_ui -->|"refreshes session"| node_review_api
node_review_api -->|"uses guards"| node_route_guard
node_review_api -->|"loads session"| node_fsrs
node_review_ui -->|"rates cards"| node_fsrs
node_activity_api -->|"uses guards"| node_route_guard
node_activity_api -->|"records activity"| node_progress
node_learner -->|"plans study"| node_planning
node_learner -->|"explores career"| node_career
node_learner -->|"checks orientation"| node_orientation
node_learner -->|"finds resources"| node_resources
node_auth_api -->|"dispatches auth"| node_auth
node_auth -->|"uses database"| node_database
node_export_api -->|"checks session"| node_auth
node_export_api -->|"opens database"| node_database
node_export_api -->|"exports progress"| node_exports

click node_lesson "https://github.com/neruaka/atlas/blob/main/app/(app)/learn/%5B...id%5D/page.tsx"
click node_content "https://github.com/neruaka/atlas/blob/main/lib/content/loader.ts"
click node_lesson_ui "https://github.com/neruaka/atlas/blob/main/components/lesson/lesson-reader.tsx"
click node_interactive "https://github.com/neruaka/atlas/blob/main/components/mdx/index.ts"
click node_runtime_ui "https://github.com/neruaka/atlas/blob/main/components/runtime/lesson-runtime.tsx"
click node_runtime_engine "https://github.com/neruaka/atlas/blob/main/lib/runtime/pyodide-engine.ts"
click node_worker "https://github.com/neruaka/atlas/blob/main/workers/pyodide.worker.ts"
click node_lesson_state_api "https://github.com/neruaka/atlas/blob/main/app/api/me/lessons/%5Bid%5D/route.ts"
click node_progress "https://github.com/neruaka/atlas/blob/main/lib/progress/lesson-state.ts"
click node_review_page "https://github.com/neruaka/atlas/blob/main/app/(app)/review/page.tsx"
click node_review_ui "https://github.com/neruaka/atlas/blob/main/components/review/review-session.tsx"
click node_review_api "https://github.com/neruaka/atlas/blob/main/app/api/me/review/route.ts"
click node_fsrs "https://github.com/neruaka/atlas/blob/main/lib/fsrs/session.ts"
click node_activity_api "https://github.com/neruaka/atlas/blob/main/app/api/me/activity/route.ts"
click node_planning "https://github.com/neruaka/atlas/blob/main/lib/planning/index.ts"
click node_career "https://github.com/neruaka/atlas/blob/main/app/(app)/career/page.tsx"
click node_orientation "https://github.com/neruaka/atlas/blob/main/lib/orientation/index.ts"
click node_resources "https://github.com/neruaka/atlas/blob/main/app/(app)/search/page.tsx"
click node_auth_api "https://github.com/neruaka/atlas/blob/main/app/api/auth/%5B...all%5D/route.ts"
click node_auth "https://github.com/neruaka/atlas/blob/main/lib/auth/server.ts"
click node_route_guard "https://github.com/neruaka/atlas/blob/main/lib/actions/route.ts"
click node_database "https://github.com/neruaka/atlas/blob/main/lib/db/client.ts"
click node_export_api "https://github.com/neruaka/atlas/blob/main/app/api/me/exports/progress/route.ts"
click node_exports "https://github.com/neruaka/atlas/blob/main/lib/exports/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_lesson,node_content,node_lesson_ui,node_interactive,node_runtime_ui,node_runtime_engine,node_worker toneBlue
class node_progress,node_review_page,node_review_ui,node_fsrs toneAmber
class node_planning,node_career,node_orientation toneMint
class node_lesson_state_api,node_review_api,node_activity_api,node_auth_api,node_auth,node_route_guard,node_database,node_export_api,node_exports toneRose
class node_resources,node_learner toneIndigo
```

## Components

### Learning journey

- [Lessons and labs](https://github.com/neruaka/atlas/blob/main/app/(app)/learn/%5B...id%5D/page.tsx): `app/(app)/learn/[...id]/page.tsx`
- [Course content](https://github.com/neruaka/atlas/blob/main/lib/content/loader.ts): `lib/content/loader.ts`
- [Lesson experience](https://github.com/neruaka/atlas/blob/main/components/lesson/lesson-reader.tsx): `components/lesson/lesson-reader.tsx`
- [Interactive content](https://github.com/neruaka/atlas/blob/main/components/mdx/index.ts): `components/mdx/index.ts`
- [Code runner UI](https://github.com/neruaka/atlas/blob/main/components/runtime/lesson-runtime.tsx): `components/runtime/lesson-runtime.tsx`
- [Python execution](https://github.com/neruaka/atlas/blob/main/lib/runtime/pyodide-engine.ts): `lib/runtime/pyodide-engine.ts`
- [Browser worker](https://github.com/neruaka/atlas/blob/main/workers/pyodide.worker.ts): `workers/pyodide.worker.ts`

### Practice and review

- [Progress tracking](https://github.com/neruaka/atlas/blob/main/lib/progress/lesson-state.ts): `lib/progress/lesson-state.ts`
- [Review session](https://github.com/neruaka/atlas/blob/main/app/(app)/review/page.tsx): `app/(app)/review/page.tsx`
- [Review controls](https://github.com/neruaka/atlas/blob/main/components/review/review-session.tsx): `components/review/review-session.tsx`
- [Spaced repetition](https://github.com/neruaka/atlas/blob/main/lib/fsrs/session.ts): `lib/fsrs/session.ts`

### Planning and career

- [Study planning](https://github.com/neruaka/atlas/blob/main/lib/planning/index.ts): `lib/planning/index.ts`
- [Career and projects](https://github.com/neruaka/atlas/blob/main/app/(app)/career/page.tsx): `app/(app)/career/page.tsx`
- [Orientation report](https://github.com/neruaka/atlas/blob/main/lib/orientation/index.ts): `lib/orientation/index.ts`

### Server and data

- [Lesson state API](https://github.com/neruaka/atlas/blob/main/app/api/me/lessons/%5Bid%5D/route.ts): `app/api/me/lessons/[id]/route.ts`
- [Review API](https://github.com/neruaka/atlas/blob/main/app/api/me/review/route.ts): `app/api/me/review/route.ts`
- [Study heartbeat](https://github.com/neruaka/atlas/blob/main/app/api/me/activity/route.ts): `app/api/me/activity/route.ts`
- [Authentication API](https://github.com/neruaka/atlas/blob/main/app/api/auth/%5B...all%5D/route.ts): `app/api/auth/[...all]/route.ts`
- [Auth service](https://github.com/neruaka/atlas/blob/main/lib/auth/server.ts): `lib/auth/server.ts`
- [API guards](https://github.com/neruaka/atlas/blob/main/lib/actions/route.ts): `lib/actions/route.ts`
- [Application database](https://github.com/neruaka/atlas/blob/main/lib/db/client.ts): `lib/db/client.ts`
- [Progress export](https://github.com/neruaka/atlas/blob/main/app/api/me/exports/progress/route.ts): `app/api/me/exports/progress/route.ts`
- [Export service](https://github.com/neruaka/atlas/blob/main/lib/exports/index.ts): `lib/exports/index.ts`

### Learning resources

- [Search and reference](https://github.com/neruaka/atlas/blob/main/app/(app)/search/page.tsx): `app/(app)/search/page.tsx`

### Other components

- **Learner**

## Connections

- Learner → Lessons and labs: opens lessons
- Lessons and labs → Lesson experience: presents lesson
- Lesson experience → Course content: loads content
- Lesson experience → Interactive content: renders activities
- Interactive content → Code runner UI: starts exercises
- Code runner UI → Browser worker: dispatches runs
- Browser worker → Python execution: runs Python
- Lesson state API → API guards: uses guards
- API guards → Auth service: checks session
- API guards → Application database: opens database
- Lesson state API → Progress tracking: reads state
- Learner → Review session: reviews cards
- Review session → Review controls: shows session
- Review controls → Review API: refreshes session
- Review API → API guards: uses guards
- Review API → Spaced repetition: loads session
- Review controls → Spaced repetition: rates cards
- Study heartbeat → API guards: uses guards
- Study heartbeat → Progress tracking: records activity
- Learner → Study planning: plans study
- Learner → Career and projects: explores career
- Learner → Orientation report: checks orientation
- Learner → Search and reference: finds resources
- Authentication API → Auth service: dispatches auth
- Auth service → Application database: uses database
- Progress export → Auth service: checks session
- Progress export → Application database: opens database
- Progress export → Export service: exports progress