# fmhy/edit architecture

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

- Interactive diagram: https://gitdiagram.com/fmhy/edit
- Repository: https://github.com/fmhy/edit

## Overview

1. **What this repository is**
   - FMHY is primarily a **content-driven wiki/knowledge base** with a static site frontend, plus a small API layer and a separate auxiliary worker package.
   - The main product is the public site at `fmhy.net`; the repo also supports backups, post archives, and a JSON/API-style search surface.

2. **Primary source of truth: Markdown content**
   - The bulk of the repository lives under `docs/`, where the site’s pages are authored as Markdown.
   - Content is organized by topic (`ai`, `audio`, `gaming`, `video-tools`, etc.), by operational pages (`other/`, `feedback.md`, `privacy.md`), and by chronological posts (`docs/posts/*.md`).
   - This means the architecture is “content first”: most of the site’s structure comes from the file tree, not from a database or application backend.

3. **Static site generation layer**
   - `docs/.vitepress/` is the build system and presentation layer for the wiki.
   - VitePress is extended with custom hooks, markdown transforms, and theme components to generate navigation, metadata, search UI, post pages, and special interactive pages.
   - The folders `hooks/`, `markdown/`, `transformer/`, and `theme/` show a clear separation between content processing, page generation, and UI rendering.

4. **Build-time content processing**
   - The site uses custom build-time logic for things like:
     - deriving post metadata and indexes,
     - transforming Markdown syntax/shortcuts,
     - generating Open Graph/RSS-related data,
     - wiring “starred” and tooltip behaviors,
     - supporting special blocks/components embedded in Markdown.
   - `docs/.vitepress/theme/posts.data.ts` and the transformer files indicate that some site indexes are generated rather than hand-written.

5. **Interactive frontend features inside the docs site**
   - The theme includes components for search, feedback, theme selection, toggles, cards, tooltips, and a “startpage” experience.
   - This is still a static-site architecture, but with client-side enhancements for navigation, filtering, search, and UI personalization.
   - The `docs/.vitepress/theme/components/startpage/` area suggests a dedicated landing page experience with bookmarks, clock, and search bar.

6. **API service boundary**
   - The `api/` directory is a separate service, likely deployed as a worker/serverless endpoint.
   - It exposes at least three concerns:
     - `routes/index.ts` for the base API surface,
     - `routes/single-page.ts` for page lookup/search,
     - `routes/feedback.post.ts` for collecting user feedback.
   - Middleware for **CORS** and **rate limiting** shows the API is designed for public browser access and abuse control.

7. **How the site and API interact**
   - The static wiki is the main experience, while the API supports dynamic features that are awkward to do purely from static Markdown.
   - The README explicitly points users to `api.fmhy.net/single-page` for finding existing entries before contributing, which implies the API backs contribution/search workflows.
   - Feedback submission from the site likely posts to the API route rather than being embedded in the static site itself.

8. **Separate auxiliary package: `pests-repellent`**
   - `pests-repellent/` is an independent package with its own TypeScript config, worker config, and Vitest tests.
   - It is structurally a separate deployable unit from the main docs site and API.
   - From the naming and packaging, it appears to be a small worker/library concerned with abuse mitigation or automated request handling, not core wiki content.

9. **Deployment model**
   - The repo is set up for multiple deployment targets:
     - `deploy-gh-pages.yml` for the static docs site,
     - `deploy-api.yml` for the API/worker service.
   - Cloudflare-style worker configuration is present (`wrangler.toml`, `worker-configuration.d.ts`), while the docs site is built for GitHub Pages.
   - This creates a clean split: static content hosting on one side, edge/API functionality on the other.

10. **Repository-wide tooling and local environment**
   - There is strong support for reproducible development via Docker, Dev Containers, Gitpod, and Nix/Mise config.
   - Formatting and content quality are enforced with Prettier, markdown linting scripts, and a typo list.
   - These tools support a large editorial repository where consistency matters as much as runtime behavior.

11. **Important architectural boundaries**
   - **Content boundary:** Markdown files are the authoritative wiki data.
   - **Presentation boundary:** VitePress themes and components control how content is rendered.
   - **Service boundary:** the API handles dynamic browser-facing capabilities and request protection.
   - **Deployment boundary:** docs and API are deployed independently, with `pests-repellent` as a further separate unit.

12. **Mental model for a diagram**
   - Draw the repo as a **static documentation platform** centered on `docs/`, with a **build pipeline** into a public site.
   - Add a separate **API/edge service** that the site and contributors call for search/feedback.
   - Treat `pests-repellent` as an adjacent worker package with its own lifecycle, not as part of the main documentation rendering path.

Main entry points: [`api/routes`](https://github.com/fmhy/edit/tree/main/api/routes) (API routes), [`docs/.vitepress/config.mts`](https://github.com/fmhy/edit/blob/main/docs/.vitepress/config.mts) (Site config), [`docs/.vitepress/theme/components`](https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/components) (Site widgets), [`package.json`](https://github.com/fmhy/edit/blob/main/package.json) (Repo tooling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Content site"]
  node_docs_root["Wiki pages<br/>markdown content"]
  node_docs_posts["Posts archive<br/>chronological content"]
  node_vitepress_config["Site config<br/>vitepress config<br/>[config.mts]"]
  node_vitepress_hooks["Build hooks<br/>site hooks<br/>[hooks]"]
  node_markdown_transforms["Markdown transforms<br/>md pipeline<br/>[markdown]"]
  node_site_transformer["Content transformer<br/>build transformer<br/>[transformer]"]
  node_theme_shell["Theme shell<br/>ui theme<br/>[theme]"]
  node_theme_components["Site widgets<br/>ui components<br/>[components]"]
  node_startpage_ui["Startpage<br/>landing ui<br/>[startpage]"]
  node_search_index[("Post data<br/>generated index<br/>[posts.data.ts]")]
end

subgraph group_service["Edge services"]
  node_api_root["API routes<br/>edge api"]
  node_api_single_page["Page lookup<br/>api route<br/>[single-page.ts]"]
  node_api_feedback["Feedback ingest<br/>api route<br/>[feedback.post.ts]"]
  node_api_middleware["API guards<br/>middleware"]
  node_pests_worker["Pests repellent<br/>worker package"]
end

subgraph group_ops["Tooling & deploy"]
  node_deploy_docs["Docs deploy<br/>ci workflow"]
  node_deploy_api["API deploy<br/>ci workflow<br/>[deploy-api.yml]"]
  node_repo_tooling["Repo tooling<br/>dev tooling<br/>[package.json]"]
end

node_docs_root -->|"served by"| node_vitepress_config
node_docs_posts -->|"indexed into"| node_search_index
node_vitepress_config -->|"loads"| node_vitepress_hooks
node_vitepress_config -->|"applies"| node_markdown_transforms
node_vitepress_config -->|"renders with"| node_theme_shell
node_vitepress_hooks -->|"uses"| node_site_transformer
node_markdown_transforms -->|"feeds"| node_site_transformer
node_site_transformer -->|"generates"| node_search_index
node_theme_shell -->|"composes"| node_theme_components
node_theme_components -->|"includes"| node_startpage_ui
node_theme_components -->|"queries"| node_api_single_page
node_theme_components -->|"submits"| node_api_feedback
node_api_root -->|"routes"| node_api_single_page
node_api_root -->|"routes"| node_api_feedback
node_api_root -->|"protected by"| node_api_middleware
node_docs_root -->|"deployed by"| node_deploy_docs
node_api_root -->|"deployed by"| node_deploy_api
node_pests_worker -.->|"separately deployed"| node_deploy_api
node_repo_tooling -.->|"supports"| node_docs_root
node_repo_tooling -.->|"supports"| node_api_root
node_repo_tooling -.->|"supports"| node_pests_worker

click node_docs_root "https://github.com/fmhy/edit/tree/main/docs"
click node_docs_posts "https://github.com/fmhy/edit/tree/main/docs/posts"
click node_vitepress_config "https://github.com/fmhy/edit/blob/main/docs/.vitepress/config.mts"
click node_vitepress_hooks "https://github.com/fmhy/edit/blob/main/docs/.vitepress/hooks"
click node_markdown_transforms "https://github.com/fmhy/edit/blob/main/docs/.vitepress/markdown"
click node_site_transformer "https://github.com/fmhy/edit/blob/main/docs/.vitepress/transformer"
click node_theme_shell "https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme"
click node_theme_components "https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/components"
click node_startpage_ui "https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/components/startpage"
click node_search_index "https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/posts.data.ts"
click node_api_root "https://github.com/fmhy/edit/tree/main/api/routes"
click node_api_single_page "https://github.com/fmhy/edit/blob/main/api/routes/single-page.ts"
click node_api_feedback "https://github.com/fmhy/edit/blob/main/api/routes/feedback.post.ts"
click node_api_middleware "https://github.com/fmhy/edit/tree/main/api/middleware"
click node_pests_worker "https://github.com/fmhy/edit/tree/main/pests-repellent"
click node_deploy_docs "https://github.com/fmhy/edit/blob/main/.github/workflows/deploy-gh-pages.yml"
click node_deploy_api "https://github.com/fmhy/edit/blob/main/.github/workflows/deploy-api.yml"
click node_repo_tooling "https://github.com/fmhy/edit/blob/main/package.json"

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_docs_root,node_docs_posts,node_vitepress_config,node_vitepress_hooks,node_markdown_transforms,node_site_transformer,node_theme_shell,node_theme_components,node_startpage_ui,node_search_index toneBlue
class node_api_root,node_api_single_page,node_api_feedback,node_api_middleware,node_pests_worker toneAmber
class node_deploy_docs,node_deploy_api,node_repo_tooling toneMint
```

## Components

### Content site

Markdown wiki content and the VitePress presentation layer that turns it into the public site.

- [Wiki pages](https://github.com/fmhy/edit/tree/main/docs): markdown content · Primary knowledge base and site pages authored in Markdown. · `docs`
- [Posts archive](https://github.com/fmhy/edit/tree/main/docs/posts): chronological content · Time-based announcement and update posts rendered as part of the site. · `docs/posts`
- [Site config](https://github.com/fmhy/edit/blob/main/docs/.vitepress/config.mts): vitepress config · Top-level VitePress configuration and shared constants for the docs site. · `docs/.vitepress/config.mts`
- [Build hooks](https://github.com/fmhy/edit/blob/main/docs/.vitepress/hooks): site hooks · Build-time hooks for metadata, Open Graph, RSS, and templated page generation. · `docs/.vitepress/hooks`
- [Markdown transforms](https://github.com/fmhy/edit/blob/main/docs/.vitepress/markdown): md pipeline · Custom Markdown processing for emoji, headers, base64 handling, and starred content. · `docs/.vitepress/markdown`
- [Content transformer](https://github.com/fmhy/edit/blob/main/docs/.vitepress/transformer): build transformer · Core build-time logic that derives indexes and rewrites content for the site. · `docs/.vitepress/transformer`
- [Theme shell](https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme): ui theme · Main VitePress theme entry, layouts, styles, and post rendering. · `docs/.vitepress/theme`
- [Site widgets](https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/components): ui components · Interactive components for search, feedback, theme selection, toggles, tooltips, and cards. · `docs/.vitepress/theme/components`
- [Startpage](https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/components/startpage): landing ui · Dedicated landing experience with bookmarks, clock, and search bar. · `docs/.vitepress/theme/components/startpage`
- [Post data](https://github.com/fmhy/edit/blob/main/docs/.vitepress/theme/posts.data.ts): generated index · Generated posts data and site-side indexes used by the theme. · `docs/.vitepress/theme/posts.data.ts`

### Edge services

Public API surface and the separate worker package used for request handling and browser-facing dynamic features.

- [API routes](https://github.com/fmhy/edit/tree/main/api/routes): edge api · Public API entrypoint exposing route handlers for browser-facing features. · `api/routes`
- [Page lookup](https://github.com/fmhy/edit/blob/main/api/routes/single-page.ts): api route · Single-page lookup/search endpoint used to find existing entries. · `api/routes/single-page.ts`
- [Feedback ingest](https://github.com/fmhy/edit/blob/main/api/routes/feedback.post.ts): api route · POST endpoint for collecting user feedback from the site. · `api/routes/feedback.post.ts`
- [API guards](https://github.com/fmhy/edit/tree/main/api/middleware): middleware · CORS and rate limiting for the public API surface. · `api/middleware`
- [Pests repellent](https://github.com/fmhy/edit/tree/main/pests-repellent): worker package · Separate deployable worker/package with its own build and tests. · `pests-repellent`

### Tooling & deploy

Repository-wide developer tooling, quality checks, and deployment configuration.

- [Docs deploy](https://github.com/fmhy/edit/blob/main/.github/workflows/deploy-gh-pages.yml): ci workflow · GitHub Pages deployment pipeline for the static wiki site. · `.github/workflows/deploy-gh-pages.yml`
- [API deploy](https://github.com/fmhy/edit/blob/main/.github/workflows/deploy-api.yml): ci workflow · Deployment pipeline for the API/worker service. · `.github/workflows/deploy-api.yml`
- [Repo tooling](https://github.com/fmhy/edit/blob/main/package.json): dev tooling · Shared local development and quality tooling including Docker, Nix/Mise, formatting, and markdown linting. · `package.json`

## Connections

- Wiki pages → Site config: served by · Markdown content is built through the VitePress site configuration.
- Posts archive → Post data: indexed into · Chronological posts feed generated site indexes.
- Site config → Build hooks: loads · Configuration wires in custom build hooks.
- Site config → Markdown transforms: applies · Configuration enables custom Markdown processing.
- Site config → Theme shell: renders with · The docs site uses the custom theme shell for presentation.
- Build hooks → Content transformer: uses · Hooks rely on transformer logic for derived metadata and page generation.
- Markdown transforms → Content transformer: feeds · Markdown transforms prepare content for the transformer pipeline.
- Content transformer → Post data: generates · Build-time logic produces post data and indexes consumed by the theme.
- Theme shell → Site widgets: composes · Layouts and theme entry are built from reusable UI components.
- Site widgets → Startpage: includes · The startpage experience is implemented as a dedicated component set.
- Site widgets → Page lookup: queries · Search and lookup UI can call the API for existing entries.
- Site widgets → Feedback ingest: submits · Feedback UI posts user input to the API.
- API routes → Page lookup: routes · The API surface includes page lookup/search.
- API routes → Feedback ingest: routes · The API surface includes feedback collection.
- API routes → API guards: protected by · Public endpoints are wrapped with CORS and rate limiting.
- Wiki pages → Docs deploy: deployed by · The wiki content is published via the docs deployment workflow.
- API routes → API deploy: deployed by · API routes are published via the API deployment workflow.
- Pests repellent → API deploy: separately deployed · The auxiliary worker package has its own deployment lifecycle.
- Repo tooling → Wiki pages: supports · Repository tooling supports editorial quality and local development.
- Repo tooling → API routes: supports · Shared tooling also covers the API service.
- Repo tooling → Pests repellent: supports · Local tooling includes the separate worker package.
