Architecture · LikeC4
sjarmak.ai
Astro static site whose Markdown content collections form a typed knowledge graph, rendered to static HTML
The whole picture
System landscape
The system in context, then opened up into its containers.
sjarmak.ai — system landscape
index
sjarmak.ai — containers (content → schema → build → graph/knowledge, with two offline pipelines)
websiteSystemAstro static site whose Markdown content collections form a typed knowledge graph, rendered to static HTML
Prototypes & opt-in surfaces
prototypesInside each box
Containers & components
Each part decomposed into the components that implement it. Every box links to its source in the interactive explorer.
Astro site — pages, layouts, components
siteContainersrc/pages + layouts + components — route pages rendered to static HTML at build
Knowledge graph — build-time edges → client Cytoscape
graphContainersrc/lib/graph + src/scripts — build the project/topic/output node-edge set at build time; Cytoscape + fcose renders it in the browser
Knowledge hub — curated threads + retrieval lanes
knowledgeContainersrc/lib/knowledge — resolves curated threads against committed JSON, then computes 3 retrieval lanes (semantic / lexical / graph) + RRF fusion, all at build time
Digest pipeline — autonomous newsletter + podcast producer
digestContainerscripts/digest — cron generates a newsletter+podcast issue via claude-auto, renders audio with local Kokoro TTS, validates, and publishes into the digest collection
Knowledge build — libraries & explorers from ADS
knowledgeBuildContainerscripts/knowledge — Python that pulls NASA ADS biblib + SciX, validates in-repo explorers, and folds new digest papers into the libraries (daily sync check)
How it runs
Walkthrough flows
Dynamic views — the narrative spine of the system, step by step.
Walkthrough — content edit → live page
publishFlowMarkdown is the single source of truth. The Zod schema validates frontmatter and reference() edges at build, so a dangling project→topic link is a CI failure (astro check), not a broken page in production. Render only deploys after checks pass.
Walkthrough — rendering the knowledge graph
graphFlowThe graph is a projection of the typed content, not a parallel data file. buildGraph resolves the reference() edges already validated by the schema; the client explorer only hydrates the result.
Walkthrough — autonomous digest issue
digestFlowA local cron drives claude-auto headless against the code-intel MCP, writes a newsletter + podcast, renders audio with a fully offline Kokoro TTS, dedupes items against recent issues, and (DIGEST_PUSH=1) pushes — the push is itself the deploy trigger.
Where it runs
Deployment
What runs where, and the process & data boundaries between the pieces.
Deployment — where each piece runs
deploymentExplore it live
The figures above are static exports. The interactive explorer lets you pan, zoom, follow relationships, and jump from any box to the source.