# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Directives

- **Zero CDN dependencies.** No external JS, CSS, fonts, images, or `cdn.*` URLs. `npm run build` fails on any CDN reference via `scripts/check-no-cdn.mjs`.
- **Persian/RTL first.** All UI copy is Persian. Layouts assume `direction: rtl`; use logical CSS properties, not left/right.
- **Frontend uses APIs only.** Never call the database from frontend code. All persistence goes through `/api/v1/*` at the backend. Frontend API clients may pass unversioned `/api/*` paths because `src/lib/api.js` rewrites them to `/api/v1/*`. `teknav-data.js` and `teknav-store.js` are seed/reference data — never use them as admin-panel fallbacks.
- **No mock admin data.** Admin/writer/reviewer/dashboard/media views must use real backend APIs and show empty/error states when data is missing.
- **Production is native Linux/systemd + nginx.** No Docker unless explicitly asked. See `DEPLOY.md`.
- **Protect credentials.** `ACCOUNTS.md` is gitignored and nginx-blocked. Never move it into `public/` or `dist/`. Seed credentials are in `backend/prisma/credentials.json`.
- **Port and registry are fixed.** Vite dev/preview → port `3009`; npm registry → `https://npm.devneeds.ir/`.
- **Reuse shared styling.** Use `src/styles/global.css` keyframes/utilities — do not redefine animation primitives.
- **Phase 15 is current.** Keep `ARCH.md`, `AGENTS.md`, `DEPLOY.md`, and `SECURITY.md` aligned when schema, SEO, trust, retention, or monetization flows change. Phase 14 Linux validation (pgvector + LMS) is still pending before full production go-live.
- **Production hardening.** Run `npm run preflight:prod` before deploy; run `TEST_REQUIRE_SERVER=1 npm test` in `backend/` against a live backend to enforce endpoint contracts.

## Commands

**Frontend** (repo root):
```bash
npm run dev              # Vite dev server → port 3009, proxies /api → localhost:3010
npm run build            # Full pipeline (see Build Pipeline Order)
npm run preview          # Preview dist/ on port 4173
npm run preflight:prod   # Static pre-deploy audit
npm run seo:sitemap      # Regenerate sitemap.xml, robots.txt, feed.xml
npm run og:images        # Generate OG images into public/images/og/ (Linux only)
npm run check:seo        # Audit Persian articles for indexability gaps
npm run smoke:prod       # Smoke-test all public endpoints
```

**Backend** (`cd backend` first):
```bash
npm run dev              # tsx watch → port 3010
npm run build            # TypeScript compile
npm run prisma:generate  # Regenerate Prisma client after schema changes
npm run prisma:apply     # Apply schema (migrations if present, else db push)
npm run seed             # Seed PostgreSQL + Persian FTS
npm run publish:due      # Publish scheduled articles + fan out notifications
npm test                 # Skips endpoint tests when no backend running
TEST_REQUIRE_SERVER=1 npm test  # Strict contract tests against a live backend
```

**Startup order:** PostgreSQL + Redis → `cd backend && npm run dev` → `npm run dev`

**Schema change workflow:** edit schema → `npm run prisma:generate --prefix backend` → `npm run prisma:apply --prefix backend` → backend build.

**Article data change workflow:** edit `teknav-data.js` → `npm run check:seo` → `npm run seo:sitemap` → `npm run build`.

## Build Pipeline Order

```
seo:sitemap → og:images → vite build → check-no-cdn → check-responsive
  → generate-article-pages → generate-web-stories → generate-comparison-pages
  → generate-company-pages → generate-en-page → generate-author-pages
  → generate-semantic-pages → compress-dist
```

All `generate-*` scripts produce static HTML that nginx serves directly — never manually edit files under `dist/`. `generate-article-pages` must run after `vite build` (needs `dist/index.html` as template) and before `compress-dist` (so `.gz`/`.br` pairs are created). Phase 15 scripts output: `dist/stories/{slug}/` (web stories), `dist/compare/{slug}/` (comparisons), `dist/directory/{slug}/` (company directory).

## SEO Invariants

- **No `hreflang="en"`.** `?lang=en` is a UI preference only; canonical always points to the clean URL.
- **No placeholder verification codes.** Never commit `INSERT_GOOGLE_VERIFICATION_CODE` or similar strings.
- **Static article pages** under `dist/article/{slug}/index.html` are build-time generated — do not edit manually.
- **Sitemap lastmod must not be future-dated.** `capDate()` in `generate-seo.mjs` enforces this.
- **Organization schema:** `['Organization', 'NewsMediaOrganization']` — required for Google News.
- **Article schema:** `['NewsArticle', 'TechArticle']` — required for Google Article rich results.
- **Run `npm run check:seo`** after any article metadata or content change.
- **Proven content formula** (article `ai-data-centric-2026` ranked #1 on Google, above Wikipedia): `<p class="lead">` opening, numbered `<h2>` sections, `<strong>` entity highlighting, bilingual terminology (Persian + English inline), technical formulas/data inline, `factCheckedAt` timestamp, 8+ sections / ~3000 words.

## Architecture

**Frontend** — Vite 5 + React 18 ES modules, automatic JSX runtime (no `import React` needed). Route dispatch in `teknav-app.jsx`; pages in `teknav-home.jsx`, `teknav-articles.jsx`, `teknav-pages.jsx`, `teknav-admin.jsx`, `teknav-auth.jsx`, `teknav-profile.jsx`. Providers, header, footer, shared UI in `teknav-ui.jsx`. Styles/fonts/keyframes in `src/styles/global.css`.

**Backend** — Fastify 4 + Prisma 5 + PostgreSQL 16 (+ `pgvector` for semantic search) + Redis 7. Route modules in `backend/src/routes/`. Global error handler registered early in `backend/src/server.ts` — maps `FST_ERR_VALIDATION` to `'invalid_input'` uniformly. Config validated by Zod in `backend/src/config.ts`.

**Data layer** — `teknav-data.js` holds all articles (`art1`–`art35`), authors, categories, topic hub metadata, glossary reference data. Article content beyond art10 lives in `article-contents-{N}.js` files. `src/lib/content-api.js` merges API results over this local fallback (API wins). `teknav-store.js` handles client-side localStorage caching.

**Auth** — Argon2id passwords (m=19MiB, t=2, p=1), Redis sessions (`tek_sid`, 14-day sliding TTL), CSRF double-submit cookie (`tek_csrf`). Login by email or `@username`. Google/GitHub OAuth (authorization-code, state in Redis). SMS 2FA via Kavenegar OTP (`tek_2fa` ticket).

**Role-based access:**

| Role | Access |
|---|---|
| `reader` | View, save, react, manage own profile |
| `reviewer` | + Article review queue |
| `writer` | + Create/edit own articles |
| `editor` | + Edit any article, manage categories/tags |
| `admin` | + Delete articles, manage users |

**Real-time** — SSE at `/api/v1/auth/notifications/stream` (reader) and `/api/v1/admin/stream` (admin live signals). Redis pub/sub is the bus (`backend/src/lib/realtime.ts`).

**Web push** — RFC 8030/VAPID via `web-push`. `PushSubscription` table stores endpoint per user; `userId` nullable for guest topic subscriptions. `sendPushToUser()` checks `NotificationPreference` before delivering. VAPID keys in `/etc/teknav/backend.env` — missing keys make push a silent no-op, all other features unaffected.

**Storage** — `LocalStorageAdapter` active by default (writes to `UPLOAD_DIR`). S3 migration: set `STORAGE_BACKEND=s3` and wire the stub in `backend/src/lib/storage.ts`.

## Phase 14 — Farsi Knowledge & Ecosystem (current, Linux validation pending)

Requires `CREATE EXTENSION vector;` (PostgreSQL superuser) and `prisma:apply` before going live:

| Subsystem | Models | Key endpoints |
|---|---|---|
| **Semantic Search / RAG** | `ArticleEmbedding` | `POST /api/v1/search/semantic`, `GET /api/v1/rag/:slug` |
| **LMS** | `LearningPath`, `LearningModule`, `Quiz`, `UserCertification` | `POST /api/v1/lms/quiz/:quizId/submit`, `GET /api/v1/lms/me` — auto-cert at ≥80 |
| **Tech Directory** | `CompanyProfile`, `CompanyClaim` | Authenticated claim endpoint |
| **Wiki/Glossary Proposals** | `WikiProposal`, `GlossaryProposal` | `POST /api/v1/wiki/proposals`, `PATCH /api/v1/admin/wiki/proposals/:id` |

`link-engine.ts` uses `cheerio` to auto-inject `<a href="/glossary/:slug">` anchors into newly published articles.

## Key Files

| Path | Purpose |
|---|---|
| `teknav-app.jsx` | Root route dispatch |
| `teknav-ui.jsx` | Providers, header, footer, `PushNotificationPrompt` |
| `teknav-home.jsx` | Home page — hero, featured, latest, personalized feed, streaks |
| `teknav-articles.jsx` | Article detail — comments, TOC, reactions, Q&A, series nav |
| `teknav-pages.jsx` | Topic hubs, glossary, tag pages, author pages, series, newsletter archive, jobs, courses, directory |
| `teknav-admin.jsx` | CMS, `ArticleEditor` (role-aware, `RevisionDrawer`, presence chips), LMS panel, directory panel |
| `teknav-auth.jsx` | Login, signup, OAuth, 2FA, forgot-password |
| `teknav-profile.jsx` | `/profile/@username`, push toggle, notification preferences, history |
| `src/lib/api.js` | Fetch wrapper with credentials + CSRF |
| `src/lib/content-api.js` | Public content client — merges API over local fallback |
| `src/lib/admin-api.js` | Admin/CMS API client |
| `src/lib/engagement-api.js` | Comments, history, notifications, follows, streaks, badges, revisions, presence |
| `src/lib/seo.jsx` | Page-level meta tags and JSON-LD for all page types |
| `backend/src/server.ts` | Fastify bootstrap — error handler registered before all plugins |
| `backend/src/routes/admin.ts` | Role-gated article CRUD, publish quality gates, analytics, review, newsletter, series |
| `backend/src/routes/auth.ts` | Local auth, OAuth, 2FA, session, `/api/v1/auth/me` |
| `backend/src/routes/comments.ts` | Comments, replies, likes, upvotes, flags, bulk mod. Returns `{items:[],total:0}` (not 404) for unknown slugs. |
| `backend/src/routes/notifications.ts` | Notification list, SSE stream, VAPID key, push subscribe/unsubscribe |
| `backend/src/routes/revisions.ts` | Article revision list/get/restore (admin/editor only) |
| `backend/src/routes/monetization.ts` | Jobs, courses, Zarinpal subscribe/callback/status |
| `backend/src/routes/errors.ts` | `POST /api/v1/errors` → `ClientError` table; `GET /api/v1/admin/errors` |
| `backend/src/lib/push.ts` | VAPID, `sendPushToUser()` (checks prefs), `sendGuestPushByTopic()`, 410 cleanup |
| `backend/src/lib/storage.ts` | `StorageAdapter` — `LocalStorageAdapter` default, `S3StorageAdapter` stub |
| `backend/src/lib/realtime.ts` | Redis pub/sub, SSE helpers, visitor counter |
| `backend/prisma/schema.prisma` | Single source of truth for all models |
| `backend/prisma/seed.ts` | Seed data, staff users, Persian FTS setup |
| `scripts/production-readiness.mjs` | `npm run preflight:prod` static pre-deploy checklist |
| `.env.prod.example` | Production env template → copy to `/etc/teknav/backend.env` |
| `ACCOUNTS.md` | Operator credential sheet — gitignored, nginx-blocked |
| `deploy/systemd/` | Production systemd units and timers |
| `nginx/nginx.conf.example` | Production nginx template |

## Production Notes

- nginx must serve pre-rendered semantic folders (`/category/`, `/tag/`, `/glossary/`, `/topics/`, `/series/`, `/author/`, `/profile/`) with `gzip_static on; brotli_static on;` — avoids redirect loops and sub_filter cost.
- Never copy Windows-generated Prisma engine binaries (`query_engine*.node`) or local `node_modules` to the Linux server.
- Zarinpal requires `ZARINPAL_MERCHANT_ID` in env; until set, subscribe returns `payment_unavailable`. Use `ZARINPAL_SANDBOX=1` for testing.
- Phase 12 requires `cd backend && npm install web-push` and VAPID key generation once on Linux.
- Phase 14 requires `CREATE EXTENSION vector;` as PostgreSQL superuser before `prisma:apply`.
- After first production login, rotate writer-admin passwords via admin UI, then remove `resetPasswordOnSeed` from `backend/prisma/credentials.json`.

## Large Codebase Analysis (Gemini CLI)

When multiple large files exceed context, use `gemini -p` with `@` path syntax:

```bash
gemini -p "@src/ @backend/src/ List all API endpoints and their auth requirements"
gemini -p "@teknav-admin.jsx @backend/src/routes/admin.ts Trace the article publish flow end-to-end"
gemini --all_files -p "List all Prisma models and their relations"
```

Paths are relative to where you run `gemini`. Use for cross-file architecture questions or verifying feature coverage across many files.

## Memory

See `MEMORY.md` for full stack context and key paths. See `ARCH.md` for the active roadmap and Phase 14 Linux validation checklist. See `DEPLOY.md` for the full production runbook. See `SECURITY.md` for the pre-deploy security checklist and nginx/Fastify hardening details. See `PHASES.md` for completed phase history. See `PHASE16.md` for the planned English `/en/` subdirectory (blocked on LTR layout pass — not started).

Quick reference:
- **Stack:** Vite 5 + React 18 / Fastify 4 + Prisma 5 / PostgreSQL 16 + pgvector + Redis 7
- **Current phase:** 15 (implemented; Phase 14 Linux validation pending)
- **Writers:** آرسام صباغ (`arsam-sabbagh`), سیداحمدرضا محجوب (`ahmadreza-mahjoub`), رادمان قلیچی (`radman-ghelichi`)
- **Constraints:** Zero CDN · Persian-first RTL · native Linux/systemd · no mock admin data