wiki/files.md

# Markdown Site - File Structure

A brief description of each file in the codebase.

## Root Files

| File                       | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| `package.json`             | Dependencies and scripts for the blog                |
| `tsconfig.json`            | TypeScript configuration                             |
| `vite.config.ts`           | Vite bundler configuration                           |
| `index.html`               | Main HTML entry with SEO meta tags and JSON-LD       |
| `netlify.toml`             | Netlify deployment and Convex HTTP redirects         |
| `README.md`                | Project documentation                                |
| `AGENTS.md`                | AI coding agent instructions (agents.md spec)        |
| `files.md`                 | This file - codebase structure                       |
| `changelog.md`             | Version history and changes                          |
| `TASK.md`                  | Task tracking and project status                     |
| `FORK_CONFIG.md`           | Fork configuration guide (manual + automated options)|
| `fork-config.json.example` | Template JSON config for automated fork setup        |

## Source Files (`src/`)

### Entry Points

| File            | Description                                |
| --------------- | ------------------------------------------ |
| `main.tsx`      | React app entry point with Convex provider |
| `App.tsx`       | Main app component with routing            |
| `vite-env.d.ts` | Vite environment type definitions          |

### Config (`src/config/`)

| File            | Description                                                                                               |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `siteConfig.ts` | Centralized site configuration (name, logo, blog page, posts display, GitHub contributions, nav order) |

### Pages (`src/pages/`)

| File        | Description                                                       |
| ----------- | ----------------------------------------------------------------- |
| `Home.tsx`  | Landing page with featured content and optional post list         |
| `Blog.tsx`  | Dedicated blog page with post list or card grid view (configurable via siteConfig.blogPage, supports view toggle) |
| `Post.tsx`  | Individual blog post or page view with optional sidebar layout (update SITE_URL/SITE_NAME when forking) |
| `Stats.tsx` | Real-time analytics dashboard with visitor stats and GitHub stars |
| `Write.tsx` | Three-column markdown writing page with Cursor docs-style UI, frontmatter reference with copy buttons, theme toggle, font switcher (serif/sans-serif), and localStorage persistence (not linked in nav) |

### Components (`src/components/`)

| File                      | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `Layout.tsx`              | Page wrapper with search button, theme toggle, mobile menu, and scroll-to-top |
| `ThemeToggle.tsx`         | Theme switcher (dark/light/tan/cloud)                      |
| `PostList.tsx`            | Year-grouped blog post list or card grid (supports list/cards view modes) |
| `BlogPost.tsx`            | Markdown renderer with syntax highlighting and collapsible sections (details/summary) |
| `CopyPageDropdown.tsx`    | Share dropdown for LLMs (ChatGPT, Claude, Perplexity) using raw markdown URLs for better AI parsing, with View as Markdown and Generate Skill options |
| `SearchModal.tsx`         | Full text search modal with keyboard navigation            |
| `FeaturedCards.tsx`       | Card grid for featured posts/pages with excerpts           |
| `LogoMarquee.tsx`         | Scrolling logo gallery with clickable links                |
| `MobileMenu.tsx`          | Slide-out drawer menu for mobile navigation with hamburger button |
| `ScrollToTop.tsx`         | Configurable scroll-to-top button with Phosphor ArrowUp icon |
| `GitHubContributions.tsx` | GitHub activity graph with theme-aware colors and year navigation |
| `VisitorMap.tsx`          | Real-time visitor location map with dotted world display and theme-aware colors |

### Context (`src/context/`)

| File               | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `ThemeContext.tsx` | Theme state management with localStorage persistence |

### Hooks (`src/hooks/`)

| File                 | Description                                   |
| -------------------- | --------------------------------------------- |
| `usePageTracking.ts` | Page view recording and active session heartbeat |

### Styles (`src/styles/`)

| File         | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `global.css` | Global CSS with theme variables, centralized font-size CSS variables for all themes |

## Convex Backend (`convex/`)

| File               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `schema.ts`        | Database schema (posts, pages, viewCounts, pageViews, activeSessions) |
| `posts.ts`         | Queries and mutations for blog posts, view counts                    |
| `pages.ts`         | Queries and mutations for static pages                               |
| `search.ts`        | Full text search queries across posts and pages                      |
| `stats.ts`         | Real-time stats with aggregate component for O(log n) counts, page view recording, session heartbeat |
| `crons.ts`         | Cron job for stale session cleanup                                   |
| `http.ts`          | HTTP endpoints: sitemap, API (update SITE_URL/SITE_NAME when forking) |
| `rss.ts`           | RSS feed generation (update SITE_URL/SITE_TITLE when forking)        |
| `convex.config.ts` | Convex app configuration with aggregate component registrations (pageViewsByPath, totalPageViews, uniqueVisitors) |
| `tsconfig.json`    | Convex TypeScript configuration                                      |

### HTTP Endpoints (defined in `http.ts`)

| Route                      | Description                            |
| -------------------------- | -------------------------------------- |
| `/stats`                   | Real-time site analytics page          |
| `/rss.xml`                 | RSS feed with descriptions             |
| `/rss-full.xml`            | RSS feed with full content for LLMs    |
| `/sitemap.xml`             | Dynamic XML sitemap for search engines |
| `/api/posts`               | JSON list of all posts                 |
| `/api/post`                | Single post as JSON or markdown        |
| `/api/export`              | Batch export all posts with content    |
| `/meta/post`               | Open Graph HTML for social crawlers    |
| `/.well-known/ai-plugin.json` | AI plugin manifest                  |
| `/openapi.yaml`            | OpenAPI 3.0 specification              |
| `/llms.txt`                | AI agent discovery                     |

## Content (`content/blog/`)

Markdown files with frontmatter for blog posts. Each file becomes a blog post.

| Field           | Description                                 |
| --------------- | ------------------------------------------- |
| `title`         | Post title                                  |
| `description`   | Short description for SEO                   |
| `date`          | Publication date (YYYY-MM-DD)               |
| `slug`          | URL path for the post                       |
| `published`     | Whether post is public                      |
| `tags`          | Array of topic tags                         |
| `readTime`      | Estimated reading time                      |
| `image`         | Header/Open Graph image URL (optional)      |
| `excerpt`       | Short excerpt for card view (optional)      |
| `featured`      | Show in featured section (optional)         |
| `featuredOrder` | Order in featured section (optional)        |
| `authorName`    | Author display name (optional)              |
| `authorImage`   | Round author avatar image URL (optional)    |

## Static Pages (`content/pages/`)

Markdown files for static pages like About, Projects, Contact, Changelog.

| Field           | Description                               |
| --------------- | ----------------------------------------- |
| `title`         | Page title                                |
| `slug`          | URL path for the page                     |
| `published`     | Whether page is public                    |
| `order`         | Display order in navigation (lower first) |
| `excerpt`       | Short excerpt for card view (optional)    |
| `featured`      | Show in featured section (optional)       |
| `featuredOrder` | Order in featured section (optional)      |
| `authorName`    | Author display name (optional)            |
| `authorImage`   | Round author avatar image URL (optional)  |

## Scripts (`scripts/`)

| File                 | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `sync-posts.ts`      | Syncs markdown files to Convex at build time               |
| `import-url.ts`      | Imports external URLs as markdown posts (Firecrawl)        |
| `configure-fork.ts`  | Automated fork configuration (reads fork-config.json)      |

### Frontmatter Flow

Frontmatter is the YAML metadata at the top of each markdown file. Here is how it flows through the system:

1. **Content directories** (`content/blog/*.md`, `content/pages/*.md`) contain markdown files with YAML frontmatter
2. **`scripts/sync-posts.ts`** uses `gray-matter` to parse frontmatter and validate required fields
3. **Convex mutations** (`api.posts.syncPostsPublic`, `api.pages.syncPagesPublic`) receive parsed data
4. **`convex/schema.ts`** defines the database structure for storing frontmatter fields

**To add a new frontmatter field**, update:

- `scripts/sync-posts.ts`: Add to `PostFrontmatter` or `PageFrontmatter` interface and parsing logic
- `convex/schema.ts`: Add field to the posts or pages table schema
- `convex/posts.ts` or `convex/pages.ts`: Update sync mutation to handle new field

## Netlify (`netlify/edge-functions/`)

| File         | Description                                                  |
| ------------ | ------------------------------------------------------------ |
| `botMeta.ts` | Edge function for social media crawler detection             |
| `rss.ts`     | Proxies `/rss.xml` and `/rss-full.xml` to Convex HTTP        |
| `sitemap.ts` | Proxies `/sitemap.xml` to Convex HTTP                        |
| `api.ts`     | Proxies `/api/posts`, `/api/post`, `/api/export` to Convex   |
| `geo.ts`     | Returns user geo location from Netlify's automatic geo headers for visitor map |

## Public Assets (`public/`)

| File           | Description                                    |
| -------------- | ---------------------------------------------- |
| `favicon.svg`  | Site favicon                                   |
| `_redirects`   | SPA redirect rules for static files            |
| `robots.txt`   | Crawler rules for search engines and AI bots (update sitemap URL when forking) |
| `llms.txt`     | AI agent discovery file (update site name/URL when forking) |
| `openapi.yaml` | OpenAPI 3.0 specification (update API title when forking) |

### Raw Markdown Files (`public/raw/`)

Static markdown files generated during `npm run sync`. Each published post and page gets a corresponding `.md` file for direct access by users, search engines, and AI agents.

| File Pattern   | Description                                    |
| -------------- | ---------------------------------------------- |
| `{slug}.md`    | Static markdown file for each post/page        |

Access via `/raw/{slug}.md` (e.g., `/raw/setup-guide.md`).

Files include a metadata header with type (post/page), date, reading time, and tags. The CopyPageDropdown includes a "View as Markdown" option that links directly to these files.

### AI Plugin (`public/.well-known/`)

| File              | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `ai-plugin.json`  | AI plugin manifest (update name/description when forking) |

### Images (`public/images/`)

| File             | Description                                  |
| ---------------- | -------------------------------------------- |
| `logo.svg`       | Site logo displayed on homepage              |
| `og-default.svg` | Default Open Graph image for social sharing  |
| `*.png/jpg/svg`  | Blog post images (referenced in frontmatter) |

### Logo Gallery (`public/images/logos/`)

| File                 | Description                              |
| -------------------- | ---------------------------------------- |
| `sample-logo-1.svg`  | Sample logo (replace with your own)      |
| `sample-logo-2.svg`  | Sample logo (replace with your own)      |
| `sample-logo-3.svg`  | Sample logo (replace with your own)      |
| `sample-logo-4.svg`  | Sample logo (replace with your own)      |
| `sample-logo-5.svg`  | Sample logo (replace with your own)      |

## Cursor Rules (`.cursor/rules/`)

| File                       | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `convex-write-conflicts.mdc` | Write conflict prevention patterns for Convex  |
| `convex2.mdc`              | Convex function syntax and examples              |
| `dev2.mdc`                 | Development guidelines and best practices        |
| `help.mdc`                 | Core development guidelines                      |
| `rulesforconvex.mdc`       | Convex schema and function best practices        |
| `sec-check.mdc`            | Security guidelines and audit checklist          |
| `task.mdc`                 | Task list management guidelines                  |
| `write.mdc`                | Writing style guide (activate with @write)       |