# arty3/journal architecture

> Architecture diagram of the GitHub repository arty3/journal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arty3/journal
- Repository: https://github.com/arty3/journal

## Overview

Journal is a static public project-and-research publication. Authors add Markdown/MDX entries with metadata; the site validates and renders them, then presents a landing page, sorted and filterable listings, individual entries, tag views, and RSS/Atom feeds. Date parsing and entry utilities form the shared domain layer. The excerpts establish collection validation, date and feed logic, and Markdown plugin configuration; links to unsampled page implementations are shown as unverified where needed.

Main entry points: [`src/lib/entries.ts`](https://github.com/arty3/journal/blob/main/src/lib/entries.ts) (Entry metadata), [`src/content.config.ts`](https://github.com/arty3/journal/blob/main/src/content.config.ts) (Entry collection), [`src/pages/entries/index.astro`](https://github.com/arty3/journal/blob/main/src/pages/entries/index.astro) (Entry listing), [`astro.config.mjs`](https://github.com/arty3/journal/blob/main/astro.config.mjs) (Markdown rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Entry authoring"]
  node_entryfiles["Entry files"]
end

subgraph group_content["Content processing"]
  node_collection["Entry collection<br/>[content.config.ts]"]
  node_markdown["Markdown rendering<br/>[astro.config.mjs]"]
  node_lazyimages["Lazy images"]
  node_mathtext["Math text fixes"]
  node_dates["Date utilities<br/>[dates.ts]"]
  node_entrylogic["Entry metadata<br/>[entries.ts]"]
  node_tagcolors["Semantic tag colors<br/>[tagColors.ts]"]
  node_tagcache[("Embedding cache")]
end

subgraph group_site["Journal experience"]
  node_landing["Landing page<br/>[index.astro]"]
  node_entrylist["Entry listing<br/>[index.astro]"]
  node_entryview["Entry detail<br/>[&#91;id&#93;.astro]"]
  node_tagview["Tag archive<br/>[&#91;tag&#93;.astro]"]
  node_entrylistcomponent["Entry list<br/>[EntryList.astro]"]
  node_entrycontrols["Entry controls"]
  node_layout["Base layout<br/>[Base.astro]"]
end

subgraph group_feeds["Subscriptions"]
  node_rss["RSS feed<br/>[rss.xml.ts]"]
  node_atom["Atom feed<br/>[atom.xml.ts]"]
end

node_author(("Journal author"))
node_readers(("Feed readers"))

node_author -->|"writes"| node_entryfiles
node_entryfiles -->|"loads entries"| node_collection
node_collection -->|"validates dates"| node_dates
node_collection -.->|"provides entries"| node_entrylogic
node_entrylogic -->|"uses date rules"| node_dates
node_markdown -->|"registers plugin"| node_lazyimages
node_markdown -->|"registers plugin"| node_mathtext
node_entrylogic -->|"supplies entries"| node_rss
node_entrylogic -->|"supplies entries"| node_atom
node_entrylogic -.->|"provides latest entry"| node_landing
node_entrylogic -.->|"sorts entries"| node_entrylist
node_entrylogic -.->|"provides metadata"| node_entryview
node_entrylogic -.->|"provides tagged entries"| node_tagview
node_entrylist -.->|"renders entries"| node_entrylistcomponent
node_entrylist -.->|"offers filters"| node_entrycontrols
node_entryview -.->|"renders body"| node_markdown
node_tagview -.->|"uses tag hues"| node_tagcolors
node_tagcolors -->|"reads and writes"| node_tagcache
node_rss -->|"publishes feed"| node_readers
node_atom -->|"publishes feed"| node_readers

click node_entryfiles "https://github.com/arty3/journal/tree/main/src/content/entries"
click node_collection "https://github.com/arty3/journal/blob/main/src/content.config.ts"
click node_markdown "https://github.com/arty3/journal/blob/main/astro.config.mjs"
click node_lazyimages "https://github.com/arty3/journal/blob/main/src/lib/rehypeLazyImages.mjs"
click node_mathtext "https://github.com/arty3/journal/blob/main/src/lib/rehypeMathTextUnderscores.mjs"
click node_dates "https://github.com/arty3/journal/blob/main/src/lib/dates.ts"
click node_entrylogic "https://github.com/arty3/journal/blob/main/src/lib/entries.ts"
click node_tagcolors "https://github.com/arty3/journal/blob/main/src/lib/tagColors.ts"
click node_tagcache "https://github.com/arty3/journal/blob/main/src/data/tag-embeddings.json"
click node_landing "https://github.com/arty3/journal/blob/main/src/pages/index.astro"
click node_entrylist "https://github.com/arty3/journal/blob/main/src/pages/entries/index.astro"
click node_entryview "https://github.com/arty3/journal/blob/main/src/pages/entries/%5Bid%5D.astro"
click node_tagview "https://github.com/arty3/journal/blob/main/src/pages/tags/%5Btag%5D.astro"
click node_entrylistcomponent "https://github.com/arty3/journal/blob/main/src/components/EntryList.astro"
click node_entrycontrols "https://github.com/arty3/journal/blob/main/src/components/EntryControls.astro"
click node_layout "https://github.com/arty3/journal/blob/main/src/layouts/Base.astro"
click node_rss "https://github.com/arty3/journal/blob/main/src/pages/rss.xml.ts"
click node_atom "https://github.com/arty3/journal/blob/main/src/pages/atom.xml.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entryfiles toneBlue
class node_collection,node_markdown,node_lazyimages,node_mathtext,node_dates,node_entrylogic,node_tagcolors,node_tagcache toneAmber
class node_landing,node_entrylist,node_entryview,node_tagview,node_entrylistcomponent,node_entrycontrols,node_layout toneMint
class node_rss,node_atom toneRose
class node_author,node_readers toneIndigo
```

## Components

### Entry authoring

- [Entry files](https://github.com/arty3/journal/tree/main/src/content/entries): `src/content/entries`

### Content processing

- [Entry collection](https://github.com/arty3/journal/blob/main/src/content.config.ts): `src/content.config.ts`
- [Markdown rendering](https://github.com/arty3/journal/blob/main/astro.config.mjs): `astro.config.mjs`
- [Lazy images](https://github.com/arty3/journal/blob/main/src/lib/rehypeLazyImages.mjs): `src/lib/rehypeLazyImages.mjs`
- [Math text fixes](https://github.com/arty3/journal/blob/main/src/lib/rehypeMathTextUnderscores.mjs): `src/lib/rehypeMathTextUnderscores.mjs`
- [Date utilities](https://github.com/arty3/journal/blob/main/src/lib/dates.ts): `src/lib/dates.ts`
- [Entry metadata](https://github.com/arty3/journal/blob/main/src/lib/entries.ts): `src/lib/entries.ts`
- [Semantic tag colors](https://github.com/arty3/journal/blob/main/src/lib/tagColors.ts): `src/lib/tagColors.ts`
- [Embedding cache](https://github.com/arty3/journal/blob/main/src/data/tag-embeddings.json): `src/data/tag-embeddings.json`

### Journal experience

- [Landing page](https://github.com/arty3/journal/blob/main/src/pages/index.astro): `src/pages/index.astro`
- [Entry listing](https://github.com/arty3/journal/blob/main/src/pages/entries/index.astro): `src/pages/entries/index.astro`
- [Entry detail](https://github.com/arty3/journal/blob/main/src/pages/entries/%5Bid%5D.astro): `src/pages/entries/[id].astro`
- [Tag archive](https://github.com/arty3/journal/blob/main/src/pages/tags/%5Btag%5D.astro): `src/pages/tags/[tag].astro`
- [Entry list](https://github.com/arty3/journal/blob/main/src/components/EntryList.astro): `src/components/EntryList.astro`
- [Entry controls](https://github.com/arty3/journal/blob/main/src/components/EntryControls.astro): `src/components/EntryControls.astro`
- [Base layout](https://github.com/arty3/journal/blob/main/src/layouts/Base.astro): `src/layouts/Base.astro`

### Subscriptions

- [RSS feed](https://github.com/arty3/journal/blob/main/src/pages/rss.xml.ts): `src/pages/rss.xml.ts`
- [Atom feed](https://github.com/arty3/journal/blob/main/src/pages/atom.xml.ts): `src/pages/atom.xml.ts`

### Other components

- **Journal author**
- **Feed readers**

## Connections

- Journal author → Entry files: writes (evidence: `README.md`)
- Entry files → Entry collection: loads entries (evidence: `src/content.config.ts`)
- Entry collection → Date utilities: validates dates (evidence: `src/content.config.ts`)
- Entry collection → Entry metadata: provides entries
- Entry metadata → Date utilities: uses date rules (evidence: `src/lib/entries.ts`)
- Markdown rendering → Lazy images: registers plugin (evidence: `astro.config.mjs`)
- Markdown rendering → Math text fixes: registers plugin (evidence: `astro.config.mjs`)
- Entry metadata → RSS feed: supplies entries (evidence: `src/pages/rss.xml.ts`)
- Entry metadata → Atom feed: supplies entries (evidence: `src/pages/atom.xml.ts`)
- Entry metadata → Landing page: provides latest entry
- Entry metadata → Entry listing: sorts entries
- Entry metadata → Entry detail: provides metadata
- Entry metadata → Tag archive: provides tagged entries
- Entry listing → Entry list: renders entries
- Entry listing → Entry controls: offers filters
- Entry detail → Markdown rendering: renders body
- Tag archive → Semantic tag colors: uses tag hues
- Semantic tag colors → Embedding cache: reads and writes (evidence: `src/lib/tagColors.ts`)
- RSS feed → Feed readers: publishes feed (evidence: `README.md`)
- Atom feed → Feed readers: publishes feed (evidence: `src/pages/atom.xml.ts`)
