Import remaining project documentation and reference notes

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
2026-09-18 23:33:04 +03:30
parent 4791bc2da0
commit e9cd12dda6
43 changed files with 20604 additions and 0 deletions
@@ -0,0 +1,47 @@
+# Teknav — Festival Submission Manifest
+
+A curated subset of the Teknav source tree, chosen to demonstrate the project's
+**custom engineering** rather than boilerplate. Original directory structure is
+preserved so each file reads in context. No original files were modified — these
+are copies. A mandatory security pass found **no hardcoded secrets**; all
+credentials in the live code are read from `process.env` (nothing required
+redaction).
+
+> Note: the repository has no top-level `README.md`, so none is included.
+
+---
+
+## Included files
+
+| # | File | Description | Presentation topic |
+|---|------|-------------|--------------------|
+| 1 | `backend/src/lib/embeddings.ts` | Semantic-search core: stores normalized vectors into the `ArticleEmbedding` table and runs nearest-neighbor lookup using pgvector's cosine-distance operator `<=>` via raw SQL. | **AI / pgvector search** |
+| 2 | `backend/src/routes/rag-gateway.ts` | RAG gateway. `GET /api/v1/rag/:slug` serves clean LLM-ready Markdown (custom HTML→Markdown stripper), and `POST /api/v1/search/semantic` exposes the vector search with rate limiting. | **RAG gateway** |
+| 3 | `backend/prisma/schema.prisma` | Single source of truth for the data model, including the `ArticleEmbedding` model with the `vector(1536)` pgvector column and the article relation that enables semantic search. | **AI / pgvector search** (schema) |
+| 4 | `scripts/generate-article-pages.mjs` | Build-time SEO generator. Injects a crawlable static-HTML fallback and a JSON-LD graph (NewsArticle/TechArticle + author `sameAs` E-E-A-T signals) into each article page — the engine behind the Zero-CDN static output. | **Zero-CDN SEO** |
+| 5 | `teknav-app.jsx` | Custom client-side router built on React Context + the History API (`pushState`/`popstate`) — no React Router dependency. Central route dispatch for every page type. | **Custom router** |
+| 6 | `teknav-admin.jsx` | Custom CMS / admin article editor: raw-textarea HTML editor with tag/snippet injection and Base64 image upload, role-aware controls, revisions and presence. | **Custom CMS editor** |
+| 7 | `package.json` | Frontend manifest — shows the deliberately lightweight, dependency-minimal philosophy (Vite + React, no heavy UI frameworks). | Dependency philosophy (all topics) |
+| 8 | `backend/package.json` | Backend manifest — Fastify + Prisma + Redis; lean server stack with no bloat. | Dependency philosophy (all topics) |
+
+---
+
+## Topic → file map
+
+- **AI / pgvector semantic search:** `backend/src/lib/embeddings.ts`, `backend/prisma/schema.prisma`
+- **RAG gateway (Markdown for LLMs):** `backend/src/routes/rag-gateway.ts`
+- **Zero-CDN build-time SEO + JSON-LD:** `scripts/generate-article-pages.mjs`
+- **Custom React-Context + History API router:** `teknav-app.jsx`
+- **Custom CMS / admin article editor:** `teknav-admin.jsx`
+- **Lightweight dependency philosophy:** `package.json`, `backend/package.json`
+
+---
+
+## Security pass
+
+- Scanned all 8 copied files for API keys, tokens, passwords, connection strings,
+  private keys, and credential-bearing URLs.
+- **Result:** clean. Matches found (`passwordHash`, `unsubscribeToken`,
+  `doubleOptInToken`) were Prisma *column definitions*, not values.
+- No `.env` files, credentials, certificates, `node_modules`, `dist`, `build`, or
+  `.git` content was copied.