#Merged Structural Audit: krisyotam.com

Date: 2026-05-20 Sources: claudeAudit.md (Claude) + codexAudit.md (Codex) Goal: Lean, navigable codebase by August 2026

---

#Decisions Applied Before Merge

• Fonts: Ignore. Being restructured via CDN work in oasis/cdn. Not a codebase problem.
• Analytics DB: Keep on Neon (external). It's lossy data, not worth hosting locally.
• All other DBs: Local SQLite only. Phase out any other external DB references.
• reference-db.ts singleton: Migrate to withDb() pattern (local SQLite, just fix the access pattern).

---

#Phase 1: Sources of Truth

These are the highest-leverage fixes. Every later phase builds on them.

#1.1 Content Registry (Codex finding, confirmed by Claude)

Problem: Content type definitions are duplicated across 13+ files. Adding a content type requires touching routing, sync scripts, feeds, sitemap, search, SEO, and tests. Some lists include documents, til, now, scripts, notebooks, sequences; others exclude them.

Files affected:

• 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

Fix: Single src/config/contentRegistry.ts defining table name, public route, canonical URL mode, sync source, date/category columns, feed/search/sitemap inclusion. Mirror as scripts/lib/contentRegistry.mjs for CommonJS scripts.

Work:

1. Introduce registry with current behavior only (no new features)
2. Convert read-only consumers: seo.ts, content.ts, sitemap.ts, api/content/search
3. Convert write/sync scripts after registry is proven

#1.2 Database Root Drift (Codex finding)

Problem: Runtime uses root data/ via src/lib/db.ts, but some scripts resolve paths relative to public/scripts/, landing at public/data/ instead. Zero-byte .db files exist in public/data/.

Files affected:

• public/scripts/doc/syncDocs.js (resolves ../../data/content.db from inside public/scripts/doc)
• public/scripts/dev/syncNotebooks.js
• public/scripts/dev/blogActivity.js
• public/scripts/prod/magic-urls.js

Fix: Create scripts/lib/paths.mjs exporting PROJECT_ROOT, DATA_DIR, CONTENT_DIR, dbPath(name). Honor KRISYOTAM_DATA_DIR. Delete zero-byte public/data/*.db files.

#1.3 Canonical URL Drift (Codex finding, confirmed by Claude)

Problem: Sexy URLs are implemented in 3 places that can disagree:

• next.config.mjs builds rewrite rules from content.db
• src/lib/canonical-url.ts mirrors type list and reserved slug rules
• Components fall back to /${slug} locally in table.tsx, directory.tsx, mediaCard.tsx

Fix: Normalize URLs server-side, pass item.url everywhere. Components render one URL field instead of rebuilding URLs locally. Use getCanonicalContentUrl in metadata, JSON-LD, breadcrumbs, citations.

#1.4 reference-db.ts Singleton (Claude finding)

Problem: reference-db.ts uses a manual singleton pattern instead of the project's withDb() wrapper. Connection never closed. This is the only SQLite file that doesn't use the canonical pattern.

Fix: Rewrite to use withDb('reference', ...). Delete the manual caching code.

---

#Phase 2: Route Consolidation

#2.1 Tracking Route Duplication (Claude finding, confirmed by Codex)

Problem: 5 near-identical page sets + 7 identical layouts + 5 near-identical API routes + 5 near-identical client components. The single biggest structural redundancy in the codebase.

Scope:

• Pages: (tracking)/{anime,film,tv,games,manga}/page.tsx + watched/read/played subpages
• Layouts: 7 files, all 12 lines, all identical
• APIs: api/tracking/{anime,film,tv,manga,media}/route.ts (150-187 lines each, same pattern)
• Clients: per-medium client components with identical state machinery

Fix:

• Single (tracking)/layout.tsx with shared styles
• Dynamic (tracking)/[medium]/ route
• Consolidated /api/tracking/[medium]/ API
• Shared TrackingGridBrowser component for watched/read/played lists
• Extend existing tracking-overview.tsx shared renderer

#2.2 Content Listing Client Duplication (Codex finding)

Problem: Listing clients repeat identical state machinery:

• (content)/[type]/client.tsx
• (content)/til/client.tsx
• (content)/now/client.tsx
• (content)/scripts/client.tsx
• (content)/sequences/client.tsx

Repeated: search state, URL query sync, category/tag construction, date sorting, empty states, header fallbacks, slug banners.

Fix: Extract src/hooks/useContentListingState.ts + src/components/content/collectionShell.tsx. Route clients own only data shape and item renderer choice.

#2.3 Content Payloads in Route Folders (Codex finding)

Problem: Authored content lives inside src/app/:

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

Fix: Move to src/content/ or external content repo. Extract src/lib/til.ts and src/lib/now.ts loaders first, then move files.

#2.4 Empty Route Groups (Claude finding, confirmed by Codex)

Delete:

• (info) -- completely empty
• (media) -- completely empty

Decide:

• (updates) -- has layout.tsx + CSS but zero routes. Delete if no plans.

#2.5 Duplicate Navigation Routes (Claude finding)

• sequences/categories/page.tsx (58 lines) vs sequences/category/page.tsx (26 lines, empty placeholder) -- delete the empty one

---

#Phase 3: Monolith Splitting

#3.1 reading.tsx (1,589 lines) -- Claude finding

Contains 9+ distinct sub-components, data fetching, state management, API calls, rendering. Split into:

• reading/ directory with sub-components
• useReading and useReadingData hooks
• Server-side data fetching passed as props

#3.2 survey.tsx (1,220 lines) -- Claude finding

Form state, validation, conditional rendering, answer tracking all in one file. Split into:

• Form schema parser
• Validation logic
• Answer reducer hook (useSurvey)
• Presentation components

#3.3 api/system/utils/route.ts (762 lines) -- Claude finding

Kitchen-sink API endpoint. Split into discrete endpoints by concern.

#3.4 globals.css (~1,979 lines) -- Codex finding

Catch-all CSS file. Extract to src/app/styles/core/:

• base.css (viewport, tokens)
• 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 only.

#3.5 media-db.ts (837 lines, 91 exports) -- Both found

Split by domain once content registry exists:

• lib/db/films.ts
• lib/db/anime.ts
• lib/db/games.ts
• lib/db/reading.ts
• lib/db/tv.ts
• lib/db/music.ts

#3.6 system-db.ts (620 lines) -- Both found

Split: metadata, quotes, supporters.

#3.7 Header Client Boundary (Codex finding)

layout/header.tsx is "use client" but imported by server pages. Split into:

• Server-safe header renderer (static markup)
• Small client island for interactive parts

#3.8 PageDescription (Codex finding)

Owns too many jobs: markdown-link parsing, icon lookup, modal state, sounds, compact/expanded modal markup. Extract:

• Pure parseMarkdownLinks helper
• Shared modal body component
• Narrow client shell for open/close state

---

#Phase 4: Dead Code and Cleanup

#4.1 Dead Exports (31 functions) -- Claude finding

Module	Dead Functions
date.ts	formatRelative, formatInCentralTime, getCurrentMonthYear, getCurrentYear, isPast, isFuture, isToday, formatDateCompact, formatDateWithValidation, isValidDate
lab-db.ts	getSurveyResponses, getAllSurveyResponses, getSurveyResponseCount, getAllSurveys, upsertSurvey, syncSurveysFromFiles
doc.ts	getDocumentsUnderPath, getDocBySlug, getTopLevelDirectories
data.ts	getVerseByTypeAndSlug, getDocumentFilePath
mdx.ts	fileExists, listMdxFiles, extractHeadingsWithHierarchy
analytics-db.ts	getHistoryTimeline
canonical-url.ts	_resetCanonicalUrlCache
cookie-sign.ts	signCookie
form-parser.ts	extractFormFrontmatter
guestbook-db.ts	getGuestbookEntry
media-db.ts	getMusicPlaylists
prompts.ts	getPromptsByCategory, getPromptBySlug

#4.2 Duplicate Type Definitions -- Both found

• TilEntry in both data.ts and system-db.ts (different id field)
• NowEntry in both data.ts and system-db.ts
• Movie in media-db.ts vs film-utils.ts (snake_case vs camelCase)

Consolidate to src/lib/types/.

#4.3 Duplicate Logic -- Both found

• getMovies() defined in both media-db.ts and film-utils.ts
• URL replacement logic identical in citation.tsx and print.tsx
• Image unoptimized={image?.includes('krisyotam.com')} repeated in 7 files
• Date formatters: 14 functions, keep ~5, delete the rest

#4.4 Stale Script Paths (Codex finding)

• syncContent.js still documents public/scripts/keep (deleted)
• generateMetadata.js hardcodes PROJECT_ROOT = '/home/krisyotam/dev/krisyotam.com'
• Several scripts hardcode DB/content locations instead of using env vars

#4.5 Empty Directories -- Claude finding

Delete: components/changelog/, components/media/anime/ (if empty) Move: contribution-graph.tsx from components root to home/

---

#Phase 5: Security and Resilience

#5.1 Cookie Secret Fallback -- Claude finding

cookie-sign.ts:3 has hardcoded default 'krisyotam-cookie-secret-change-in-prod'. Should throw in production if COOKIE_SECRET not set.

#5.2 Error Boundaries -- Claude finding

Zero error.tsx files. Add to at minimum: (content), (tracking), (misc), root.

#5.3 TikZ SVG Sanitization -- Claude finding

typography/tikz.tsx renders SVG via dangerouslySetInnerHTML without DOMPurify. Low risk (server-rendered from own API) but worth hardening.

#5.4 CSRF Localhost Bypass -- Claude finding

csrf.ts allows localhost:3000 and localhost:3080 unconditionally. Gate behind NODE_ENV === 'development'.

---

#Phase 6: Scripts Relocation

#6.1 Private Scripts Under public/ (Codex finding)

Only browser-delivered scripts belong under public/. Current structure puts dev tooling, DB mutators, importers, prose/verse tools all under public/scripts/.

Target structure:

public/scripts/           -- browser-delivered only
  footnotes.js
  sidenotes.js
  prod/                   -- production browser scripts

scripts/                  -- NOT web-served
  dev/
  doc/
  prose/
  verse/
  auth/
  lib/                    -- shared helpers (paths.mjs, contentRegistry.mjs)

Note: This conflicts with current project memory that says script subdirectories are fixed under public/scripts/{auth,dev,doc,prod,prose,verse}. Update architecture docs and memory when migration starts.

---

#Phase 7: CSS and Themes

#7.1 Theme Token Duplication (Codex finding)

src/app/styles/themes/default.css has duplicate no-JS dark-mode and .dark definitions, repeated pastel token blocks. Reduce declarations while preserving fallback behavior.

#7.2 !important Overuse (Claude finding)

globals.css code block styles (lines 32-67) use excessive !important. Refactor cascade to avoid.

---

#Phase 8: Testing

#8.1 No Test Coverage (Both found)

Vitest config exists but no test files. Priority tests to write:

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

---

#Work Division

#Claude Batch 1: Content Registry + Route Consolidation

• Create src/config/contentRegistry.ts
• Convert read-only consumers: seo.ts, content.ts, sitemap.ts, api/content/search
• Consolidate tracking routes (layouts, pages, APIs, clients)
• Delete 31 dead exports
• Delete empty route groups and directories

#Codex Batch 1: Data Integrity + Path Safety

• Create scripts/lib/paths.mjs
• Fix syncDocs.js, syncNotebooks.js, blogActivity.js, magic-urls.js paths
• Delete zero-byte public/data/*.db
• Migrate reference-db.ts to withDb()
• Fix generateMetadata.js hardcoded PROJECT_ROOT
• Add DB path tests

#Claude Batch 2: Monolith Splitting

• Split reading.tsx into sub-components + hooks
• Split survey.tsx into form logic + presentation
• Split api/system/utils into discrete endpoints
• Extract globals.css into styles/core/* modules
• Split header client boundary

#Codex Batch 2: Canonical URLs + Listing Primitives

• Normalize canonical URL generation, require item.url
• Update table.tsx, directory.tsx, mediaCard.tsx to use passed URLs
• Extract useContentListingState hook
• Extract collectionShell.tsx
• Move TIL/Now content out of route folders

#Shared Later Batches

• Script migration out of public/ (after path helper + docs update)
• Split media-db.ts and system-db.ts by domain (after registry)
• Error boundaries
• Security fixes
• Theme token dedup
• Test coverage

---

#Execution Order

1. Content registry (unblocks everything)
2. DB root drift + path helper (unblocks script fixes)
3. Canonical URL normalization (unblocks component cleanup)
4. Tracking route consolidation (biggest line-count reduction)
5. Monolith splitting (reading, survey, utils, globals)
6. Dead code deletion (31 exports, duplicate types, empty dirs)
7. Listing/content client extraction
8. TIL/Now loader extraction + content file moves
9. Header/PageDescription client boundary fixes
10. Script relocation out of public/
11. Security fixes (cookie, error boundaries, CSRF, TikZ)
12. Split broad DB modules by domain
13. CSS/theme cleanup
14. Test coverage

---

#Files Index (Conflict-Prone)

These files will be touched by both agents at different phases. Coordinate order:

File	Phase	Owner
src/lib/seo.ts	1.1	Claude first, then Codex
src/lib/content.ts	1.1	Claude first, then Codex
src/app/sitemap.ts	1.1	Claude
src/lib/canonical-url.ts	1.3	Codex
next.config.mjs	1.1	Claude (registry), Codex (URLs)
src/app/globals.css	3.4	Claude
public/scripts/dev/git.js	1.2	Codex
public/scripts/dev/syncContent.js	1.1, 1.2	Codex
src/app/(content)/[type]/config.ts	1.1	Claude
src/lib/data.ts	4.1, 4.2	Claude (dead code), Codex (types)