LeetCode Animation — Administrator & Developer Guide

1. Architecture Overview

LeetCode Animation is a static content archive of ~100 LeetCode algorithm problems, each presented as an animated GIF visualization, a Chinese markdown article, and optionally a Java reference implementation. There is no runtime service, no database, and no CI — the "architecture" is a folder-naming contract and a small Python scaffolding CLI.

Content production pipeline

┌─────────────────────────────────────────────────────────┐
│               CONTENT PRODUCTION PIPELINE               │
│                                                         │
│  1. Scaffold          2. Author         3. Publish      │
│     (anima CLI)          (human)           (git push)   │
│                                                         │
│  python anima.py  →  Article/*.md    →  git add + push  │
│  new <id> <title>    Animation/*.gif                    │
│       ↓              Code/*.java                        │
│  {id:04d}-{slug}/                                       │
│  ├─ Animation/                                          │
│  ├─ Article/                                            │
│  └─ Code/                                               │
└─────────────────────────────────────────────────────────┘

Note

This is not a conventional software project. There is no build, no test suite, no deploy pipeline. The product is textual and media content; the only executable is a ~100-line Python scaffold tool. The correct mental model is a flat content catalog governed by a folder-naming contract.

Component inventory

Technology stack

What does NOT exist

• No web server, API, or service boundary
• No database, cache, or persistent state outside of git
• No test suite, no CI configuration
• No build system (setup.py, pyproject.toml, Makefile)
• No packaging metadata — anima cannot be pip install-ed
• No configuration files, no .env, no secrets
• No Docker or container configuration
• No internationalization framework

2. System Requirements

For reading content

For using the scaffolding CLI

Dependencies

The requirements.txt contains a single entry:

fire

fire transitively pulls six and termcolor. No other runtime dependencies exist.

Important

The fire version is unpinned, which means pip install will grab the latest release. For reproducibility, consider pinning: fire==0.6.0 (or the latest stable at time of fork).

3. Configuration Reference

This project has no configuration files, environment variables, or CLI flags beyond the anima.py new command arguments.

The naming convention is hardcoded in anima/model.py:

def title_slug(self):
    title_parts = re.split(r'\s+', self.title)
    return f'{self.id:04d}-' + '-'.join(title_parts)

Warning

The slug generator zero-pads to 4 digits via f'{id:04d}' but does not truncate. IDs like 1394 produce 1394-... (4 digits), not 01394-... (5 digits). The existing folder 01394-Find-out-the-lucky-number-in-the-array was created manually with extra padding. Any tooling walking the catalog must handle both widths.

4. Operations

Routine maintenance (if resurrecting the project)

• Broken outbound links. Articles reference external URLs that may go stale. Audit with any link checker (lychee, muffet).
• CDN reachability. README-embedded GIFs may reference external CDN URLs. Clone the repository for local copies as the reliable fallback.
• Catalog-to-filesystem consistency. The READMEs link to specific paths under notes/ and Article/ directories. There is no script verifying these links resolve.

Tip

A simple link-verification script (walk every markdown link in the READMEs, os.path.exists() each local target) is a ~20-line task and would catch most breakage.

Disk usage

The repository is a few hundred MB, dominated by:

• GIFs under Animation/ (typically 500 KB – 3 MB each)
• M4V/MP4 source files (10–50 MB each when present)

Note

Use sparse checkout to pull a subset of problems without downloading the full media collection (see User Guide, Common Tasks).

Backup strategy

The GitHub repository is the durable copy. Anyone forking for preservation should git clone to capture in-repo GIF copies rather than relying on external CDN URLs referenced in the READMEs.

No CI, no tests

This is intentional. Reintroducing automation would add value only if contributions resumed — at which point anima could grow a --dry-run mode, a lint target for article templates, and a link-checker workflow.

Lifecycle state

The repository has not accepted commits since 2022-01-12. Issues #104, #126, #127, #134, #138, #139, #140, #141, #144, and #148 remain open and untriaged.

5. Security

There is almost no attack surface because there is no runtime service.

CDN trust

If README-embedded animation URLs point to an external CDN, a compromise of that CDN would affect the rendered README. Forks should replace external URLs with raw.githubusercontent.com URLs pointing to in-repo copies.

Caution

Do not assume externally hosted GIF URLs are stable or trustworthy long-term. Always prefer the in-repo Animation/ copies as the authoritative source.

anima CLI input sanitization

anima accepts free-form title strings and concatenates them into directory names. The current implementation uses re.split(r'\s+', title) to split on whitespace but does not sanitize path-dangerous characters:

• A title containing / or .. would produce a slug with path separators
• Unicode control characters would be preserved verbatim

Warning

For a single-contributor use case this has never been a practical issue. A fork accepting community CLI input should validate titles against a safe character set (e.g., [A-Za-z0-9 -]) before calling create_solution.

Python dependencies

fire is maintained by Google. It transitively depends on six and termcolor. Neither has known supply-chain issues, but pinning the version in requirements.txt would reduce risk.

6. Developer Internals

Repository structure

LeetCodeAnimation/
├── Readme.md                      Chinese catalog index
├── README-En.md                   English catalog with inline GIFs
├── contributing.md                anima CLI usage (Chinese)
├── requirements.txt               Python deps: fire
├── .gitattributes                 Git attributes
├── .gitignore                     Git ignore rules
├── anima.py                       CLI entrypoint
├── anima/
│   ├── __init__.py                Anima class (new() method)
│   ├── base.py                    Path helpers
│   ├── create.py                  create_solution() orchestration
│   └── model.py                   ProblemInfo + Solution dataclasses
├── template/
│   └── template.md                Article template
├── Pictures/                      Shared images (QR code, banners)
├── notes/                         68 Chinese article write-ups
├── 0001-Two-Sum/                  Per-problem folders (~108 total)
│   ├── Animation/
│   ├── Article/
│   └── Code/                      (optional)
├── ...
└── Interview053-I-Find-Number-In-Sort-Array-I/

Module reference

anima.py (entrypoint)

#!/usr/bin/env python3
import fire
import anima

if __name__ == '__main__':
    fire.Fire(anima.Anima())

Wires the Anima class to the CLI via Google Fire. All Anima public methods become subcommands.

anima/__init__.py — Anima class

anima/base.py — Path helpers

Path resolution uses os.path.realpath(__file__) to handle symlinks.

anima/create.py — Solution creation

Flow:

1. Build ProblemInfo(problem_id, problem_title)
2. Compute solution_dir = project_root / problem.title_slug()
3. If solution_dir exists → print error (Chinese) and exit(1)
4. solution_dir.mkdir() → Solution.create() → copy template.md to article path

anima/model.py — Data models

ProblemInfo dataclass:

Solution dataclass:

The private _create_dirs() method creates Animation/, Article/, and Code/ subdirectories, plus two zero-byte placeholder files: Animation/Animation.m4v and Animation/Animation.gif.

Class hierarchy

Anima                    (anima/__init__.py)
  └── new() → create_solution()

ProblemInfo              (anima/model.py)
  └── title_slug()

Solution                 (anima/model.py)
  ├── create()           (classmethod)
  ├── animation_path()
  ├── article_path()
  ├── doc_path()
  └── code_path()

The problem folder contract

Every per-problem folder must follow this naming and structural convention:

Naming rule: {ID:0>4}-{TitleWithHyphens}/

Directory shape:

{id-slug}/
├── Animation/                   ← the teaching GIF
│   ├── Animation.gif              (created by anima)
│   └── Animation.m4v              (created by anima, optional)
├── Article/                     ← written walkthrough
│   └── {id-slug}.md               (created from template)
└── Code/                        ← optional reference implementation
    └── 1.java                     (free-form naming)

Article template structure

Every article starts from template/template.md with six sections:

The relative image reference ../Animation/Animation.gif in the template assumes the article lives at {id-slug}/Article/{id-slug}.md. Moving articles out of this path (e.g., into notes/) breaks the image reference.

notes/ vs. Article/ distinction

A problem may have one, the other, or both. No automation enforces consistency between them.

Note

The notes/ filenames contain Chinese characters and full-width colons. On Windows systems with legacy encoding, use UTF-8-aware tooling (PowerShell 7+, Git Bash, WSL). Do not rename these files — other documents link to their exact Unicode filenames.

Code solutions inventory

Problems with Java code solutions in Code/ directories:

Tip

Java is the dominant code language. The single C++ file is Problem #215. Code files are standalone — they compile against the standard LeetCode class signature for each problem.

Known limitations of anima

• No rename or delete command. Only creates. Use git mv to rename.
• No validation of problem IDs. Any integer is accepted.
• No idempotency. Re-running against an existing folder exits non-zero with no --force flag.
• No .mp4 placeholder. Only .m4v is created by default.
• Hard-coded template path. Resolved relative to anima/base.py's parent. Moving anima/ breaks it.
• Hard-coded zero-pad width of 4. Problem IDs beyond 9999 will not pad to 5 digits.

Potential improvements

1. Pin fire version in requirements.txt for reproducible installs
2. Add input validation to create_solution to reject path-unsafe characters in titles
3. Add a --force flag to overwrite existing problem directories
4. Link verification script to check that README table links resolve to real files
5. Add a LICENSE file — currently absent, which limits reuse rights under GitHub default ToS
6. Support .mp4 placeholders alongside .m4v in the scaffold
7. Automate README updates when a new problem is scaffolded

Contributing

1. Fork the repository
2. Create a virtual environment and install dependencies: pip install -r requirements.txt
3. Scaffold a new problem: python anima.py new <id> "<title>"
4. Fill in the article, create the animation, optionally add code
5. Update both Readme.md and README-En.md catalog tables
6. Submit a pull request

The repository's contributing.md describes the anima CLI invocation in Chinese.

Warning

Pull requests are not actively reviewed since the repository has been inactive since 2022-01-12. Community issues #104, #126, #127, #134, #138, #139, #140, #141, #144, and #148 remain open and untriaged.