# ravindusohan/the-sherlock-dsl architecture

> Architecture diagram of the GitHub repository ravindusohan/the-sherlock-dsl, 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/ravindusohan/the-sherlock-dsl
- Repository: https://github.com/ravindusohan/the-sherlock-dsl

## Overview

Sherlock is a declarative DSL and toolchain for creating STEM animations. The documented authoring workflow starts with a `.sherlock` scene, parses it into a scene representation, previews it, and exports video; the CLI also supports project setup, scene creation, guidance, examples, and diagnostics. This checkout exposes CLI modules and a Next.js scene/compiler interface, but the README says the parser, rendering runtime, and export pipeline are private, and their implementation is not in the supplied tree. The source excerpts show scene-file reads and API parsing calls, but do not establish CLI dispatch or preview-to-render wiring.

Main entry points: [`app/api/compiler/parse-scene/route.ts`](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/parse-scene/route.ts) (Scene parsing API), [`app/api/compiler/latex/route.ts`](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/latex/route.ts) (LaTeX API), [`bin/sherlock.js`](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/bin/sherlock.js) (Sherlock CLI), [`app/layout.tsx`](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/layout.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring tools"]
  node_cli["Sherlock CLI<br/>[sherlock.js]"]
  node_init["Project setup<br/>[init.js]"]
  node_create["Scene creation<br/>[create.js]"]
  node_preview["Live preview<br/>[preview.js]"]
  node_render["Video export<br/>[render.js]"]
  node_code["Live coding<br/>[code.js]"]
  node_interactive["Guided workflow<br/>[interactive.js]"]
  node_guide["DSL guide<br/>[guide.js]"]
  node_examples["Scene examples<br/>[examples.js]"]
  node_config["Project config<br/>[config.js]"]
  node_doctor["Environment check<br/>[doctor.js]"]
  node_workspace["Workspace state<br/>[project-manager.js]"]
end

subgraph group_web["Web interface"]
  node_webapp["Web application<br/>[layout.tsx]"]
  node_compiler["Compiler page<br/>[page.tsx]"]
  node_player["Scene player<br/>[SherlockPlayer.tsx]"]
  node_sceneapi["Scene parsing API<br/>[route.ts]"]
  node_latexapi["LaTeX API<br/>[route.ts]"]
  node_katex["KaTeX renderer<br/>[route.ts]"]
end

subgraph group_engine["Animation pipeline"]
  node_scenefiles["Scene files"]
  node_parser["DSL parser"]
  node_runtime["Animation runtime"]
  node_exporter["MP4 exporter"]
end

node_author(("Scene author"))
node_video["MP4 video"]

node_author -->|"uses"| node_cli
node_author -->|"uses"| node_webapp
node_sceneapi -->|"reads"| node_scenefiles
node_sceneapi -->|"parses with"| node_parser
node_latexapi -->|"renders with"| node_katex

click node_cli "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/bin/sherlock.js"
click node_init "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/init.js"
click node_create "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/create.js"
click node_preview "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/preview.js"
click node_render "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/render.js"
click node_code "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/code.js"
click node_interactive "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/interactive.js"
click node_guide "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/guide.js"
click node_examples "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/examples.js"
click node_config "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/config.js"
click node_doctor "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/doctor.js"
click node_workspace "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/workspace/project-manager.js"
click node_webapp "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/layout.tsx"
click node_compiler "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/compiler/page.tsx"
click node_player "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/components/SherlockPlayer.tsx"
click node_sceneapi "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/parse-scene/route.ts"
click node_latexapi "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/latex/route.ts"
click node_katex "https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/latex/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_cli,node_init,node_create,node_preview,node_render,node_code,node_interactive,node_guide,node_examples,node_config,node_doctor,node_workspace toneBlue
class node_webapp,node_compiler,node_player,node_sceneapi,node_latexapi,node_katex toneAmber
class node_scenefiles,node_parser,node_runtime,node_exporter toneMint
class node_author,node_video toneIndigo
```

## Components

### Authoring tools

- [Sherlock CLI](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/bin/sherlock.js): `bin/sherlock.js`
- [Project setup](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/init.js): `lib/commands/init.js`
- [Scene creation](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/create.js): `lib/commands/create.js`
- [Live preview](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/preview.js): `lib/commands/preview.js`
- [Video export](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/render.js): `lib/commands/render.js`
- [Live coding](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/code.js): `lib/commands/code.js`
- [Guided workflow](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/interactive.js): `lib/commands/interactive.js`
- [DSL guide](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/guide.js): `lib/commands/guide.js`
- [Scene examples](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/examples.js): `lib/commands/examples.js`
- [Project config](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/config.js): `lib/commands/config.js`
- [Environment check](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/commands/doctor.js): `lib/commands/doctor.js`
- [Workspace state](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/lib/workspace/project-manager.js): `lib/workspace/project-manager.js`

### Web interface

- [Web application](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/layout.tsx): `app/layout.tsx`
- [Compiler page](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/compiler/page.tsx): `app/compiler/page.tsx`
- [Scene player](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/components/SherlockPlayer.tsx): `components/SherlockPlayer.tsx`
- [Scene parsing API](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/parse-scene/route.ts): `app/api/compiler/parse-scene/route.ts`
- [LaTeX API](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/latex/route.ts): `app/api/compiler/latex/route.ts`
- [KaTeX renderer](https://github.com/ravindusohan/the-sherlock-dsl/blob/main/app/api/compiler/latex/route.ts): `app/api/compiler/latex/route.ts`

### Animation pipeline

- **Scene files**
- **DSL parser**
- **Animation runtime**
- **MP4 exporter**

### Other components

- **Scene author**
- **MP4 video**

## Connections

- Scene author → Sherlock CLI: uses
- Scene author → Web application: uses
- Scene parsing API → Scene files: reads
- Scene parsing API → DSL parser: parses with
- LaTeX API → KaTeX renderer: renders with