Onboarding: JacksonTian/fks

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JacksonTian/fks shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

AVOID — Stale and unlicensed — last commit 2y ago

• 36+ active contributors
• Distributed ownership (top contributor 39% of recent commits)
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JacksonTian/fks repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JacksonTian/fks.

What it runs against: a local clone of JacksonTian/fks — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JacksonTian/fks | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 910 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>JacksonTian/fks</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JacksonTian/fks. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JacksonTian/fks.git
#   cd fks
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JacksonTian/fks and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JacksonTian/fks(\\.git)?\\b" \\
  && ok "origin remote is JacksonTian/fks" \\
  || miss "origin remote is not JacksonTian/fks (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "bin/generate.js" \\
  && ok "bin/generate.js" \\
  || miss "missing critical file: bin/generate.js"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "fks_chart/bower.json" \\
  && ok "fks_chart/bower.json" \\
  || miss "missing critical file: fks_chart/bower.json"
test -f "fks_chart/bower_components/d3/d3.js" \\
  && ok "fks_chart/bower_components/d3/d3.js" \\
  || miss "missing critical file: fks_chart/bower_components/d3/d3.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 910 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~880d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JacksonTian/fks"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

FKS (Frontend Knowledge Structure) is a collaborative, version-controlled knowledge base documenting the complete skillset required for modern frontend engineering. It transforms a static infographic into an interactive, maintainable markdown-based hierarchy covering browsers, programming languages, markup/styling, and dev tools—rendered as an AngularJS + D3 visualization at fks_chart/. The core value is enabling community contributions to track how frontend technology evolves over time via Git history. Two-part structure: (1) source knowledge tree in markdown (referenced in README.md), and (2) fks_chart/ subdir contains the AngularJS + D3 visualization app (bower.json dependencies, angular.js, d3.js, angular-marked for markdown rendering, jQuery for DOM). bin/generate.js likely parses markdown and generates visualization data; the chart is served at fks_chart/index.html (inferred from bower_components presence).

Who it's for

Junior and mid-level frontend engineers seeking a comprehensive roadmap of required skills; senior engineers and technical leads using it as a onboarding reference and knowledge audit tool; contributors (like @jayli) wanting to collectively maintain an up-to-date frontend competency framework.

Maturity & risk

Moderately mature but aging: this is a reference/educational project (not a production library) that appears to have slowed development—bower_components are vendored, suggesting early 2010s tooling. No test suite, CI, or recent commits visible in the file list. Verdict: stable reference material, but not actively maintained; suitable for knowledge lookup, not as a live dependency.

Low technical risk (it's documentation, not executable production code), but low maintenance risk: single maintainer (JacksonTian), no visible CI/CD, relies on old frontend stack (AngularJS 1.x, bower, D3 v3 era). The knowledge content may drift from modern practice (TypeScript, React, Vue, modern CSS are listed but likely under-represented vs. 2024 reality). Contributing requires understanding the markdown structure and chart generation pipeline.

Active areas of work

No active development visible from file list alone. The project appears dormant post-initial community adoption. Last meaningful update likely years ago; bower is deprecated tooling. Knowledge content may be stale on emerging tech (serverless, modern JS frameworks, CSS-in-JS patterns).

Get running

1. Clone: git clone https://github.com/JacksonTian/fks.git && cd fks. 2. Install dependencies: npm install or if bower.json is used: bower install in fks_chart/. 3. View the visualization: open fks_chart/index.html in a browser (or run a local HTTP server: python -m http.server 8000 then navigate to http://localhost:8000/fks_chart/). 4. Edit knowledge: modify the markdown structure in root README.md or similar source files, then run make or node bin/generate.js to regenerate the visualization.

Daily commands:

1. cd fks_chart/. 2. Ensure dependencies installed: bower install (if bower not in npm). 3. Serve over HTTP (required for D3 data loading): python -m http.server 8000 then open http://localhost:8000/. 4. Or: make at root (Makefile likely has a serve target—check Makefile for exact command).

Map of the codebase

• README.md — Primary project documentation explaining the frontend knowledge structure initiative and its collaborative purpose.
• bin/generate.js — Build script that generates the visualization from the knowledge structure data; essential for understanding the build pipeline.
• Makefile — Build automation and project tasks definition; entry point for common development operations.
• fks_chart/bower.json — Frontend dependencies manifest for the visualization chart component; defines Angular, D3, and jQuery integration.
• fks_chart/bower_components/d3/d3.js — Core visualization library used to render the interactive knowledge structure diagram.
• fks_chart/bower_components/angular/angular.js — Application framework for the interactive web interface; handles data binding and DOM manipulation.
• fks_chart/bower_components/angular-marked/angular-marked.js — Markdown renderer integration enabling documentation display within the Angular application.

Components & responsibilities

• bin/generate.js (Node.js, Markdown parsing) — Parses knowledge structure from README.md and produces machine-readable JSON representation for visualization
  • Failure mode: Invalid JSON output prevents visualization from loading; malformed markdown causes parsing errors
• D3.js visualization engine (D3.js, SVG, JavaScript) — Renders hierarchical tree structure as interactive SVG with node positioning, links, and zoom/pan interactions
  • Failure mode: Missing or corrupted data causes layout collapse; large datasets degrade rendering performance
• Angular.js application controller (AngularJS 1.x, data binding) — Manages application state, loads generated data, coordinates between D3 and UI components
  • Failure mode: Unhandled exceptions in scope cause UI freezing; scope leaks degrade memory usage over time
• angular-marked markdown renderer (marked.js, AngularJS directives) — Parses and renders markdown in node descriptions for display in UI tooltips and info panels
  • Failure mode: XSS injection if markdown is not sanitized; missing sanitizer allows script execution

Data flow

• README.md → bin/generate.js — Knowledge structure hierarchy is parsed from markdown format into structured data
• bin/generate.js → generated JSON file (loaded by Angular) — Processed knowledge structure is serialized as JSON for consumption by visualization
• Angular.js controller → D3.js hierarchy layout — JSON knowledge tree is bound to D3's hierarchical data structure for SVG rendering
• D3.js → Browser SVG DOM — Visualization produces SVG elements representing nodes and links in the knowledge graph
• Node descriptions (markdown) → angular-marked directive — Embedded markdown in knowledge entries is parsed and converted to HTML for display

How to make changes

Add a new knowledge domain to the structure

1. Edit the README.md file to add a new category in the frontend knowledge hierarchy under the appropriate parent node (README.md)
2. Run the generate.js script to parse the updated README and create a new visualization dataset (bin/generate.js)
3. Commit changes to git; the visualization updates automatically via the build pipeline (Makefile)

Customize the interactive visualization

1. Modify the D3 rendering logic to change how nodes are positioned, colored, or animated (fks_chart/bower_components/d3/d3.js)
2. Update the Angular controller in the chart application to add interactivity handlers and state management (fks_chart/bower_components/angular/angular.js)
3. Add styles and DOM structure using jQuery if custom event handlers are needed (fks_chart/bower_components/jquery/dist/jquery.js)

Add markdown documentation to knowledge nodes

1. Include markdown syntax in README.md knowledge structure entries (README.md)
2. The angular-marked directive automatically parses and renders the markdown in the visualization UI (fks_chart/bower_components/angular-marked/angular-marked.js)

Why these technologies

• AngularJS (1.x) — Provides lightweight MVC framework for binding generated knowledge structure data to interactive UI without complex build tooling
• D3.js — Industry-standard data visualization library capable of rendering hierarchical knowledge structures as interactive SVG diagrams
• Bower for dependency management — Simplifies frontend library management and allows easy vendor updates for core visualization dependencies
• Node.js generate script — Enables automated transformation of markdown-based knowledge structure into machine-readable JSON for visualization
• Markdown source format — Human-readable, git-friendly format that allows community collaboration while remaining parseable by automation

Trade-offs already made

• Markdown-based source data with post-processing generation

  • Why: Prioritizes community contributions and version control history over real-time dynamic updates
  • Consequence: Requires rebuild step to see changes; prevents live collaborative editing but ensures data integrity and Git auditability

• AngularJS 1.x instead of modern frameworks

  • Why: Repository predates modern frontend tooling; simple CDN-based deployment without build compilation
  • Consequence: Code is maintainable without Node build tools but lacks tree-shaking and modern JavaScript features

• Static visualization generation via generate.js

  • Why: Knowledge structure is semi-static reference material that doesn't require real-time updates
  • Consequence: Simple, cacheable, and performant but requires explicit generation when source changes

Non-goals (don't propose these)

• Real-time collaborative editing—contributions are made via Git pull requests, not live CRDT synchronization
• Backend API or database—all data is embedded in static files and generated artifacts
• Mobile-optimized interface—visualization is designed primarily for desktop viewing
• Search or full-text indexing—navigation is primarily hierarchical browsing
• Authentication or access control—content is publicly viewable without login

Code metrics

• Avg cyclomatic complexity: ~2 — Project is a static visualization tool with straightforward data flow: parse markdown → generate JSON → render with D3. No complex algorithms, async patterns, or error handling paths.

Anti-patterns to avoid

• Global scope pollution via Bower components (Medium) — fks_chart/bower_components/: AngularJS, D3, jQuery, and marked all register globals; no module system prevents namespace conflicts in browser
• Unmaintained dependencies (High) — fks_chart/bower.json: AngularJS 1.x and Bower are deprecated; no lock file ensures reproducible installs; bower_components checked into git causes bloat
• No input validation in generate.js (Medium) — bin/generate.js: Markdown parsing and JSON generation assume well-formed input; malformed README structure could crash generator without error messages

Performance hotspots

• fks_chart/bower_components/d3/d3.js (Rendering performance) — D3 layout calculation becomes CPU-intensive with large datasets (>10k nodes); no pagination or virtualization implemented
• bin/generate.js (Build time) — Sequential markdown parsing and JSON generation blocks build pipeline; no parallel processing for large knowledge structures

Traps & gotchas

1. Bower is deprecated (replaced by npm/yarn)—fks_chart/bower.json may fail on modern Node versions; may need to use legacy npm/Node or manually install bower. 2. D3 v3 API (likely used in chart) differs significantly from modern D3 v6+; updating requires knowledge of force simulation changes. 3. AngularJS 1.x is end-of-life; security/compatibility issues on modern browsers. 4. The visualization requires serving over HTTP (not file://); local testing needs a dev server. 5. No tests, so changes to generate.js or chart rendering have no safety net. 6. Markdown source format is inferred (not formally spec'd); changes must match the expected structure for generate.js to parse correctly.

Architecture

Concepts to learn

• Force-directed graph layout (D3) — FKS uses D3's force simulation to spatially arrange the knowledge tree nodes; understanding this is essential to modify or improve the visualization layout behavior
• Markdown-to-HTML compilation pipeline — bin/generate.js parses markdown source into a data structure that the visualization consumes; understanding this flow is necessary to extend the knowledge structure or change how it's rendered
• AngularJS two-way data binding and directives — The fks_chart visualization is built on AngularJS; to modify the interactive behavior (filtering, zooming, node selection), you need to understand ng-repeat, ng-click, and scope watchers
• SVG and D3 selections — The knowledge tree is rendered as SVG circles and lines by D3; modifying the visual appearance (colors, sizes, labels) requires DOM manipulation via D3 selections
• Bower package management (deprecated) — FKS relies on bower.json for frontend dependencies; while deprecated, understanding bower reveals the project's age and is a blocker for dependency updates
• Knowledge representation and taxonomy design — FKS's core value is structuring frontend skills into a navigable hierarchy; contributing meaningfully requires understanding taxonomy principles and how to categorize emerging technologies

Related repos

• kamranahmedse/developer-roadmap — Comprehensive, actively maintained roadmap for frontend/backend/DevOps paths; modern alternative to FKS with interactive visualization and regular updates
• donnemartin/system-design-primer — Complements FKS with deeper coverage of scalability, system design, and architecture—skills needed beyond the basics in FKS
• airbnb/javascript — De-facto JavaScript style guide and best practices; directly referenced by FKS's JavaScript knowledge node; essential for implementing FKS concepts
• getify/You-Dont-Know-JS — In-depth JavaScript learning resources covering scope, closures, async, types—the deep-dive content FKS's JavaScript branch should link to
• ElemeFE/node-interview — Curated interview questions and knowledge points for Node.js, filling the gap between FKS's high-level 'Node.js' listing and practical backend skills

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Migrate bower_components from version control to .gitignore

The repo currently commits entire bower_components directories (angular, d3, jquery, angular-marked) to Git, which bloats the repository size and violates best practices. These should be excluded via .gitignore and managed through fks_chart/bower.json instead. This would significantly reduce repo size and follow npm/bower conventions.

• [ ] Add 'fks_chart/bower_components/' to .gitignore
• [ ] Update fks_chart/bower.json to ensure all dependencies are properly declared (angular, d3, jquery, angular-marked, marked)
• [ ] Add installation instructions to README.md explaining 'bower install' setup for fks_chart
• [ ] Test that 'bower install' correctly restores all dependencies
• [ ] Create a git commit removing the committed bower_components directory

Add Node.js/npm build script for automated knowledge structure generation

The repo has bin/generate.js which likely transforms the knowledge structure into the visualization, but there's no npm script or clear documentation on how to run it. Adding a documented build process with package.json scripts would enable contributors to regenerate the chart when updating the knowledge structure.

• [ ] Add 'package.json' to root directory with 'generate' and 'build' scripts pointing to bin/generate.js
• [ ] Document in README.md the data source file format that bin/generate.js expects
• [ ] Add a clear 'Contributing' section explaining: 'To update the knowledge structure, modify the source file, run npm run generate, and commit the results'
• [ ] Test that npm run generate successfully produces updated output

Add GitHub Actions workflow for visualization deployment and validation

The repo hosts a visualization at html5ify.com/fks/fks_chart/ but has no CI/CD pipeline to validate that changes to the knowledge structure still generate valid visualizations. A GitHub Actions workflow would catch broken builds when contributors modify the knowledge data.

• [ ] Create .github/workflows/validate.yml that runs on pull requests
• [ ] Add step to install dependencies: 'bower install' in fks_chart/
• [ ] Add step to run bin/generate.js and verify it produces valid output without errors
• [ ] Add step to validate that fks_chart/index.html still loads the generated data correctly
• [ ] Document in CONTRIBUTING.md that CI checks must pass before merging

Good first issues

• Modernize the visualization stack: Migrate from AngularJS 1.x + D3 v3 + bower to React + D3 v6+ (or Visx) + npm. This preserves functionality while fixing security and maintenance issues. Start by creating a React component that reads the knowledge tree JSON and renders it with D3 force layout.: The current stack is unmaintained, blocking contributors unfamiliar with legacy frameworks.
• Create a JSON schema and documentation for the knowledge structure format. Currently, the format that bin/generate.js expects is implicit. Formalize it, add JSON Schema validation, and update the README with contribution guidelines.: New contributors cannot confidently add/modify knowledge entries without reverse-engineering the expected structure.
• Audit the knowledge tree for 2024 relevance: Many entries are outdated (e.g., no mention of TypeScript as default, no Vite/Bun, no modern CSS frameworks). Create a GitHub issue per major gap and invite community PRs to update specific sections (e.g., 'Add Bun and Deno to Node.js alternatives', 'Expand CSS-in-JS and Tailwind', 'Add testing frameworks (Jest, Vitest, Playwright)').: The knowledge base is the project's core value; stale content reduces its usefulness as an onboarding tool.

Top contributors

• @JacksonTian — 39 commits
• @xfq — 11 commits
• @mortonfox — 3 commits
• @hjzheng — 3 commits
• @infinnie — 2 commits

Recent commits

• 5472262 — resort the content (JacksonTian)
• 931beea — 增加nw.js、react native (yhtml5)
• 363ea09 — Update README.md (callpri)
• 27d8b5c — Add Microsoft Edge here too. (#136) (infinnie)
• eddeaa8 — Update README.md (#127) (Pines-Cheng)
• f11aa44 — Add Microsoft Edge (#135) (infinnie)
• e30bb86 — remove duplicate vs code (JacksonTian)
• 85664cd — Update README.md (#131) (wppei)
• 5f1600d — Update README.md (#130) (harveyyeung)
• 0770090 — 更新抓包调试工具 (#129) (Ivanwangcy)

Security observations

This frontend knowledge structure project has significant security concerns primarily related to outdated dependencies and stale third-party libraries. The most critical issues are: (1) AngularJS 1.x is no longer maintained with known CVEs, (2) all bower_components are pinned to old versions from 2013-2014, (3) the marked/angular-marked integration presents XSS risks if not properly configured, and (4) missing security headers on the visualization site. The project appears to be educational/inform

• High · Outdated Dependencies with Known Vulnerabilities — fks_chart/bower_components/angular-marked/package.json. The angular-marked package.json contains significantly outdated dependencies. Grunt (0.4.4), Karma (0.12.9), and other build tools are from 2013-2014 era and likely contain multiple known CVEs. These outdated versions may have unpatched security vulnerabilities. Fix: Update all dependencies to their latest versions. Run 'npm audit' to identify specific vulnerabilities and update packages using 'npm update' or 'npm audit fix'.
• High · Unmanaged Bower Dependencies in Version Control — fks_chart/bower_components/. The fks_chart/bower_components directory contains third-party dependencies checked into version control. This includes AngularJS, jQuery, and D3 libraries. If vulnerabilities are discovered in these libraries, the repository won't automatically reflect security updates, and dependencies can become stale. Fix: Add bower_components/ to .gitignore and rely on bower.json for dependency management. Regenerate dependencies locally using 'bower install' during setup.
• Medium · Marked Markdown Library XSS Risk — fks_chart/bower_components/angular-marked/. The angular-marked package integrates the 'marked' library for markdown parsing. If not properly configured, marked can render unsafe HTML/JavaScript, leading to XSS vulnerabilities. The angular-marked wrapper may not sanitize output by default. Fix: Ensure marked is configured with sanitization enabled. Use Angular's $sanitize service to clean output, or configure marked with {breaks: false, sanitize: true} options.
• Medium · Outdated AngularJS Framework — fks_chart/bower_components/angular/. The bower_components contains AngularJS, which appears to be from the 1.x era based on the bower.json structure. AngularJS 1.x is no longer maintained and contains known security vulnerabilities. The framework reached end-of-life in December 2021. Fix: Migrate to a modern framework (Angular 2+, React, Vue, or similar). If migration isn't possible, ensure AngularJS is upgraded to the latest 1.x patch version (1.8.x) and implement strict Content Security Policy headers.
• Medium · Missing Security Headers Configuration — fks_chart/ (web configuration). No visible configuration for security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.) in the static analysis. The visualization at html5ify.com/fks/fks_chart/ may be vulnerable to clickjacking and injection attacks. Fix: Implement security headers in web server configuration (nginx/Apache) or via meta tags. At minimum: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff.
• Low · No HTTPS Enforcement Visible — README.md. The README references http://html5ify.com/fks/fks_chart/ without HTTPS. While this is a documentation issue, it indicates the demo site may not enforce HTTPS, creating potential for man-in-the-middle attacks. Fix: Update documentation to use https:// URLs and ensure the hosting infrastructure enforces HTTPS with HSTS headers.
• Low · Missing Input Validation in Generate Script — bin/generate.js. The bin/generate.js file (a build tool) was not provided for review. If this script processes user input or external data without validation, it could introduce vulnerabilities during the build process. Fix: Review bin/generate.js to ensure all external inputs are validated and sanitized. Use safe parsing methods and avoid eval() or similar dynamic code execution.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.