# Codex Structural Audit

Generated: 2026-05-20

Scope: structural issues in `krisyotam.com`, with emphasis on making the codebase leaner, easier to navigate, and safer to change by August. This audit does not cover visual design polish or content quality.

## Executive Summary

The main problem is not one bad subsystem. The project has several parallel sources of truth that have drifted:

- Content type definitions are repeated across routing, sync scripts, feeds, sitemap, search, SEO, and tests.
- SQLite path ownership is split between root `data/` and stale `public/data/` artifacts.
- URL resolution exists in several forms: Next rewrites, canonical helpers, component fallbacks, sitemap, JSON-LD, and script utilities.
- `src/app` mixes route modules with content payloads.
- Client boundaries are broader than they need to be, especially around layout and listing pages.
- `public/scripts` contains both browser assets and private operational tooling.
- Large CSS and data modules have become catch-all files.

The highest-value August target is:

1. One content registry.
2. One database root.
3. One canonical URL resolver.
4. One script path helper.
5. Route folders that only contain route code.
6. Shared listing and tracking primitives instead of repeated page clients.

## Severity 1: Data and Routing Sources of Truth

### 1. Content type lists are duplicated and inconsistent

Evidence:

- `src/app/(content)/[type]/config.ts`
- `next.config.mjs`
- `src/lib/seo.ts`
- `src/lib/content.ts`
- `src/lib/graph.ts`
- `src/app/sitemap.ts`
- `src/app/api/content/search/route.ts`
- `src/app/api/content/md/[slug]/route.ts`
- `src/app/api/system/utils/route.ts`
- `public/scripts/dev/syncContent.js`
- `public/scripts/dev/slugCollisions.js`
- `public/scripts/prod/magic-urls.js`
- `public/scripts/dev/generateMetadata.js`

Why it matters:

Adding or changing a content type requires edits in many unrelated files. Some lists include `documents`, `til`, `now`, `scripts`, `notebooks`, or `sequences`; others exclude them. That makes behavior hard to predict across feeds, search, sitemap, sexy URLs, and sync.

Fix:

Create a single registry that defines each content surface:

- table name
- public route
- canonical URL mode
- sync source
- date column
- category column
- tag relation
- ratings support
- feed/search/sitemap inclusion
- MDX import directory

Suggested file:

- `src/config/contentRegistry.ts` for app/runtime code.
- `scripts/lib/contentRegistry.mjs` or generated JSON for CommonJS scripts and `next.config.mjs`.

First batch:

1. Introduce the registry with current behavior only.
2. Convert read-only consumers: `src/lib/seo.ts`, `src/lib/content.ts`, `src/app/sitemap.ts`, `src/app/api/content/search/route.ts`.
3. Convert write/sync scripts after the registry is proven.

### 2. Database artifact ownership is split

Evidence:

- Runtime defaults use root `data/` via `src/lib/db.ts`.
- Root `data/*.db` is explicitly tracked by `.gitignore`.
- `public/data/content.db`, `public/data/media.db`, and `public/data/system.db` exist as zero-byte files.
- `public/scripts/doc/syncDocs.js` resolves `../../data/content.db` from inside `public/scripts/doc`, which lands at `public/data/content.db`.
- `public/scripts/dev/syncNotebooks.js` has the same public-data path issue.
- `public/scripts/dev/blogActivity.js` and `public/scripts/prod/magic-urls.js` still reference public DB paths.

Why it matters:

The app reads one database root while some scripts mutate or inspect another. This creates silent drift and makes script output untrustworthy. It also keeps fake DB files under a web-served directory.

Fix:

Make root `data/` the only SQLite root. Add a shared script helper:

- `scripts/lib/paths.mjs`
- exports `PROJECT_ROOT`, `DATA_DIR`, `CONTENT_DIR`, and `dbPath(name)`
- honors `KRISYOTAM_DATA_DIR` and `KRISYOTAM_CONTENT_DIR`

First batch:

1. Update `syncDocs.js`, `syncNotebooks.js`, `blogActivity.js`, and `magic-urls.js` to use the helper.
2. Remove stale zero-byte `public/data/*.db`.
3. Document which files in `data/` are source snapshots and which are derived artifacts.
4. Make `git.js` fail on core sync errors instead of catching and continuing.

### 3. Canonical URL behavior is duplicated and drifting

Evidence:

- `next.config.mjs` builds sexy URL rewrites directly from `content.db`.
- `src/lib/canonical-url.ts` mirrors the type list and reserved slug rules.
- `src/app/(content)/[type]/[category]/[slug]/page.tsx` uses `/${slug}` for metadata but hierarchical URLs for JSON-LD and breadcrumbs.
- Shared components fall back to `/${slug}` in `src/components/content/table.tsx`, `src/components/content/directory.tsx`, and `src/components/content/mediaCard.tsx`.
- Some clients pass `route` fields that are ignored by shared components.

Why it matters:

The site convention is sexy URLs. Today that rule is implemented partly by rewrite generation, partly by helper functions, and partly by UI component fallbacks. SEO, JSON-LD, sitemap, breadcrumbs, and client links can disagree.

Fix:

Normalize URLs server-side and pass `item.url` everywhere. Components should render one URL field instead of rebuilding URLs locally.

First batch:

1. Add a server helper that maps DB rows to normalized content cards with `url`.
2. Use `getCanonicalContentUrl` or a generated route manifest in metadata, JSON-LD, breadcrumbs, citations, and view trackers.
3. Remove fallback URL building from table, directory, and media-card components after callers pass URLs.

## Severity 2: App Structure and Route Ownership

### 4. `src/app` contains content payloads

Evidence:

- `src/app/(content)/til/content/*.mdx`
- `src/app/(content)/now/content/*.mdx`
- `src/app/(misc)/surveys/content/*.survey.md`

Why it matters:

The App Router tree should show routing and rendering ownership. Source content inside route folders makes it harder to scan the app tree and blurs the line between code and authored content.

Fix:

Move these payloads to `src/content/...` or the external content repo, then keep `src/app` limited to route modules, layouts, loading states, route-local clients, and route-local styles.

First batch:

1. Move TIL and Now content loaders behind `src/lib/til.ts` and `src/lib/now.ts`.
2. Move the physical files only after imports are centralized.
3. Repeat for surveys after the route behavior is covered by tests.

### 5. TIL and Now detail pages load too much

Evidence:

- `src/app/(content)/til/page.tsx`
- `src/app/(content)/til/[slug]/page.tsx`
- `src/app/(content)/now/page.tsx`
- `src/app/(content)/now/[slug]/page.tsx`

Why it matters:

Index and detail pages repeat full-collection loading and MDX import logic. Detail routes should not scale with collection size.

Fix:

Extract loaders:

- `getTilEntries()`
- `getTilEntry(slug)`
- `getNowEntries()`
- `getNowEntry(slug)`

Then use collection loaders only for indexes and static params.

### 6. Route groups have dead or unclear boundaries

Evidence:

- `src/app/(info)` is empty.
- `src/app/(media)` is empty.
- Media-like pages live under `(tracking)`.
- Misc pages under `(misc)` include several unrelated page families.

Why it matters:

Empty and vague groups weaken the mental map. The App Router tree should answer "where does this page belong?" quickly.

Fix:

Remove empty route groups or add a short route ownership note in `.config/.codex/docs/routes.md` and the architecture map.

## Severity 2: Client Boundaries and Repeated UI State

### 7. Layout header is client-side too high in the tree

Evidence:

- `src/components/layout/header.tsx` starts with `"use client"`.
- It is imported broadly by server-rendered pages.

Why it matters:

Mostly static header markup should not widen the client boundary. The interactive part should be a small island.

Fix:

Split into:

- server-safe header renderer
- small client help or tooltip component
- pure formatting helpers

### 8. Listing clients repeat the same state machinery

Evidence:

- `src/app/(content)/[type]/client.tsx`
- `src/app/(content)/til/client.tsx`
- `src/app/(content)/now/client.tsx`
- `src/app/(content)/scripts/client.tsx`
- `src/app/(content)/sequences/client.tsx`

Repeated logic includes:

- search state
- URL query view sync
- category or tag option construction
- date sorting
- empty states
- header data fallbacks
- slug banners and single-entry modes

Why it matters:

Every new collection page copies decisions from older pages. Small behavior fixes then require many edits.

Fix:

Extract:

- `src/hooks/useContentListingState.ts`
- `src/components/content/CollectionShell.tsx`
- `src/components/content/FacetIndex.tsx`

Keep route clients responsible only for data shape and item renderer choice.

### 9. Tracking pages repeat browser scaffolding

Evidence:

- `src/components/media/tracking-overview.tsx` already contains a shared renderer.
- `src/app/(tracking)/games/client.tsx` still hand-rolls tabs, stat strips, sections, pagination, and empty states.
- `src/app/(tracking)/film/watched/client.tsx` and `src/app/(tracking)/anime/watched/client.tsx` repeat filter and grid scaffolding.

Fix:

Extend `TrackingOverview`, then add a generic `TrackingGridBrowser` for watched/read/played lists.

### 10. `PageDescription` owns too many jobs

Evidence:

- `src/components/layout/page-description.tsx`

Current responsibilities:

- markdown-link parsing
- icon lookup
- modal open state
- sounds
- compact modal markup
- expanded modal markup

Fix:

Extract:

- pure `parseMarkdownLinks` helper with tests
- shared modal body component
- narrow client shell for open and close state

## Severity 2: CSS and Theme Structure

### 11. `globals.css` is a catch-all

Evidence:

- `src/app/globals.css` is about 1,979 lines.
- It contains imports, viewport behavior, code block overrides, hover-card primitives, typography, footer animation, comments, sidenotes, footnotes, lede cards, and print styles.

Why it matters:

Global CSS is now a shared junk drawer. It is hard to know whether a class is global by design, legacy, or route-specific.

Fix:

Move domain styles into `src/app/styles/core/*` and import them through a single file:

- `base.css`
- `typography.css`
- `code.css`
- `comments.css`
- `footnotes.css`
- `sidenotes.css`
- `print.css`
- `cards.css`
- `motion.css`

Keep `globals.css` as the import root plus true app-wide tokens.

### 12. Theme tokens duplicate fallback and class-based modes

Evidence:

- `src/app/styles/themes/default.css`
- duplicate no-JS dark-mode and `.dark` definitions
- repeated pastel token blocks

Fix:

Use layered token groups or generate theme CSS from one source. The first target is no behavior change: reduce duplicate declarations while preserving fallback behavior.

## Severity 3: Scripts and Tooling Shape

### 13. Private operational scripts live under `public/`

Evidence:

- `public/scripts/dev/*`
- `public/scripts/doc/*`
- `public/scripts/prose/*`
- `public/scripts/verse/*`
- `public/scripts/doc/filelist.txt`

Why it matters:

Only browser-delivered scripts belong under `public/`. Commit tooling, DB mutators, importers, document sync, and prose tools should not be web-served.

Fix:

Target shape:

- `public/scripts/footnotes.js`
- `public/scripts/sidenotes.js`
- `public/scripts/prod/*` only if browser-delivered or server-used from public path
- `scripts/dev/*`
- `scripts/doc/*`
- `scripts/prose/*`
- `scripts/verse/*`
- `scripts/lib/*`

Migration needs compatibility shims because project memory currently says script subdirectories are fixed under `public/scripts/{auth,dev,doc,prod,prose,verse}`. This should be changed deliberately in the architecture docs when the migration starts.

### 14. Script comments and hardcoded paths are stale

Evidence:

- `public/scripts/dev/syncContent.js` still documents `public/scripts/keep`.
- `public/scripts/dev/generateMetadata.js` hardcodes `PROJECT_ROOT = '/home/krisyotam/dev/krisyotam.com'`.
- Several scripts hardcode DB or content locations instead of deriving from project root and env vars.

Fix:

After the path helper lands, convert scripts one family at a time and remove stale comments while touching each file.

## Severity 3: Large Data Modules and Testing

### 15. Database modules are too broad

Evidence:

- `src/lib/media-db.ts` is about 837 lines.
- `src/lib/data.ts` is about 713 lines.
- `src/lib/system-db.ts` is about 620 lines.
- Direct SQL is spread across app routes, lib modules, and scripts.

Fix:

Split by domain once the registry exists:

- content collections
- content taxonomy
- content detail lookup
- media film
- media tv
- media anime and manga
- media games
- system roll pages
- system social pages

Avoid splitting before the registry and DB path fixes, or it will preserve the same drift in more files.

### 16. Tests cover utilities more than structure

Evidence:

- `vitest.config.ts` uses Node environment only.
- Existing tests focus on pure utility and config behavior.
- Route clients, route handlers, URL normalization, DB path resolution, and theme tokens have little visible coverage.

Fix:

Start with tests that protect the refactors:

1. Content registry consumers agree on valid types.
2. DB path helper resolves root `data/` by default.
3. Canonical URL resolver returns sexy URLs and document overrides.
4. Listing state hook filters and sorts deterministically.
5. API route handlers return consistent error shapes.

Add jsdom only for components that actually need browser interaction.

## Proposed Work Division After Deduplication

This is the cleanest split between Claude and Codex without both agents touching the same files at once.

### Codex-owned first batch

Files likely touched:

- `src/lib/db.ts`
- new `scripts/lib/paths.mjs`
- `public/scripts/doc/syncDocs.js`
- `public/scripts/dev/syncNotebooks.js`
- `public/scripts/dev/blogActivity.js`
- `public/scripts/prod/magic-urls.js`
- `public/scripts/dev/git.js`
- tests for DB path behavior

Goal:

Fix DB root drift and make script path resolution trustworthy.

### Claude-owned first batch

Files likely touched:

- `src/app/(content)/[type]/config.ts`
- `src/lib/seo.ts`
- `src/lib/content.ts`
- `src/app/sitemap.ts`
- `src/app/api/content/search/route.ts`
- new content registry file
- tests for registry consistency

Goal:

Create the content registry and convert read-only consumers.

### Codex-owned second batch

Files likely touched:

- `src/lib/canonical-url.ts`
- `src/app/(content)/[type]/[category]/[slug]/page.tsx`
- `src/app/(content)/[type]/page.tsx`
- `src/components/content/table.tsx`
- `src/components/content/directory.tsx`
- `src/components/content/mediaCard.tsx`

Goal:

Normalize canonical URLs once and pass `item.url` through shared components.

### Claude-owned second batch

Files likely touched:

- `src/app/(content)/til/page.tsx`
- `src/app/(content)/til/[slug]/page.tsx`
- `src/app/(content)/now/page.tsx`
- `src/app/(content)/now/[slug]/page.tsx`
- new `src/lib/til.ts`
- new `src/lib/now.ts`

Goal:

Extract TIL and Now loaders before moving content out of route folders.

### Later shared batches

- CSS split: one agent owns `globals.css` extraction; the other only reviews imports.
- Listing shell: one agent owns content listing state; the other owns tracking grid browser.
- Script migration out of `public/`: do only after path helper and docs are updated.

## Recommended Order

1. Fix DB root drift and path helper.
2. Add content registry and convert read-only consumers.
3. Normalize canonical URL generation and require `item.url`.
4. Extract TIL and Now loaders.
5. Split header and `PageDescription` client islands.
6. Extract listing and tracking primitives.
7. Split `globals.css`.
8. Move private scripts out of `public/`.
9. Split broad DB modules by domain.

## Notes for Merge With Claude Audit

No `claudeAudit.md` was present in the repo root when this file was written. When Claude's file appears, merge by theme rather than by agent:

- Data and scripts
- Content registry
- Canonical URLs
- Route tree ownership
- Client boundaries
- CSS and themes
- Tests
- Work division

Deduplicate by file path before assigning fixes. The files most likely to attract conflicts are:

- `src/app/(content)/[type]/config.ts`
- `src/lib/seo.ts`
- `src/lib/content.ts`
- `src/lib/data.ts`
- `src/lib/canonical-url.ts`
- `next.config.mjs`
- `src/app/globals.css`
- `public/scripts/dev/git.js`
- `public/scripts/dev/syncContent.js`