# S01 Research — Browser Agent Site Audit

## Summary

Chrysopedia is a mature single-page application (React 18 + react-router-dom v6, Vite build, no UI library) with a FastAPI backend (Python 3.x, SQLAlchemy async, Celery worker, PostgreSQL 16, Qdrant, Redis, Ollama). The site is live at `http://ub01:8096` with 83 technique pages and 26 creators. The codebase is well-structured but monolithic — one CSS file (5820 lines, 589 unique classes), one API client module (public-client.ts, ~600 lines), one models.py (13 SQLAlchemy models), one schemas.py. No CSS modules, no preprocessors, no component library.

## Recommendation

This audit is straightforward data collection — no new technology, no ambiguous scope. The work is reading source code systematically and producing a structured report. The output is a markdown Site Audit Report covering: route map, component inventory, API surface map, CSS architecture analysis, and integration recommendations for Phase 2.

## Implementation Landscape

### Route Map (12 frontend routes)

| Route | Page Component | Type |
|---|---|---|
| `/` | Home | Public |
| `/search` | SearchResults | Public |
| `/techniques/:slug` | TechniquePage | Public |
| `/creators` | CreatorsBrowse | Public |
| `/creators/:slug` | CreatorDetail | Public |
| `/topics` | TopicsBrowse | Public |
| `/topics/:category/:subtopic` | SubTopicPage | Public |
| `/about` | About | Public |
| `/admin/reports` | AdminReports | Admin |
| `/admin/pipeline` | AdminPipeline | Admin |
| `/admin/techniques` | AdminTechniquePages | Admin |
| `*` (fallback) | → Redirect `/` | — |

### Component Inventory (14 shared components + 10 pages)

**Pages:** Home, SearchResults, TechniquePage, CreatorsBrowse, CreatorDetail, TopicsBrowse, SubTopicPage, About, AdminReports, AdminPipeline, AdminTechniquePages

**Shared Components:** SearchAutocomplete, AdminDropdown, AppFooter, TableOfContents, SortDropdown, TagList, CategoryIcons, CreatorAvatar, CopyLinkButton, SocialIcons, ReportIssueModal

**Hooks:** useCountUp, useSortPreference, useDocumentTitle

**Utils:** citations.tsx, catSlug.ts

### API Surface Map (43 endpoints)

**Public (10 endpoints):**
- `GET /health` — health check
- `GET /api/v1/stats` — site stats
- `GET /api/v1/search` — search (semantic + keyword fallback)
- `GET /api/v1/search/suggestions` — autocomplete suggestions
- `GET /api/v1/search/popular` — popular searches
- `GET /api/v1/techniques` — paginated technique list
- `GET /api/v1/techniques/random` — random technique redirect
- `GET /api/v1/techniques/{slug}` — technique detail
- `GET /api/v1/techniques/{slug}/versions` — version history
- `GET /api/v1/techniques/{slug}/versions/{version_number}` — specific version

**Browse (5 endpoints):**
- `GET /api/v1/creators` — creator list (sort, genre filter)
- `GET /api/v1/creators/{slug}` — creator detail
- `GET /api/v1/topics` — topic hierarchy
- `GET /api/v1/topics/{category_slug}/{subtopic_slug}` — subtopic techniques
- `GET /api/v1/topics/{category_slug}` — category techniques

**Reports (3 endpoints):**
- `POST /api/v1/reports` — submit content report
- `GET /api/v1/admin/reports` — list reports
- `PATCH /api/v1/admin/reports/{report_id}` — update report

**Pipeline Admin (20+ endpoints):**
- Videos list, trigger, clean-retrigger, revoke, rerun-stage
- Events, runs, chunking inspector, embed-status
- Debug mode get/set, token summary, stale pages
- Bulk resynthesize, wipe all output, optimize prompt
- Reindex all, worker status, creator profile update, avatar fetch

**Ingest:** `POST /api/v1/ingest` — transcript upload
**Videos:** `GET /api/v1/videos` — source video list

### CSS Architecture

- **Single file:** `frontend/src/App.css` (5820 lines)
- **Naming:** BEM convention (`block__element--modifier`)
- **Theming:** 77 CSS custom properties in `:root` (D017), dark theme only, cyan accent (#22d3ee)
- **Breakpoints:** 4 distinct values — 480px, 600px, 640px, 768px (10 total `@media` blocks scattered)
- **No CSS modules, no preprocessor, no Tailwind**
- **Font stack:** System fonts (no custom fonts loaded)

### Data Model (13 SQLAlchemy models)

Creator, SourceVideo, TranscriptSegment, KeyMoment, TechniquePage, RelatedTechniqueLink, TechniquePageVersion, Tag, TechniquePageVideo, ContentReport, SearchLog, PipelineRun, PipelineEvent

### Infrastructure Stack

| Service | Image | Container Name |
|---|---|---|
| PostgreSQL 16 | postgres:16-alpine | chrysopedia-db |
| Redis 7 | redis:7-alpine | chrysopedia-redis |
| Qdrant 1.13.2 | qdrant/qdrant:v1.13.2 | chrysopedia-qdrant |
| Ollama | ollama/ollama:latest | chrysopedia-ollama |
| API (FastAPI) | custom (Dockerfile.api) | chrysopedia-api |
| Worker (Celery) | custom (Dockerfile.api) | chrysopedia-worker |
| Watcher | custom (Dockerfile.api) | chrysopedia-watcher |
| Web (nginx) | custom (Dockerfile.web) | chrysopedia-web-8096 |

### Frontend Architecture Notes

- **Zero external UI dependencies** — React 18, react-router-dom, TypeScript, Vite. That's it.
- **API client:** Single `public-client.ts` module with typed `request<T>` helper, relative `/api/v1` base URL (nginx proxies to API container)
- **State management:** Local component state only (useState/useEffect). No Redux, Zustand, or context providers.
- **Build:** Vite with react plugin, injects `__APP_VERSION__`, `__BUILD_DATE__`, `__GIT_COMMIT__` at build time
- **Dev proxy:** Vite proxies `/api` to `localhost:8001` for local dev

### Key Integration Points for Phase 2

1. **New routes** will be added to the `<Routes>` block in App.tsx. The SPA fallback in nginx.conf handles all paths.
2. **New API endpoints** follow the router pattern: create `backend/routers/foo.py` with `APIRouter(prefix="/foo", tags=["foo"])`, register in `backend/main.py` with `app.include_router(foo.router, prefix="/api/v1")`.
3. **New frontend API calls** go in `public-client.ts` using the `request<T>` helper. TypeScript interfaces defined in the same file.
4. **CSS additions** append to `App.css` using BEM naming. Use existing CSS custom properties for colors. Phase 2 should consider splitting this file — at 5820 lines it's becoming unwieldy.
5. **New models** go in `backend/models.py`, schemas in `backend/schemas.py`. No Alembic migrations directory exists — schema changes require manual DDL or adding Alembic.
6. **The monolithic CSS file is the biggest Phase 2 risk** — 5820 lines with no scoping means any selector conflict affects the whole app. Consider CSS modules or at minimum splitting by page/feature area.

### Natural Task Seams

1. **Route map + component inventory** — read App.tsx + all page/component files, document props and dependencies
2. **API surface map** — read all routers, document request/response shapes, auth requirements, query params
3. **CSS architecture analysis** — analyze App.css structure, naming patterns, breakpoint consistency, dead CSS detection
4. **Integration recommendations** — synthesize findings into actionable Phase 2 guidelines
5. **Assemble final Site Audit Report** — single deliverable markdown document

### What to Build or Prove First

The riskiest part is CSS analysis — understanding which styles are actually used, which are dead, and how breakpoints are applied inconsistently (480px vs 600px vs 640px vs 768px — four different mobile breakpoints). The route/API maps are mechanical extraction from source code.

### How to Verify

- The Site Audit Report is a documentation artifact. Verify by checking:
  - All 12 routes documented with correct components
  - All 43+ API endpoints documented with methods, paths, and purpose
  - CSS custom property count matches (77)
  - Component inventory includes all files in `frontend/src/components/` and `frontend/src/pages/`
  - Integration recommendations address the key risks (monolithic CSS, no auth, no Alembic)
