kostavukicevic.com

FastAPI · Postgres · Next.js · Cytoscape · Docker

Skilltree

A graph explorer for skills and topics with real prerequisite structure: a DAG, not a flat list. Hubs open into their concepts, a concept can wear a different formulation depending on where you stand, and every edge leaving the view leaves a hint about where it goes.

Explore the seed graph

click select · double-click or Enter open a hub · Esc back

The seed data from backend/app/seed.py, run through a browser port of the backend's build_graph and build_focus_graph. Drawing and layout here are simplified; the real frontend renders with Cytoscape and dagre.

01 · how a focus view is built

Open a hub, get a smaller honest graph

Baseline shows hubs, not everything.

Top-level domains (Math, Physics, Signal Processing) are hidden. Their children, the depth-2 hubs, are the baseline's nodes. Concept-to-concept edges are aggregated into hub-to-hub edges, and a recommended edge keeps its best rank.

Inside = descendants + members.

Opening a hub loads all of its taxonomy descendants plus anything that belongs to it through a membership row. The hub itself isn't drawn; you're inside it.

Only active implementations draw edges.

A concept can have several implementation rows. An implementation with context rows is active only when the focus is one of its contexts; one without contexts is always active.

Edges that leave become directional hints.

An edge with one end inside and one outside becomes a hint: depends_on for inside → outside, used_by for outside → inside, grouped by the outside node's hub (taxonomy first, membership as a fallback).

02 · one concept, three formulations

The Fourier transform depends on where you stand

Fourier lives under Methods in the taxonomy but is a portal member of four hubs. It has no core implementation on purpose, which forces a context to choose: the math formulation, the signals one or the physics one. Pick a hub to see which one is active and what it connects to.

03 · data model

Concepts are abstract; implementations carry the edges

Nodes split into abstract concepts and implementation rows underneath them. That split is what makes the focused views possible: edges connect implementations, so the same concept can sit in different prerequisite chains in different contexts.

abstract_nodes

  • slug, title, short_title (for on-graph labels)
  • kind: concept | group
  • parent_id (taxonomy)
  • summary, body_md

impl_nodes

  • abstract_id
  • variant_key (core, math, signals, …)
  • contract_md

impl_contexts

  • impl_id
  • context_abstract_id: where this variant is active

abstract_memberships

  • abstract_id → hub_id
  • role (portal), weight
  • no self-membership (check constraint)

edges

  • src_impl_id → dst_impl_id
  • type: requires | recommended
  • rank (recommended only)
  • seeded through a cycle check

04 · build log

Semantic zoom, the long way

Drill-down navigation that doesn't jitter, doesn't lose your camera and doesn't show the wrong node on the way back out took one long day of attempts. Every fix surfaced the next inconsistency, until it didn't.

    05 · run it

    One command

    Needs Docker with the Compose plugin and GNU Make.

    make dev     # frontend :3000 · backend :8000 · postgres :5432
    make logs
    make down
    make clean   # also deletes the DB volume
    make help

    docker-compose.yml is the baseline; docker-compose.dev.yml layers bind mounts and hot reload on top. There's also a test stack (docker-compose.test.yml) with an async test harness for the focus graph.