chore: reorganize documentation structure and clean repository root

Consolidate docs into architecture/development/performance/presentation sections, refresh navigation links, and move root-level logs and legacy data snapshots into dedicated archive locations to keep the repo entrypoints clean.

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitignore

@@ -47,6 +47,10 @@ Thumbs.db
 *.csv
 *.txt
 !requirements.txt
+# keep historical root snapshots after cleanup
+!data/legacy_root_exports/
+!data/legacy_root_exports/*.csv
+!data/legacy_root_exports/*.txt
 # data/books_processed.csv and others are now loaded at runtime from HF
 
 # Model files (downloaded at runtime from HF Hub)

CHANGELOG.md

@@ -9,7 +9,9 @@ All notable changes to this project will be documented in this file.
 - **Version alignment**: Updated `src/main.py`, `web/package.json` to 2.6.0. Unified version references across README, docs, technical_report, experiment_archive, interview_guide, roadmap.
 - **Freeze notice**: Added to README, docs/README, experiment_archive, roadmap.
 
-## [Unreleased]
+## [Post-freeze maintenance] - 2026-02-12
+
+Post-freeze updates after v2.6.0 baseline lock. Scope: bug fixes, architecture cleanup, and documentation/engineering maintenance.
 
 ### Added - A/B Testing & RAG Diversity (2026-02-12)
 - **A/B testing framework** (`src/core/ab_experiments.py`): Minimal experiment assignment via `get_variant(user_id, experiment_id)`; `get_experiment_config()` returns control/treatment params. Enable with `AB_EXPERIMENTS_ENABLED=true`.
@@ -28,7 +30,7 @@ All notable changes to this project will be documented in this file.
 - **Fallback rules improved**: Replaced brittle `len(words) <= 2` with NL keyword detection (`ROUTER_NL_KEYWORDS`: like, similar, recommend, want, looking, ...). Short queries (≤6 words) without NL keywords → FAST; queries with NL keywords → DEEP.
 - **Config**: `natural_language_keywords` in router config; `ROUTER_NL_KEYWORDS` in `src/config.py`.
 
-### Added - Latency Optimizations (LATENCY_OPTIMIZATION.md)
+### Added - Latency Optimizations (`docs/performance/LATENCY_OPTIMIZATION.md`)
 - **1. 裁剪候选集**: `RERANK_CANDIDATES_MAX=20` (env overridable); rerank top 20 instead of 50.
 - **2. ColBERT**: `RERANKER_BACKEND=colbert`; optional `llama-index-postprocessor-colbert-rerank`.
 - **3. Rerank 异步化**: `fast=true` skips rerank (~150ms); `async_rerank=true` returns RRF first, reranks in background, next request gets cached reranked.

CONTRIBUTING.md

@@ -23,7 +23,7 @@ python scripts/init_sqlite_db.py
 make run
 ```
 
-详见 [README](README.md) 与 [Build Guide](docs/build_guide.md)。
+详见 [README](README.md) 与 [Build Guide](docs/development/build_guide.md)。
 
 ---
 
@@ -40,8 +40,10 @@ make run
 ├── config/                 # 路由等配置
 ├── data/                   # 数据目录（不入库）
 └── docs/                   # 文档
-    ├── DEVELOPMENT.md      # 开发指南（召回、路由）
-    ├── TECHNICAL_REPORT.md # 技术报告
+    ├── architecture/       # 技术报告、架构图
+    ├── development/        # 开发与部署指南
+    ├── performance/        # 性能优化与调试
+    ├── presentation/       # 面试材料与演进路线
     └── ...
 ```
 
@@ -73,8 +75,8 @@ make run
 
 | 场景 | 参考文档 |
 |------|----------|
-| 添加新召回通道 | [docs/DEVELOPMENT.md § 一](docs/DEVELOPMENT.md#一如何添加新的召回通道) |
-| 调整路由规则 / 关键词 | [docs/DEVELOPMENT.md § 二](docs/DEVELOPMENT.md#二如何调整路由规则) |
+| 添加新召回通道 | [docs/development/DEVELOPMENT.md § 一](docs/development/DEVELOPMENT.md#一如何添加新的召回通道) |
+| 调整路由规则 / 关键词 | [docs/development/DEVELOPMENT.md § 二](docs/development/DEVELOPMENT.md#二如何调整路由规则) |
 | 修复 Bug | 先复现，再最小改动修复 |
 | 性能优化 | 对比前后指标，在 CHANGELOG 中记录 |
 
@@ -83,7 +85,7 @@ make run
 ## 五、文档与变更
 
 - **CHANGELOG.md**: 用户可见的变更应在此记录
-- **docs/DEVELOPMENT.md**: 开发相关扩展或修改流程时同步更新
+- **docs/development/DEVELOPMENT.md**: 开发相关扩展或修改流程时同步更新
 - **README.md**: 面向使用者的说明，重大功能变更时更新
 
 ---

README.md

@@ -7,7 +7,7 @@ app_port: 8000
 
 # Intelligent Book Recommendation System
 
-*Frozen at v2.6.0 — maintenance mode for portfolio use.*
+*Frozen at v2.6.0 (model/features baseline) — maintenance mode for portfolio use. Post-freeze updates are limited to bug fixes, refactor, and documentation.*
 
 ## Problem
 
@@ -64,14 +64,16 @@ cd web && npm install && npm run dev   # UI http://localhost:5173
 
 ## Documentation
 
+Start from the internal documentation hub: [`docs/README.md`](docs/README.md).
+
 | Doc | Purpose |
 |:---|:---|
-| [Technical Report](docs/TECHNICAL_REPORT.md) | Architecture, design decisions |
-| [Development Guide](docs/DEVELOPMENT.md) | 添加召回通道、调整路由规则 |
-| [Contributing](CONTRIBUTING.md) | 贡献者指南 |
-| [Experiment Archive](docs/experiments/experiment_archive.md) | Full experiment log (V1.0 → v2.6.0) |
-| [Interview Guide](docs/interview_guide.md) | Q&A, STAR cases |
-| [Build Guide](docs/build_guide.md) | Deployment instructions |
+| [Docs Hub](docs/README.md) | Canonical documentation navigation |
+| [Technical Report](docs/architecture/TECHNICAL_REPORT.md) | Architecture and design decisions |
+| [Experiment Archive](docs/experiments/experiment_archive.md) | Consolidated experiment log (V1.0 → v2.6.0) |
+| [Development Guide](docs/development/DEVELOPMENT.md) | Engineering playbook for extension/refactor |
+| [Build Guide](docs/development/build_guide.md) | Build and deployment instructions |
+| [Changelog](CHANGELOG.md) | Versioned change history |
 
 ## License
 

docs/README.md

@@ -1,33 +1,65 @@
-# Project Documentation
+# Project Documentation Hub
 
-## Layer 1 — Main Story (README, 5-min interview)
+This file is the canonical navigation entry for project documentation.
+
+## Current Status
+
+- **Baseline**: v2.6.0 is frozen for portfolio use.
+- **Allowed updates**: bug fixes, engineering refactor, documentation cleanup.
+- **Not in scope**: new model/features or new experiment tracks.
+
+## 1) Start Here (Most readers)
+
+| Document | Audience | Purpose |
+|:---|:---|:---|
+| [../README.md](../README.md) | Recruiter / first-time visitor | 5-minute project overview and quick start |
+| [architecture/TECHNICAL_REPORT.md](architecture/TECHNICAL_REPORT.md) | Engineer / interviewer | Full architecture and design decisions |
+| [experiments/experiment_archive.md](experiments/experiment_archive.md) | Research / reviewer | Consolidated experiment timeline and conclusions |
+| [../CHANGELOG.md](../CHANGELOG.md) | Maintainer | Versioned change history |
+
+## 2) Engineering Guides (Contributors)
 
 | Document | Purpose |
 |:---|:---|
-| [Technical Report](TECHNICAL_REPORT.md) | Architecture, design decisions, method line |
-| [Architecture Diagrams](ARCHITECTURE_DIAGRAMS.md) | 流程图、时序图、ER 图（Mermaid） |
-| [Experiment Archive](experiments/experiment_archive.md) | Consolidated experiment log (V1.0 → v2.6.0) |
+| [development/DEVELOPMENT.md](development/DEVELOPMENT.md) | Extend recall/ranking/router and maintain pipeline |
+| [development/build_guide.md](development/build_guide.md) | Local build and service startup pipeline |
+| [development/huggingface_deployment.md](development/huggingface_deployment.md) | HF Spaces deployment notes |
+| [performance/memory_optimization.md](performance/memory_optimization.md) | Zero-RAM SQLite and memory trade-offs |
+| [performance/LATENCY_OPTIMIZATION.md](performance/LATENCY_OPTIMIZATION.md) | Latency tuning options and trade-offs |
+| [performance/performance_debugging_report.md](performance/performance_debugging_report.md) | Root-cause analysis and debugging playbook |
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) | Contribution guidelines |
 
-## Layer 2 — Capability Showcase (Resume, technical Q&A)
+## 3) Presentation Material
 
 | Document | Purpose |
 |:---|:---|
-| [Development Guide](DEVELOPMENT.md) | 添加召回通道、调整路由规则 |
-| [Contributing](../CONTRIBUTING.md) | 贡献者指南 |
-| [Interview Guide](interview_guide.md) | Q&A, STAR cases |
-| [Memory Optimization](memory_optimization.md) | Zero-RAM SQLite, engineering decisions |
-| [Performance Debugging](performance_debugging_report.md) | Root cause analysis |
-| [Build Guide](build_guide.md) | Full build pipeline |
-| [Hugging Face Deployment](huggingface_deployment.md) | HF Spaces deployment |
+| [presentation/interview_guide.md](presentation/interview_guide.md) | Interview Q&A and STAR examples |
+| [presentation/roadmap.md](presentation/roadmap.md) | Technical evolution and vision gap |
 
-## Archives
+## 4) Archives and Raw Reports
 
-| Path | Contents |
+| Path | Purpose |
 |:---|:---|
-| [archived/](archived/) | Deprecated docs (Phase 2, TAGS, REVIEW_HIGHLIGHTS, etc.) |
-| [archived/graveyard/](archived/graveyard/) | Layer 3 — tried but not in main story (future_roadmap, interview_deep_dive, etc.) |
-| [experiments/reports/](experiments/reports/) | Raw experiment reports (baseline, hybrid, rerank, router, temporal) |
+| [archived/README.md](archived/README.md) | Archived document index with reason tags |
+| [archived/](archived/) | Deprecated or superseded docs |
+| [experiments/reports/](experiments/reports/) | Raw experiment reports |
+| [../data/legacy_root_exports/](../data/legacy_root_exports/) | Historical root-level data snapshots moved out of repo root |
+
+## Documentation Rules
+
+Each active document should include a short metadata block near the top:
+
+- `Status`: `active` | `frozen` | `deprecated` | `archived`
+- `Audience`: target reader
+- `Last Updated`: `YYYY-MM-DD`
+- `Owner`: maintainer name
+
+When code behavior changes, update:
+
+1. `CHANGELOG.md`
+2. One topic document in `docs/`
+3. This file (`docs/README.md`) if navigation changed
 
 ---
 
-**Frozen v2.6.0** — HR@10 = 0.4545, MRR@5 = 0.2893
+**Frozen baseline metrics (v2.6.0):** HR@10 = 0.4545, MRR@5 = 0.2893

docs/{ARCHITECTURE_DIAGRAMS.md → architecture/ARCHITECTURE_DIAGRAMS.md}

@@ -347,5 +347,5 @@ flowchart TB
 - **命令行**: 使用 `mmdc` (mermaid-cli) 导出 PNG/SVG
   ```bash
   npm install -g @mermaid-js/mermaid-cli
-  mmdc -i docs/ARCHITECTURE_DIAGRAMS.md -o docs/diagrams/
+  mmdc -i docs/architecture/ARCHITECTURE_DIAGRAMS.md -o docs/diagrams/
   ```

docs/archived/README.md

@@ -0,0 +1,48 @@
+# Archived Documentation Index
+
+Use this index to find deprecated/superseded materials quickly.
+
+## Status Semantics
+
+- `deprecated`: replaced by newer canonical docs
+- `archived`: historical snapshot retained for traceability
+- `reference-only`: useful background, not part of current main story
+
+## Archived at `docs/archived/`
+
+| Document | Status | Reason |
+|:---|:---|:---|
+| [DEPLOYMENT.md](DEPLOYMENT.md) | deprecated | Replaced by [`../development/build_guide.md`](../development/build_guide.md) and [`../development/huggingface_deployment.md`](../development/huggingface_deployment.md) |
+| [PHASE_2_DEVELOPMENT.md](PHASE_2_DEVELOPMENT.md) | archived | Phase-specific implementation log |
+| [REVIEW_HIGHLIGHTS.md](REVIEW_HIGHLIGHTS.md) | archived | Feature-specific historical note |
+| [TAGS_AND_EMOTIONS.md](TAGS_AND_EMOTIONS.md) | archived | Earlier tagging/emotion design notes |
+| [interview_prep_v1.md](interview_prep_v1.md) | deprecated | Superseded by [`../presentation/interview_guide.md`](../presentation/interview_guide.md) |
+| [story_and_strategy.md](story_and_strategy.md) | reference-only | Narrative framing draft, not canonical technical source |
+
+## Archived assets
+
+| Path | Status | Reason |
+|:---|:---|:---|
+| [assets/](assets/) | archived | Non-source artifacts kept for historical record |
+
+## Archived at `docs/archived/graveyard/`
+
+These files are exploratory drafts and intermediate analyses.
+
+| Document | Status | Reason |
+|:---|:---|:---|
+| [DEPLOYMENT.md](graveyard/DEPLOYMENT.md) | archived | Early deployment draft |
+| [business_logic.md](graveyard/business_logic.md) | archived | Early business-logic decomposition draft |
+| [future_roadmap.md](graveyard/future_roadmap.md) | reference-only | Long-horizon ideas not in frozen scope |
+| [interview_deep_dive.md](graveyard/interview_deep_dive.md) | reference-only | Expanded interview draft |
+| [interview_prep.md](graveyard/interview_prep.md) | deprecated | Replaced by active interview guide |
+| [phase7_plan.md](graveyard/phase7_plan.md) | archived | Phase plan snapshot after implementation |
+| [project_analysis.md](graveyard/project_analysis.md) | archived | Intermediate analysis notes |
+| [project_narrative.md](graveyard/project_narrative.md) | reference-only | Storytelling draft |
+| [rag_architecture.md](graveyard/rag_architecture.md) | deprecated | Replaced by technical report and diagrams |
+| [technical_architecture.md](graveyard/technical_architecture.md) | deprecated | Replaced by technical report |
+| [technical_deep_dive_sota.md](graveyard/technical_deep_dive_sota.md) | reference-only | Background survey notes |
+
+---
+
+If a file in this index should be restored to active status, move it out of `archived/` and add it to [`../README.md`](../README.md).

server_final.log

@@ -1,42 +0,0 @@
-uvicorn src.main:app --reload --port 6006
-INFO:     Will watch for changes in these directories: ['/Users/ymlin/Downloads/003-Study/138-Projects/08-book-rec-with-LLMs']
-INFO:     Uvicorn running on http://127.0.0.1:6006 (Press CTRL+C to quit)
-INFO:     Started reloader process [9672] using WatchFiles
-2026-01-10 23:12:04,451 - src.services.chat_service - INFO - ChatService: Loading books data for context retrieval...
-2026-01-10 23:12:04,451 - src.etl - INFO - Loading processed data from /Users/ymlin/Downloads/003-Study/138-Projects/08-book-rec-with-LLMs/data/books_processed.csv
-INFO:     Started server process [9726]
-INFO:     Waiting for application startup.
-2026-01-10 23:12:08,624 - src.main - INFO - Initializing Recommender Engine...
-2026-01-10 23:12:08,624 - src.etl - INFO - Loading processed data from /Users/ymlin/Downloads/003-Study/138-Projects/08-book-rec-with-LLMs/data/books_processed.csv
-2026-01-10 23:12:12,766 - src.recommender - INFO - Loaded books DataFrame with columns: ['isbn13', 'title', 'description', 'average_rating', 'authors', 'thumbnail', 'simple_categories', 'joy', 'sadness', 'fear', 'anger', 'surprise', 'tags', 'review_highlights', 'large_thumbnail']
-2026-01-10 23:12:12,766 - src.vector_db - INFO - Loading embedding model: sentence-transformers/all-MiniLM-L6-v2
-/Users/ymlin/Downloads/003-Study/138-Projects/08-book-rec-with-LLMs/src/vector_db.py:36: LangChainDeprecationWarning: The class `HuggingFaceEmbeddings` was deprecated in LangChain 0.2.2 and will be removed in 1.0. An updated version of the class exists in the `langchain-huggingface package and should be used instead. To use it run `pip install -U `langchain-huggingface` and import as `from `langchain_huggingface import HuggingFaceEmbeddings``.
-  self.embeddings = HuggingFaceEmbeddings(
-2026-01-10 23:12:14,865 - src.vector_db - INFO - Embedding model loaded successfully
-2026-01-10 23:12:14,865 - src.vector_db - INFO - Loading existing vector database from /Users/ymlin/Downloads/003-Study/138-Projects/08-book-rec-with-LLMs/data/chroma_db
-/Users/ymlin/Downloads/003-Study/138-Projects/08-book-rec-with-LLMs/src/vector_db.py:45: LangChainDeprecationWarning: The class `Chroma` was deprecated in LangChain 0.2.9 and will be removed in 1.0. An updated version of the class exists in the `langchain-chroma package and should be used instead. To use it run `pip install -U `langchain-chroma` and import as `from `langchain_chroma import Chroma``.
-  self.db = Chroma(
-2026-01-10 23:12:17,822 - src.vector_db - INFO - Loaded 222003 documents from vector database
-2026-01-10 23:12:17,824 - src.vector_db - INFO - Initializing BM25 Index (Sparse Retrieval)...
-2026-01-10 23:12:35,315 - src.vector_db - INFO - BM25 Index built with 222005 documents.
-2026-01-10 23:12:41,192 - src.vector_db - INFO - Loaded 186954 publication dates for Temporal Scoring.
-Redis cache initialization failed: Error 61 connecting to localhost:6379. Connection refused.. Caching disabled.
-2026-01-10 23:12:44,213 - src.recommender - INFO - Loaded 212398 book images from books_basic_info.csv
-2026-01-10 23:12:44,213 - src.main - INFO - Initializing Personalized Rec Service...
-Failed to load YoutubeDNN: [Errno 2] No such file or directory: 'data/model/recall/youtube_dnn.pt'
-Failed to load YoutubeDNN: [Errno 2] No such file or directory: 'data/model/recall/youtube_dnn.pt'
-2026-01-10 23:13:30,405 - src.main - INFO - Engines Initialized.
-INFO:     Application startup complete.
-INFO:     127.0.0.1:58450 - "GET /api/recommend/personal?user_id=demo&top_k=1 HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58469 - "GET /favorites/list/local HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "GET /user/local/stats HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58471 - "GET /api/recommend/personal?user_id=local&limit=20 HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58469 - "GET /user/local/stats HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58472 - "GET /favorites/list/local HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "GET /api/recommend/personal?user_id=local&limit=20 HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "OPTIONS /marketing/highlights HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "POST /marketing/highlights HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "POST /marketing/highlights HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "POST /marketing/highlights HTTP/1.1" 200 OK
-INFO:     127.0.0.1:58470 - "POST /marketing/highlights HTTP/1.1" 200 OK
-make: *** [run] Hangup: 1