# jasonkneen/codefolio architecture

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

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

## Overview

Codefolio is a local-first web app for building executable notebooks on a freeform desk. Users add or import notebook content, edit Markdown and JavaScript cells, run code in a persistent sandbox, and view rich results inline; named-cell references can connect values across cells and notebooks. The canvas and notebook store coordinate editing and persistence. A separate source-project workflow compiles selected notebook source for preview, walkthrough, and ZIP export. The README documents several capabilities whose exact internal wiring is not visible in the sampled excerpts, so those links are limited to supported entry points.

Main entry points: [`src/lib/notebook/store.ts`](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/store.ts) (Notebook store), [`src/components/notebook/notebook-document.tsx`](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/notebook-document.tsx) (Notebook document), [`src/components/canvas/project-preview.tsx`](https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/project-preview.tsx) (Project preview), [`src/lib/notebook/runtime.ts`](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/runtime.ts) (Cell runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desk["Desk canvas"]
  node_root["App shell<br/>[__root.tsx]"]
  node_canvas["Folio canvas<br/>[folio-canvas.tsx]"]
  node_deskstack["Desk layout<br/>[desk-stack.tsx]"]
  node_sidebar["Workspace sidebar"]
end

subgraph group_notebook["Notebook editing"]
  node_document["Notebook document"]
  node_codecell["Code cell<br/>[code-cell.tsx]"]
  node_markdowncell["Markdown cell<br/>[markdown-cell.tsx]"]
  node_artifactcell["Artifact cell<br/>[artifact-cell.tsx]"]
  node_media["Media cells<br/>[image-cell.tsx]"]
  node_store[("Notebook store<br/>[store.ts]")]
  node_persistence["Desk persistence<br/>[persistence.ts]"]
  node_output["Cell output<br/>[cell-output.tsx]"]
end

subgraph group_execution["Cell execution"]
  node_kernel["Sandbox kernel<br/>[sandbox-kernel.ts]"]
  node_runtime["Cell runtime<br/>[runtime.ts]"]
  node_references["Cell references<br/>[cell-references.ts]"]
  node_inspect["Output inspection<br/>[inspect.ts]"]
end

subgraph group_projects["Source projects"]
  node_preview["Project preview"]
  node_compiler["Project compiler"]
  node_frame["Preview frame<br/>[frame.ts]"]
  node_assistant["Project assistant"]
  node_exporter["Project export<br/>[project-export.ts]"]
  node_catalog["Artifact templates<br/>[templates.ts]"]
end

node_user(("Notebook author"))
node_browserstore[("Browser localStorage")]
node_zip["Project ZIP"]

node_user -->|"opens app"| node_root
node_root -->|"mounts"| node_canvas
node_canvas -->|"shows desk"| node_deskstack
node_deskstack -->|"renders notebook"| node_document
node_canvas -->|"updates desk"| node_store
node_sidebar -->|"manages notebooks"| node_store
node_user -->|"edits cells"| node_document
node_document -->|"renders code"| node_codecell
node_document -->|"renders notes"| node_markdowncell
node_document -->|"renders artifacts"| node_artifactcell
node_document -->|"renders media"| node_media
node_document -->|"dispatches edits"| node_store
node_store -->|"persists desk"| node_persistence
node_persistence -->|"reads/writes"| node_browserstore
node_store -->|"runs cells"| node_kernel
node_kernel -->|"evaluates code"| node_runtime
node_runtime -->|"resolves references"| node_references
node_runtime -->|"formats values"| node_inspect
node_runtime -->|"returns results"| node_kernel
node_codecell -->|"requests run"| node_store
node_output -->|"renders results"| node_document
node_store -->|"provides cell output"| node_output
node_user -->|"imports source"| node_sidebar
node_user -->|"previews project"| node_preview
node_preview -->|"reads source notebooks"| node_store
node_preview -->|"compiles modules"| node_compiler
node_preview -->|"creates preview"| node_frame
node_preview -.->|"requests explanation"| node_assistant
node_preview -->|"builds project"| node_exporter
node_exporter -->|"compiles modules"| node_compiler
node_exporter -->|"packages files"| node_zip
node_store -->|"uses templates"| node_catalog

click node_root "https://github.com/jasonkneen/codefolio/blob/main/src/routes/__root.tsx"
click node_canvas "https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/folio-canvas.tsx"
click node_deskstack "https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/desk-stack.tsx"
click node_sidebar "https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/workspace-sidebar.tsx"
click node_preview "https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/project-preview.tsx"
click node_document "https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/notebook-document.tsx"
click node_codecell "https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/code-cell.tsx"
click node_markdowncell "https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/markdown-cell.tsx"
click node_artifactcell "https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/artifact-cell.tsx"
click node_media "https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/image-cell.tsx"
click node_store "https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/store.ts"
click node_persistence "https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/persistence.ts"
click node_kernel "https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/sandbox-kernel.ts"
click node_runtime "https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/runtime.ts"
click node_references "https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/cell-references.ts"
click node_inspect "https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/inspect.ts"
click node_output "https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/cell-output.tsx"
click node_compiler "https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/project-compiler.ts"
click node_frame "https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/frame.ts"
click node_assistant "https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/project-assistant.ts"
click node_exporter "https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/project-export.ts"
click node_catalog "https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/templates.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_root,node_canvas,node_deskstack,node_sidebar toneBlue
class node_document,node_codecell,node_markdowncell,node_artifactcell,node_media,node_store,node_persistence,node_output,node_browserstore toneAmber
class node_kernel,node_runtime,node_references,node_inspect toneMint
class node_preview,node_compiler,node_frame,node_assistant,node_exporter,node_catalog toneRose
class node_user,node_zip toneIndigo
```

## Components

### Desk canvas

- [App shell](https://github.com/jasonkneen/codefolio/blob/main/src/routes/__root.tsx): `src/routes/__root.tsx`
- [Folio canvas](https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/folio-canvas.tsx): `src/components/canvas/folio-canvas.tsx`
- [Desk layout](https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/desk-stack.tsx): `src/components/canvas/desk-stack.tsx`
- [Workspace sidebar](https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/workspace-sidebar.tsx): `src/components/canvas/workspace-sidebar.tsx`

### Notebook editing

- [Notebook document](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/notebook-document.tsx): `src/components/notebook/notebook-document.tsx`
- [Code cell](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/code-cell.tsx): `src/components/notebook/code-cell.tsx`
- [Markdown cell](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/markdown-cell.tsx): `src/components/notebook/markdown-cell.tsx`
- [Artifact cell](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/artifact-cell.tsx): `src/components/notebook/artifact-cell.tsx`
- [Media cells](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/image-cell.tsx): `src/components/notebook/image-cell.tsx`
- [Notebook store](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/store.ts): `src/lib/notebook/store.ts`
- [Desk persistence](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/persistence.ts): `src/lib/notebook/persistence.ts`
- [Cell output](https://github.com/jasonkneen/codefolio/blob/main/src/components/notebook/cell-output.tsx): `src/components/notebook/cell-output.tsx`

### Cell execution

- [Sandbox kernel](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/sandbox-kernel.ts): `src/lib/notebook/sandbox-kernel.ts`
- [Cell runtime](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/runtime.ts): `src/lib/notebook/runtime.ts`
- [Cell references](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/cell-references.ts): `src/lib/notebook/cell-references.ts`
- [Output inspection](https://github.com/jasonkneen/codefolio/blob/main/src/lib/notebook/inspect.ts): `src/lib/notebook/inspect.ts`

### Source projects

- [Project preview](https://github.com/jasonkneen/codefolio/blob/main/src/components/canvas/project-preview.tsx): `src/components/canvas/project-preview.tsx`
- [Project compiler](https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/project-compiler.ts): `src/lib/artifacts/project-compiler.ts`
- [Preview frame](https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/frame.ts): `src/lib/artifacts/frame.ts`
- [Project assistant](https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/project-assistant.ts): `src/lib/artifacts/project-assistant.ts`
- [Project export](https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/project-export.ts): `src/lib/artifacts/project-export.ts`
- [Artifact templates](https://github.com/jasonkneen/codefolio/blob/main/src/lib/artifacts/templates.ts): `src/lib/artifacts/templates.ts`

### Other components

- **Notebook author**
- **Browser localStorage**
- **Project ZIP**

## Connections

- Notebook author → App shell: opens app
- App shell → Folio canvas: mounts
- Folio canvas → Desk layout: shows desk
- Desk layout → Notebook document: renders notebook
- Folio canvas → Notebook store: updates desk
- Workspace sidebar → Notebook store: manages notebooks
- Notebook author → Notebook document: edits cells
- Notebook document → Code cell: renders code
- Notebook document → Markdown cell: renders notes
- Notebook document → Artifact cell: renders artifacts
- Notebook document → Media cells: renders media
- Notebook document → Notebook store: dispatches edits
- Notebook store → Desk persistence: persists desk
- Desk persistence → Browser localStorage: reads/writes
- Notebook store → Sandbox kernel: runs cells
- Sandbox kernel → Cell runtime: evaluates code
- Cell runtime → Cell references: resolves references
- Cell runtime → Output inspection: formats values
- Cell runtime → Sandbox kernel: returns results
- Code cell → Notebook store: requests run
- Cell output → Notebook document: renders results
- Notebook store → Cell output: provides cell output
- Notebook author → Workspace sidebar: imports source
- Notebook author → Project preview: previews project
- Project preview → Notebook store: reads source notebooks
- Project preview → Project compiler: compiles modules
- Project preview → Preview frame: creates preview
- Project preview → Project assistant: requests explanation
- Project preview → Project export: builds project
- Project export → Project compiler: compiles modules
- Project export → Project ZIP: packages files
- Notebook store → Artifact templates: uses templates