Add system architecture documentation for Restaurant Recommendation System

README.md

@@ -1,6 +1,140 @@
 # Restaurant Recommendation System
 
-Architecture documentation for a Restaurant Recommendation System.
+A scalable, ML-powered restaurant recommendation system that delivers personalized dining suggestions based on user preferences, location, behavior history, and contextual signals.
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Core Modules](#core-modules)
+- [Tech Stack](#tech-stack)
+- [Documentation Index](#documentation-index)
+
+---
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph Client["Client Layer"]
+        MobileApp["📱 Mobile App"]
+        WebApp["🌐 Web App"]
+        ThirdParty["🔗 Third-party API"]
+    end
+
+    subgraph Gateway["API Gateway Layer"]
+        LB["Load Balancer"]
+        APIGW["API Gateway\n(Auth · Rate Limit · Routing)"]
+    end
+
+    subgraph Serving["Serving Layer"]
+        RecAPI["Recommendation\nService (FastAPI)"]
+        SearchAPI["Search\nRe-rank Service"]
+    end
+
+    subgraph RecsEngine["Recommendation Engine"]
+        CandGen["Candidate\nGeneration"]
+        Ranking["Scoring &\nRanking"]
+        ReRank["Re-ranking &\nBusiness Logic"]
+    end
+
+    subgraph DataLayer["Data Layer"]
+        Redis[("Redis Cache")]
+        Postgres[("PostgreSQL")]
+        Elasticsearch[("Elasticsearch")]
+        Milvus[("Milvus\nVector DB")]
+    end
+
+    subgraph MLPlatform["ML Platform"]
+        FeatureStore["Feature Store"]
+        ModelRegistry["Model Registry\n(MLflow)"]
+        Training["Training\nPipeline"]
+    end
+
+    subgraph Streaming["Streaming Layer"]
+        Kafka["Apache Kafka"]
+        Flink["Apache Flink"]
+    end
+
+    subgraph Observability["Observability"]
+        Prometheus["Prometheus"]
+        Grafana["Grafana"]
+        ELK["ELK Stack"]
+    end
+
+    Client --> LB --> APIGW --> Serving
+    Serving --> RecsEngine
+    RecsEngine --> DataLayer
+    RecsEngine --> FeatureStore
+    MLPlatform --> RecsEngine
+    Streaming --> FeatureStore
+    Serving --> Observability
+```
+
+---
+
+## Core Modules
+
+| # | Module | Description |
+|---|--------|-------------|
+| 01 | [Data Ingestion](docs/modules/01-data-ingestion.md) | Clickstream tracking, restaurant catalog sync, user profile aggregation, review ingestion |
+| 02 | [Recommendation Engine](docs/modules/02-recommendation-engine.md) | Candidate generation → Scoring/Ranking → Re-ranking with business rules |
+| 03 | [Serving & Delivery](docs/modules/03-serving-delivery.md) | REST API endpoints, 4-layer caching, real-time personalization stream |
+| 04 | [Feature Store](docs/modules/04-feature-store.md) | Online/Offline store, feature registry, <5ms latency SLA |
+| 05 | [ML Platform](docs/modules/05-ml-platform.md) | Training pipelines, model lifecycle, canary/blue-green deployment |
+| 06 | [Experimentation](docs/modules/06-experimentation.md) | A/B testing framework, statistical testing, experiment lifecycle |
+| 07 | [Observability](docs/modules/07-observability.md) | System monitoring, ML drift detection, business metrics, alerting |
+| 08 | [Data Pipeline](docs/modules/08-data-pipeline.md) | Airflow DAGs, Kafka+Flink streaming, SLAs, retry strategies |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| API | FastAPI (Python), Go (high-throughput endpoints) |
+| ML Framework | PyTorch, TensorFlow, LightGBM, XGBoost |
+| Feature Store | Redis (online), S3 + BigQuery (offline) |
+| Vector Search | Milvus (HNSW ANN), Elasticsearch |
+| Streaming | Apache Kafka, Apache Flink |
+| Batch Processing | Apache Spark, Apache Airflow |
+| Relational DB | PostgreSQL |
+| Cache | Redis Cluster |
+| Model Serving | TensorFlow Serving, NVIDIA Triton |
+| Model Registry | MLflow |
+| Experiment Tracking | Evidently AI |
+| Monitoring | Prometheus, Grafana, Metabase |
+| Logging | ELK Stack / Grafana Loki |
+| CI/CD | GitHub Actions |
+| Container / Orchestration | Docker, Kubernetes |
+
+---
+
+## Documentation Index
+
+### Architecture
+- [System Overview](docs/architecture/system-overview.md) — System diagram, request lifecycle, latency budgets
+- [Tech Stack](docs/architecture/tech-stack.md) — Technology choices and justification
+- [Data Flow](docs/architecture/data-flow.md) — Real-time, batch, and streaming flow diagrams
+
+### Modules
+- [01 Data Ingestion](docs/modules/01-data-ingestion.md)
+- [02 Recommendation Engine](docs/modules/02-recommendation-engine.md)
+- [03 Serving & Delivery](docs/modules/03-serving-delivery.md)
+- [04 Feature Store](docs/modules/04-feature-store.md)
+- [05 ML Platform](docs/modules/05-ml-platform.md)
+- [06 Experimentation](docs/modules/06-experimentation.md)
+- [07 Observability](docs/modules/07-observability.md)
+- [08 Data Pipeline](docs/modules/08-data-pipeline.md)
+
+### Schemas
+- [User Event Schema](docs/schemas/user-event.md)
+- [Restaurant Catalog Schema](docs/schemas/restaurant-catalog.md)
+- [User Profile Schema](docs/schemas/user-profile.md)
+- [Review & Rating Schema](docs/schemas/review-rating.md)
+
+### API
+- [API Specification](docs/api/api-specification.md)
+
+### Infrastructure
+- [Deployment](docs/infrastructure/deployment.md)
 
-## Status
-🚧 Under Development