Add system architecture documentation for Restaurant Recommendation System

[Copilot]

Bootstraps the full architecture documentation suite for a restaurant recommendation system — covering ML pipeline, serving infra, data schemas, and operational runbook material. Repo previously had only a 3-line README stub.

Structure added

docs/
├── architecture/       # system-overview, tech-stack, data-flow
├── modules/            # 8 modules: ingestion → engine → serving → features → ML platform → experiments → observability → pipelines
├── schemas/            # user-event, restaurant-catalog, user-profile, review-rating
├── api/                # REST API specification (6 endpoints)
└── infrastructure/     # Kubernetes + CI/CD deployment

Key content per section

Architecture

• System diagram and end-to-end request lifecycle with latency budget (p50 ~39ms / p99 ~106ms cache-miss path; p50 ~5ms cache-hit)
• Tech stack table with justifications and alternatives considered per layer

Recommendation Engine (02-recommendation-engine.md)

• 3-stage funnel: Candidate Generation (500–2000) → Scoring/Ranking (top 50–200, LightGBM/DeepFM/DIN) → Re-ranking (MMR diversity, business rules, fairness constraints)
• Cold start transition thresholds (cold→warm at 10 interactions, full personalization at 30)

Serving (03-serving-delivery.md)

• 4-layer cache: CDN (5–15 min TTL) → Redis app cache (30 min–2 h) → Feature Store cache (1–6 h) → Model Prediction cache (15–30 min)
• 6 REST endpoints with p50/p99 SLAs, rate limits (100 req/min per user, 1000/min per API key)

ML Platform (05-ml-platform.md)

• Canary (5% / 2 h) → shadow → blue-green; auto-rollback triggers: p99 latency >300 ms, error rate >1%, NDCG drop >5%

Experimentation (06-experimentation.md)

• mSPRT sequential testing, α=0.05, power=0.80, Bonferroni correction, CUPED variance reduction

Observability (07-observability.md)

• Prometheus/Grafana (system), Evidently AI (ML drift, PSI >0.2 threshold), Metabase (business), structured per-request logs with latency_breakdown_ms

Schemas

• Restaurant catalog includes all domain-specific fields: geohash, cuisine taxonomy (120+ types), price tiers ($–$$$$), dietary flags, ambiance tags, 768d text + 512d image embeddings
• User event schema covers 8 event types with full context and experiment variant metadata

Infrastructure (deployment.md)

• Multi-stage Docker builds, Kubernetes HPA configs (CPU-based for API, KEDA queue-depth for GPU/Triton), GitHub Actions CI/CD with canary promotion step

Original prompt

Mục tiêu

Tạo bộ tài liệu kiến trúc hệ thống (Architecture Documentation) cho hệ thống Restaurant Recommendation — một hệ thống gợi ý nhà hàng cho người dùng. CHỈ tạo tài liệu Markdown, KHÔNG tạo source code.

Cấu trúc thư mục cần tạo

Restaurant-Recommendation/
├── README.md                                    # Cập nhật: Tổng quan + Architecture Overview
└── docs/
    ├── architecture/
    │   ├── system-overview.md                   # System diagram + Request lifecycle
    │   ├── tech-stack.md                        # Tech stack + Justification
    │   └── data-flow.md                         # Real-time, Batch, Streaming flows
    ├── modules/
    │   ├── 01-data-ingestion.md                 # Data collection & schemas
    │   ├── 02-recommendation-engine.md          # Core ML: Candidate → Ranking → Re-ranking
    │   ├── 03-serving-delivery.md               # API, Caching, Real-time serving
    │   ├── 04-feature-store.md                  # Online/Offline store, Registry
    │   ├── 05-ml-platform.md                    # Training pipeline, Model lifecycle
    │   ├── 06-experimentation.md                # A/B Testing framework
    │   ├── 07-observability.md                  # Monitoring, Alerting, Logging
    │   └── 08-data-pipeline.md                  # Orchestration, DAGs, SLAs
    ├── schemas/
    │   ├── user-event.md                        # Event schema + JSON examples
    │   ├── restaurant-catalog.md                # Restaurant-specific schema
    │   ├── user-profile.md                      # Profile + preference vectors
    │   └── review-rating.md                     # Reviews + sentiment schema
    ├── api/
    │   └── api-specification.md                 # Full API docs + SLAs
    └── infrastructure/
        └── deployment.md                        # Deployment diagram + CI/CD

Yêu cầu chi tiết cho từng file

1. README.md (Root) — CẬP NHẬT file hiện có

• Tổng quan dự án Restaurant Recommendation
• Architecture Overview diagram (dùng Mermaid)
• Mô tả high-level các module chính (8 modules)
• Tech stack dự kiến (tóm tắt)
• Mục lục dẫn đến các tài liệu chi tiết trong docs/

2. docs/architecture/system-overview.md

• System Architecture Diagram tổng quan (Mermaid)
• Mô tả data flow từ khi user gửi request đến khi nhận được recommendations
• Request lifecycle chi tiết với latency budget cho từng bước (tổng ~60ms p50, ~150ms p99)
• Các thành phần chính: API Gateway, Recommendation Engine, Data Layer, ML Platform
• Deployment topology (containerized, microservices)

3. docs/architecture/tech-stack.md

• Bảng chi tiết tech stack cho từng layer/module
• Lý do chọn từng công nghệ (justification)
• Alternatives đã cân nhắc
• Bao gồm: API (FastAPI/Go), ML (PyTorch/TensorFlow), Data (Kafka, Spark, Airflow), Storage (PostgreSQL, Redis, Elasticsearch, Milvus), Monitoring (Prometheus, Grafana), CI/CD (GitHub Actions)

4. docs/architecture/data-flow.md

• Data flow diagrams (Mermaid) cho:
  • Real-time recommendation flow
  • Batch processing flow (model training, feature computation)
  • Event streaming flow (user behavior tracking)
• Mô tả chi tiết từng flow

5. docs/modules/01-data-ingestion.md

• User Behavior Tracking: clickstream, events (view, click, order, rate, search), sessions
• Restaurant Catalog Management: sync từ nguồn, enrichment (NLP tags, image embeddings)
• User Profile Aggregation: demographic, behavioral, preference vectors, user segments
• Review & Rating Ingestion: thu thập và xử lý reviews, sentiment analysis
• Data schemas mẫu dùng JSON/YAML code blocks cho: user events, restaurant catalog, user profile, reviews
• Đặc thù Restaurant domain: location data (lat/lng), cuisine types, operating hours, price range (4 tiers: $, $$, $$$, $$$$), dietary options (vegetarian, vegan, halal, gluten-free), ambiance, capacity, parking

6. docs/modules/02-recommendation-engine.md

• Candidate Generation (~500-2000 candidates):
  • Collaborative Filtering (ALS, BPR, Neural CF, Two-Tower)
  • Content-Based Filtering (embedding similarity + ANN search via HNSW)
  • Popularity/Trending Based (time-decay)
  • Location-Aware Filtering (geofencing, distance-based, configurable radius 1-50km)
  • Cuisine Matching (user cuisine preference → restaurant cuisine)
  • Knowledge Graph (GNN for entity relationships)
• Scoring & Ranking (→ top 50-200):
  • Feature engineering chi tiết: user features (embedding, segment, recency, frequency, monetary), restaurant features (embedding, cuisine, price, rating, review count, distance), context features (time, device, weather, occasion), cross features (user×cuisine affinity, user×price match, user-restaurant similarity)
  • Ranking models: LightGBM, XGBoost, DeepFM, Wide&Deep, DIN
  • Multi-objective ranking (relevance + distance + price + rating)
• Re-ranking & Business Logic (→ final top 10-50):
  • Diversity injection (MMR - Maximal Marginal Relevance, category_max_ratio=0.4)
    -...

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.