teknav-bak/app/AGENTS.md

# Repository Guidelines

## Project Structure

Teknav is a Persian RTL React SPA (`teknav.ir`) with a Fastify/PostgreSQL/Redis backend. The Vite entry is `index.html` → `src/main.jsx`. Global styles, fonts, and animation primitives live in `src/styles/global.css`. Main frontend modules at repo root: `teknav-app.jsx`, `teknav-ui.jsx`, `teknav-home.jsx`, `teknav-articles.jsx`, `teknav-pages.jsx`, `teknav-auth.jsx`, `teknav-admin.jsx`, `teknav-profile.jsx`, `teknav-data.js`, `teknav-store.js`. Runtime assets in `public/`; font archives in `Fonts/`. Backend in `backend/` with Fastify sources in `backend/src/` and Prisma in `backend/prisma/`.

## Dev Commands

**Frontend** (repo root):
- `npm run dev` — Vite dev server on **port 3009**, proxies `/api` → `http://localhost:3010`. Backend must be running first.
- `npm run build` — runs SEO artifact generation, OG image generation, Vite build, CDN/responsive checks, static article page generation, and gzip/brotli compression.
- `npm run preview` — preview built `dist/` on **port 4173**.
- `npm run preflight:prod` — static production readiness audit for env templates, nginx SSE/credential protection, required scripts, generated-engine safety, and migration/test posture.
- `npm run seo:sitemap` — regenerate `public/sitemap.xml`, `public/robots.txt`, `public/feed.xml` from `teknav-data.js`.
- `npm run og:images` — generate local Open Graph images into `public/images/og/` from article metadata. Run on Linux after dependencies are installed.
- `npm run check:seo` — audit current Persian indexable articles for canonical, meta, OG image, review date, heading structure, entity coverage, and body-depth warnings.

**Backend** (`backend/`):
- `npm run dev` — `tsx watch src/server.ts` on **port 3010** (env `PORT`, default 3010).
- `npm run build` — `tsc` type-check and compile.
- `npm run prisma:generate` — regenerate Prisma client after schema changes.
- `npm run prisma:apply` — apply schema (migrations if present, else `db push --skip-generate`).
- `npm run seed` — seed Postgres via `tsx prisma/seed.ts`.
- `npm run publish:due` — publish scheduled articles (also runs via systemd timer in prod).

**Dev startup order**: PostgreSQL + Redis → `cd backend && npm run dev` → `npm run dev`.

Backend tests are `node:test` smoke/contract checks. `cd backend && npm test` auto-skips endpoint assertions when no backend is reachable; use `TEST_REQUIRE_SERVER=1 npm test` against a running backend for strict validation.

Validate with `npm run preflight:prod`, `npm run check:seo`, `npm run build` (frontend), `cd backend && npm run build`, and strict backend tests against a running API.

## Hard Constraints

- **Zero CDN.** No external JS, CSS, fonts, images. `npm run build` rejects any CDN URL in `dist/`.
- **Persian-first RTL.** All UI copy in Persian. Use logical CSS properties over `left`/`right`.
- **ES modules, named exports.** JSX uses Vite automatic runtime — import hooks directly, not `React`.
- **No mock admin data.** Admin/panel views (`teknav-admin.jsx`) must use backend API only (`src/lib/admin-api.js`). `teknav-data.js` and `teknav-store.js` are seed/reference data, not UI fallbacks.
- **Production is native Linux/systemd + nginx.** No Docker. Deploy docs in `DEPLOY.md`.
- **`ACCOUNTS.md`** is gitignored and nginx-blocked. Never commit or expose it. Seed credentials are in `backend/prisma/credentials.json`.

## Ports & Proxy

| Service | Dev Port | Prod |
|---|---|---|
| Frontend (Vite) | 3009 | nginx →
`dist/` |
| Preview (built) | 4173 | — |
| Backend (Fastify) | 3010 | nginx proxy |

Vite dev proxies `/api` to `http://localhost:3010` for same-origin cookies. Production nginx handles path-based routing. Backend health: `GET /api/v1/health`; strict readiness: `GET /api/v1/ready` returns 503 if PostgreSQL or Redis is unavailable. Frontend clients may call unversioned `/api/*`; `src/lib/api.js` rewrites those calls to `/api/v1/*`.

## Auth & Accounts

Argon2id hashing, Redis sessions (`tek_sid`), CSRF double-submit cookie (`tek_csrf`). Login by **email** or **`@username`**. Every seeded account must have a URL-safe username. Writer-admin accounts (آرسام صباغ, رادمان قلیچی, سیداحمدرضا محجوب) in `backend/prisma/credentials.json` use `resetPasswordOnSeed: true` — remove after production password rotation.

## Schema & Seed Workflow

When changing `backend/prisma/schema.prisma`: run `prisma:generate` before backend build/type-check, then `prisma:apply`.
For production/Linux deployment, run `cd backend && npm ci && npm run prisma:generate && npm run prisma:apply` on the Linux host after uploading code. Never copy Windows-generated Prisma engine files (`backend/query_engine*.node`, `backend/schema-engine*`) or local `node_modules` into production.
When changing `teknav-data.js` slugs/dates: run `npm run check:seo` and `npm run seo:sitemap`.
When changing article Open Graph metadata: run `npm run og:images`, `npm run check:seo`, and `npm run seo:sitemap` on Linux.
When changing seed logic: run `cd backend && npm run seed` against running PostgreSQL/Redis.

## Phase 9 Files

Phase 9 adds real publication features across frontend and backend:

- `backend/src/routes/public.ts` — related articles, public article SEO fields, public series, newsletter unsubscribe, saved-article default reading-list sync.
- `backend/src/routes/comments.ts` — real comment like/unlike API, like counts, and liked-by-me flags.
- `backend/src/routes/lists.ts` — authenticated reading-list CRUD, add/remove, and reorder.
- `backend/src/routes/analytics.ts` — authenticated writer/editor article analytics.
- `backend/src/routes/admin.ts` — admin analytics, review workflow, newsletter campaigns, article series, and article SEO field writes.
- `backend/prisma/schema.prisma` — `ArticleViewLog`, `CommentLike`, `NewsletterCampaign`, `ArticleSeries`, `ArticleReview`, `ReadingList`, and new article SEO fields.
- `teknav-admin.jsx` — API-backed analytics, review, newsletter, and series panels.
- `teknav-articles.jsx` — comment likes and API-backed related articles.
- `teknav-pages.jsx` / `teknav-app.jsx` — public `/series/:slug` route.
- `scripts/generate-seo.mjs` — canonical/dateModified/metaDescription sitemap and full-content RSS.
- `scripts/generate-og-images.mjs` — local OG image generation.

## Phase 10 Files

Phase 10 expands SEO growth, trust, and publication readiness:

- `PHASE10.md` — active Phase 10 checklist and Linux validation status.
- `teknav-data.js` — topic hub metadata, glossary term data, and SEO seed/reference content.
- `teknav-pages.jsx` — topic hubs, glossary pages, author pages, tag pages, series pages, and newsletter archive pages.
- `src/lib/seo.jsx` — Article, CollectionPage, ProfilePage, DefinedTerm, FAQPage, ItemList, BreadcrumbList, canonical, robots, and Google Discover meta handling.
- `scripts/generate-seo.mjs` — sitemap, robots, global feed, topic feeds, author feeds, and glossary URL generation.
- `teknav-articles.jsx` — public article detail, table of contents, Discover hero image, correction notices, verified author badges, comparison table styles, comments, sharing, and engagement tracking.
- `teknav-admin.jsx` — admin/writer editor, Phase 10 quality metadata, comparison article template, correction submission, verified author management, role dashboards, SEO/analytics panels.
- `teknav-auth.jsx` / `teknav-ui.jsx` — email or `@username` login, Google/GitHub OAuth entry points, and SMS 2FA login completion.
- `teknav-profile.jsx` — profile editing, phone verification, SMS 2FA toggle, public profile trust badges, reading history, and follows.
- `public/manifest.json` / `public/service-worker.js` / `index.html` — PWA manifest, service worker registration, article offline cache, and installability.
- `backend/src/routes/monetization.ts` — job board API, job submissions, and course listing API.
- `backend/src/routes/errors.ts` — first-party client error capture for self-hosted/error-tracking workflows.
- `backend/tests/phase10-smoke.test.mjs` — node:test smoke suite for auth rejection, public article/comments, optional authenticated comment, and optional publish workflow checks.
- `backend/src/routes/auth.ts` — local auth, OAuth callbacks, OTP-backed 2FA, session creation, and current-user API.
- `backend/src/routes/profile.ts` — public profile API, profile edits, verified expert fields for writer profiles, and 2FA-enabled account payloads.
- `backend/src/routes/admin.ts` — article SEO/quality writes, approval workflow, analytics, newsletter, series, author verification, and article corrections.
- `backend/src/routes/comments.ts` — comment/reply APIs, likes, upvotes, flags, best-comment sorting, and bulk moderation.
- `backend/src/routes/public.ts` — public articles/categories/authors/series/newsletter with SEO fields, verified expert fields, and correction notices.
- `backend/prisma/schema.prisma` — Phase 10 persistence including analytics events, topic follows, trust fields, verified experts, 2FA flags, article corrections, sponsored articles, premium memberships/articles, job listings, and courses.

## Phase 15 Files

Phase 15 adds viewership and top-of-funnel scaling features:

- `scripts/generate-web-stories.mjs` — CSS scroll-snap story generator; outputs `dist/stories/{slug}/index.html`; OG + Twitter Card meta, keyboard navigation.
- `scripts/generate-comparison-pages.mjs` — comparison static HTML with ItemList + FAQPage + BreadcrumbList JSON-LD.
- `scripts/generate-company-pages.mjs` — company directory static HTML with Organization JSON-LD.
- `src/components/QuoteSharer.jsx` — Selection API + Canvas 1080×1080 branded quote card; share/copy/download; analytics tracking.
- `embed.html` — second Vite rollup entry for widget iframes.
- `src/embed.jsx` — widget bootstrapper routing by URL path.
- `src/widgets/GlossaryWidget.jsx` / `ArticleCardWidget.jsx` / `CompanyWidget.jsx` — embeddable cards with dark mode and postMessage resize.
- `public/embed-loader.js` — third-party snippet that injects sandboxed `<iframe>`.
- `teknav-data.js` — now exports `comparisons` (10 entries) and `companies` (10 entries).
- `teknav-pages.jsx` — adds `ComparisonPage` (with localStorage vote widget), `ComparisonsListPage`, `DirectoryListPage`, `CompanyProfilePage`, `StoriesListPage`.
- `teknav-app.jsx` — routes: `/compare`, `/compare/:slug`, `/stories`, `/directory`, `/directory/:slug`.
- `backend/src/routes/directory.ts` — adds `GET /api/v1/directory/companies` and `GET /api/v1/directory/companies/:slug`.
- `nginx/nginx.conf.example` — `/embed/` location with `frame-ancestors *` CSP.
- `vite.config.js` — `rollupOptions.input: { main: 'index.html', embed: 'embed.html' }`.

Build pipeline (in `package.json`): `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`.

## Key Files

| Path | Purpose |
|---|---|
| `src/main.jsx` | Vite entry, mounts app, dismisses splash loader |
| `src/styles/global.css` | fonts, reset, keyframes, shared utilities |
| `teknav-app.jsx` | root route dispatch |
| `teknav-ui.jsx` | providers, header/footer, shared UI |
| `teknav-admin.jsx` | CMS UI, article editor, media library, dashboard |
| `src/lib/api.js` | fetch wrapper with credentials and CSRF |
| `src/lib/content-api.js` | public content API client |
| `src/lib/admin-api.js` | admin API client |
| `src/lib/engagement-api.js` | comments, history, notifications, follows client |
| `src/components/QuoteSharer.jsx` | Selection API + Canvas quote card sharer |
| `src/embed.jsx` | Widget iframe bootstrapper (second Vite entry) |
| `src/widgets/` | GlossaryWidget, ArticleCardWidget, CompanyWidget |
| `public/embed-loader.js` | Third-party `<script>` snippet for embedding widgets |
| `backend/src/lib/realtime.ts` | Redis pub/sub, SSE, visitor counter helpers |
| `backend/src/routes/admin.ts` | admin API routes |
| `backend/src/routes/auth.ts` | login/logout API |
| `backend/src/routes/public.ts` | public content endpoints |
| `backend/src/routes/directory.ts` | public + authenticated company directory endpoints under `/api/v1/directory/companies` |
| `backend/src/routes/comments.ts` | article comments, flags, moderation API |
| `backend/src/routes/history.ts` | reading history API |
| `backend/src/routes/notifications.ts` | notification list and SSE stream |
| `backend/src/routes/follows.ts` | writer follow API |
| `backend/src/routes/admin-stream.ts` | admin SSE stream |
| `backend/prisma/schema.prisma` | Prisma schema |
| `backend/prisma/seed.ts` | seed data, Persian FTS setup |
| `backend/src/config.ts` | env/config with Zod validation |

## Reference Docs

- `CLAUDE.md` — directives and quick reference
- `ARCH.md` — roadmap and current work status
- `MEMORY.md` — durable project context
- `DEPLOY.md` — production deployment runbook
- `SECURITY.md` — security practices
- `PHASES.md` — completed phase history


 # Using Gemini CLI for Large Codebase Analysis

  When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive
  context window. Use `gemini -p` to leverage Google Gemini's large context capacity.

  ## File and Directory Inclusion Syntax

  Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the
   gemini command:

  ### Examples:

  **Single file analysis:**
  ```bash
  gemini -p "@src/main.py Explain this file's purpose and structure"

  Multiple files:
  gemini -p "@package.json @src/index.js Analyze the dependencies used in the code"

  Entire directory:
  gemini -p "@src/ Summarize the architecture of this codebase"

  Multiple directories:
  gemini -p "@src/ @tests/ Analyze test coverage for the source code"

  Current directory and subdirectories:
  gemini -p "@./ Give me an overview of this entire project"
  
#
 Or use --all_files flag:
  gemini --all_files -p "Analyze the project structure and dependencies"

  Implementation Verification Examples

  Check if a feature is implemented:
  gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"

  Verify authentication implementation:
  gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware"

  Check for specific patterns:
  gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths"

  Verify error handling:
  gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks"

  Check for rate limiting:
  gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details"

  Verify caching strategy:
  gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"

  Check for specific security measures:
  gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"

  Verify test coverage for features:
  gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases"

  When to Use Gemini CLI

  Use gemini -p when:
  - Analyzing entire codebases or large directories
  - Comparing multiple large files
  - Need to understand project-wide patterns or architecture
  - Current context window is insufficient for the task
  - Working with files totaling more than 100KB
  - Verifying if specific features, patterns, or security measures are implemented
  - Checking for the presence of certain coding patterns across the entire codebase

  Important Notes

  - Paths in @ syntax are relative to your current working directory when invoking gemini
  - The CLI will include file contents directly in the context
  - No need for --yolo flag for read-only analysis
  - Gemini's context window can handle entire codebases that would overflow Claude's context
  - When checking implementations, be specific about what you're looking for to get accurate results # Using Gemini CLI for Large Codebase Analysis


  When analyzing large codebases or multiple files that might exceed context limits, use the Gemini CLI with its massive
  context window. Use `gemini -p` to leverage Google Gemini's large context capacity.


  ## File and Directory Inclusion Syntax


  Use the `@` syntax to include files and directories in your Gemini prompts. The paths should be relative to WHERE you run the
   gemini command:


  ### Examples:


  **Single file analysis:**
  ```bash
  gemini -p "@src/main.py Explain this file's purpose and structure"


  Multiple files:
  gemini -p "@package.json @src/index.js Analyze the dependencies used in the code"


  Entire directory:
  gemini -p "@src/ Summarize the architecture of this codebase"


  Multiple directories:
  gemini -p "@src/ @tests/ Analyze test coverage for the source code"


  Current directory and subdirectories:
  gemini -p "@./ Give me an overview of this entire project"
  # Or use --all_files flag:
  gemini --all_files -p "Analyze the project structure and dependencies"


  Implementation Verification Examples


  Check if a feature is implemented:
  gemini -p "@src/ @lib/ Has dark mode been implemented in this codebase? Show me the relevant files and functions"


  Verify authentication implementation:
  gemini -p "@src/ @middleware/ Is JWT authentication implemented? List all auth-related endpoints and middleware"


  Check for specific patterns:
  gemini -p "@src/ Are there any React hooks that handle WebSocket connections? List them with file paths"


  Verify error handling:
  gemini -p "@src/ @api/ Is proper error handling implemented for all API endpoints? Show examples of try-catch blocks"


  Check for rate limiting:
  gemini -p "@backend/ @middleware/ Is rate limiting implemented for the API? Show the implementation details"


  Verify caching strategy:
  gemini -p "@src/ @lib/ @services/ Is Redis caching implemented? List all cache-related functions and their usage"


  Check for specific security measures:
  gemini -p "@src/ @api/ Are SQL injection protections implemented? Show how user inputs are sanitized"


  Verify test coverage for features:
  gemini -p "@src/payment/ @tests/ Is the payment processing module fully tested? List all test cases"


  When to Use Gemini CLI


  Use gemini -p when:
  - Analyzing entire codebases or large directories
  - Comparing multiple large files
  - Need to understand project-wide patterns or architecture
  - Current context window is insufficient for the task
  - Working with files totaling more than 100KB
  - Verifying if specific features, patterns, or security measures are implemented
  - Checking for the presence of certain coding patterns across the entire codebase


  Important Notes


  - Paths in @ syntax are relative to your current working directory when invoking gemini
  - The CLI will include file contents directly in the context
  - No need for --yolo flag for read-only analysis
  - Gemini's context window can handle entire codebases that would overflow Claude's context
  - When checking implementations, be specific about what you're looking for to get accurate results