Lanshu Animated Architecture Diagram: Local Python Renderer for Animated Technical GIFs

What Lanshu Animated Architecture Diagram Produces and Who It Is For

The project solves a specific problem: creating technical architecture diagrams that look polished in article contexts, with hand-drawn typography and genuine motion, without requiring a browser, a remote rendering service, or a complex dependency stack.

The README describes its intended use as article explanations, system architecture diagrams, process diagrams, and DailyDoseOfDS-style black-background technical sketches. The outputs are:

- A .excalidraw file containing the diagram in Excalidraw's JSON format, which remains editable in the Excalidraw web application or any editor plugin that supports the format. - A .png static preview of the diagram at full resolution. - An animated .gif with moving glow points and pulsing module highlights.

The default canvas dimensions are 1210 by 1138 pixels, rendered at 20 frames per second across 41 frames, producing a 2.05-second animation loop. These parameters are fixed by the renderer's design, not configurable from the JSON spec.

The target user is someone who writes technical content, such as a developer writing a deep-learning pipeline explainer, and wants an illustration that is both editable and animated without setting up a full design tool.

How the Renderer Works Without Browser Automation

Most diagram-to-image pipelines rely on a headless browser to render the diagram as a page and screenshot it, or they call a remote service. This project does neither. The renderer is a single Python script, scripts/render_animated_diagram.py, that reads the JSON spec, draws each frame using Pillow's image drawing primitives, and assembles the frames into an animated GIF.

The README lists what the renderer does not require: Excalidraw (the web application), browser automation, ImageMagick, remote APIs, and external icon libraries. The only Python dependency is Pillow at version 10.0.0 or later. This means the entire rendering pipeline runs locally without network access once Pillow is installed.

The .excalidraw output is generated programmatically, not captured from a browser render. This means Excalidraw IDs in the output are unique and text fonts are set consistently, properties that the --check flag validates. The motion in the GIF is added in post-processing: glow points move and module highlights pulse on top of the static diagram layout. The --verify flag prints sampled frame differences to confirm that the GIF contains genuine animation, with nonzero changed pixels between frames.

Installing and Running a First Render

The standalone renderer requires only Python 3.9 or later and Pillow.

git clone https://github.com/cclank/lanshu-animated-architecture-diagram.git
cd lanshu-animated-architecture-diagram
python3 -m pip install -r requirements.txt

The requirements.txt contains one line:

Pillow>=10.0.0

To render the bundled sample diagram:

python3 scripts/render_animated_diagram.py \
  --spec assets/default-spec.json \
  --outdir outputs \
  --basename sample \
  --verify

This command reads the default spec from assets/default-spec.json and writes three files into the outputs directory: sample.excalidraw, sample.png, and sample.gif. The --verify flag prints frame-difference statistics to the terminal confirming the GIF is animated.

To also validate the output contract, add --check:

python3 scripts/render_animated_diagram.py \
  --spec assets/default-spec.json \
  --outdir outputs \
  --basename sample \
  --verify \
  --check

The --check flag validates dimensions, GIF frame count, GIF frame duration, sampled motion, unique Excalidraw IDs, text font family, and the absence of embedded external files. It exits nonzero if any required property fails.

Optionally, ffprobe can be used to inspect the GIF's media parameters, but it is not required for the renderer itself.

Placing Lanshu in a Codex Skills Directory

The project is also packaged as a Codex skill. To install it, place the cloned directory in your Codex skills directory:

${CODEX_HOME:-$HOME/.codex}/skills/lanshu-animated-architecture-diagram

Once installed, you invoke it from a Codex session by name:

Use $lanshu-animated-architecture-diagram to turn this article into a premium hand-drawn animated architecture GIF.

The SKILL.md file at the repository root contains the skill contract that Codex reads to understand what the skill does and what inputs it expects. The agents/ directory contains an openai.yaml file for agent configuration.

To validate that the skill directory structure meets the expected format, the README provides a quick_validate.py script from the Codex skills system:

python3 ${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py \
  ${CODEX_HOME:-$HOME/.codex}/skills/lanshu-animated-architecture-diagram

This validation step is separate from the output validation done by --check. It checks the skill directory structure, not the rendered outputs.

The JSON Spec: What You Edit to Customise a Diagram

The renderer reads a JSON spec to determine what to draw. The README identifies the fields you are most likely to edit:

signature
title.prefix
title.highlight
title.subtitle
inputs
core.cards
decision
output
left_panel
center_panel
right_panel

The layout is fixed: there is a top input strip, a middle core pipeline with cards, a decision node, an output section, and three lower panels (left, center, right). You change what text and icons appear within that structure, but you cannot change the structure itself.

The supported icon keys are: folder, file, scan, shield, db, hash, and package. Diagrams that need icons outside this vocabulary are not supported. The README points to references/spec-format.md for detailed documentation of the spec fields.

Start from the bundled template:

cp assets/default-spec.json work/my-diagram-spec.json

Edit work/my-diagram-spec.json with the content for your diagram, then pass it to the renderer with --spec. The README does not document adding new icon types or modifying the layout panels.

The Fixed Visual System: A Trade-off Between Consistency and Flexibility

The README is direct about the project's intentional scope: the visual system is narrow. It uses a dark canvas, a hand-drawn title treatment, a top input strip, a middle core pipeline, bottom panels, and a top-right signature. The README states that this constraint keeps outputs consistent and polished across different architecture topics.

This is a real constraint. If your diagram requires a light canvas, a circular layout, a swimlane structure, or more than seven icon types, this tool will not produce it. The layout is art-directed for a specific aesthetic, not designed as a general-purpose diagram library.

For comparison, Excalidraw itself (the web application) is a free, browser-based whiteboard tool that supports arbitrary layouts, custom icons, and manual node placement. The difference in approach is that Excalidraw requires manual drawing, while lanshu-animated-architecture-diagram generates a polished output automatically from a JSON spec, trading layout flexibility for consistency and automation.

The last push to the repository was on 2026-09-03. The project is MIT-licensed. Optional dependencies listed in the README are ffprobe for media inspection and the Excalidraw editor for manually editing the generated .excalidraw files.

Editorial conclusion

lanshu-animated-architecture-diagram is a good fit for engineers who want to turn a structured JSON spec into a dark-canvas animated GIF for articles or documentation, and who want the output to remain editable in Excalidraw without needing browser automation or a remote API. It is not suitable for teams who need flexible layouts: the visual system is intentionally fixed to a single dark-canvas template. Before committing to it, confirm that the icon vocabulary (folder, file, scan, shield, db, hash, package) and the three-panel layout match your diagram's structure.

Frequently asked questions

Official sources

1. cclank/lanshu-animated-architecture-diagram on GitHub
2. Issues
3. License: MIT
4. README