✨ Tính năng nổi bật

🏛️ Kiến trúc hệ thống

┌─────────────────────────────────────────────────────────────────────────┐
│                        USER (Browser)                                    │
│              https://d3qrt08bgfyl3d.cloudfront.net                       │
└────────────────────────────┬────────────────────────────────────────────┘
                             │ HTTPS
              ┌──────────────▼──────────────┐
              │         CloudFront           │
              │   /api/* → ALB (proxy)       │
              │   /*     → S3 Frontend       │
              └───────┬──────────┬──────────┘
                      │          │
          ┌───────────▼──┐  ┌────▼────────────────────────┐
          │  S3 Bucket   │  │  Application Load Balancer   │
          │  (React SPA) │  │  memrag-backend-alb-*.elb    │
          └──────────────┘  └────────────┬────────────────┘
                                         │
              ┌──────────────────────────▼──────────────────────────┐
              │              ECS EC2 — FastAPI Backend               │
              │                   Port 8000                          │
              │                                                      │
              │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
              │  │ Chat API │  │ Docs API │  │ Wiki / Auth API  │  │
              │  │  (SSE)   │  │ (upload) │  │ Transcription WS │  │
              │  └────┬─────┘  └────┬─────┘  └────────┬─────────┘  │
              │       │             │                  │            │
              │  ┌────▼─────────────▼──────────────────▼──────────┐ │
              │  │      Google ADK Agent (Gemini 2.5-flash)        │ │
              │  │           9 Tools + ContextFilterPlugin         │ │
              │  └────┬────┬────┬────┬────┬────┬───────────────────┘ │
              │       │    │    │    │    │    │                     │
              └───────┼────┼────┼────┼────┼────┼─────────────────────┘
                      │    │    │    │    │    │
          ┌───────────▼┐ ┌─▼──┐ │ ┌─▼──┐ │ ┌─▼──────┐
          │  ElastiCache│ │mem0│ │ │Wiki│ │ │DynamoDB│
          │  Redis Cache│ │    │ │ │S3  │ │ │Sessions│
          └─────────────┘ └────┘ │ └────┘ │ └────────┘
                              ┌──▼──┐  ┌──▼────┐
                              │     │  │  RDS  │
                              │Qdrant  │Postgres│
                              │(RAG)│  │(Auth) │
                              └─────┘  └───────┘

🔄 Data Flow

💬 Chat Flow

User nhắn tin
    └─► POST /api/v1/chat/stream (SSE)
            └─► ChatService._ensure_session() [DynamoDB]
                    └─► ContextFilterPlugin (tóm tắt nếu > 22 msgs)
                            └─► ADK Runner → Gemini 2.5-flash
                                    ├─► read_wiki_index / read_wiki_page
                                    ├─► search_documents (RAG — Qdrant)
                                    ├─► retrieve_memories (mem0)
                                    └─► ─── SSE stream tokens ──► Browser

📄 Upload PDF Flow

Upload PDF
    └─► POST /api/v1/documents/upload
            ├─► extract text → StorageBackend.save() [S3]
            ├─► RAGService: chunk → embed → Qdrant upsert
            ├─► Cache.delete("docs:{user_id}:list")
            └─► [background] WikiService 4-phase pipeline
                    ├─► Phase 1 MAP:    extract entities/topics (parallel)
                    ├─► Phase 2 REDUCE: merge + deduplicate by slug
                    ├─► Phase 3 SYNTH:  LLM synthesize per page → S3
                    └─► Phase 4 FINAL:  rebuild index + link_index

🎙️ Transcription Flow

Start meeting → POST /transcription/start [DynamoDB]
    │
Audio stream → WS /transcription/audio/{meeting_id}
    └─► SonioxService → Soniox STT → utterances → DynamoDB
    │
Stop meeting → POST /transcription/stop
    ├─► TranscriptRAGService.ingest() [Qdrant]
    └─► [background] WikiService.update_wiki_from_transcript()

⚡ Cache Strategy

Request đến API
    │
    ├─► Cache.get(key) ──► HIT  ──► Return cached data (< 1ms)
    │
    └─► MISS ──► Tính toán / DB query
                    └─► Cache.set(key, data, ttl)
                            └─► Return data

TTL: wiki_page=10min | wiki_graph=2min | sessions=1min | docs=1min | user=5min

🚀 Quickstart — Local Dev

Yêu cầu

• Docker & Docker Compose
• Node.js 20+
• Python 3.11+ với uv
• Google Gemini API Key

1. Clone & cấu hình

git clone https://github.com/minh2004pd/chatbotfullpipeline.git
cd chatbotfullpipeline

# Tạo file .env từ example
cp .env.example .env
# → Điền GEMINI_API_KEY và các biến cần thiết

2. Khởi động services

# Chạy toàn bộ: Redis, Qdrant, DynamoDB Local, Postgres, Backend
docker compose up -d

# Kiểm tra logs backend
docker logs -f memrag-backend

3. Chạy Frontend

cd frontend
npm install
npm run dev
# → http://localhost:5173

4. API Docs

🧪 Testing

# Chạy toàn bộ test suite
cd backend && uv run pytest

# Với coverage report
uv run pytest --cov=app --cov-report=term-missing

# Chạy test cụ thể
uv run pytest tests/services/test_wiki_service.py -v

Test coverage: | Module | Test file | |--------|-----------| | Wiki pipeline | tests/services/test_wiki_service.py | | Auth + JWT | tests/core/test_auth.py | | Session CRUD | tests/services/test_dynamo_session_service.py | | Cache Service | tests/core/test_cache_service.py | | RAG Service | tests/services/test_rag_service.py |

🔁 CI/CD Pipeline

git push origin main
        │
        ├── backend/** thay đổi?
        │       │
        │   ┌───▼──────────────┐   ┌──────────────────┐
        │   │   JOB: lint      │   │   JOB: test      │  ← chạy song song
        │   │  ruff format     │   │ pytest + coverage │
        │   │  ruff check      │   │ upload artifact   │
        │   └───────┬──────────┘   └────────┬─────────┘
        │           └──────────┬────────────┘
        │                      │ cả 2 pass
        │            ┌─────────▼──────────┐
        │            │  JOB: build-push   │  ← push main only
        │            │  docker build      │
        │            │  tag: <sha>+latest │
        │            │  push → ECR        │
        │            └─────────┬──────────┘
        │                      │
        │            ┌─────────▼──────────┐
        │            │   JOB: deploy      │  ← environment: production
        │            │  ECS rolling update│
        │            │  wait stable ✓     │
        │            └────────────────────┘
        │
        └── frontend/** thay đổi?
                │
            ┌───▼──────────────────────┐
            │  JOB: validate           │
            │  tsc --noEmit + eslint   │
            └───────────┬──────────────┘
                        │
            ┌───────────▼──────────────┐
            │  JOB: deploy             │
            │  npm build               │
            │  s3 sync (immutable)     │
            │  CloudFront invalidate   │
            └──────────────────────────┘

☁️ Infrastructure (AWS)

AWS ap-southeast-2
├── VPC (10.0.0.0/16)
│   ├── Public Subnets  → ALB, NAT Gateway
│   └── Private Subnets → ECS EC2, RDS, ElastiCache
│
├── ECS Cluster (EC2 launch type)
│   └── Backend Task (FastAPI :8000)
│
├── Qdrant (ECS Fargate + EFS volume)
│
├── ALB → ECS Backend (port 8000)
├── CloudFront → S3 (frontend) + ALB (/api/*)
│
├── RDS PostgreSQL (db.t3.micro) — Auth
├── DynamoDB — Sessions + Meetings
├── ElastiCache Redis (cache.t3.micro) — Caching
├── S3 — Uploads + Wiki pages
└── ECR — Docker images

Triển khai:

cd infrastructure

terraform init
terraform plan    # kiểm tra trước
terraform apply   # tạo hạ tầng (~10-15 phút)
terraform output  # xem endpoints

Outputs quan trọng: | Output | Giá trị | |--------|---------| | cloudfront_url | URL frontend public | | alb_dns_name | Backend ALB endpoint | | redis_primary_endpoint | ElastiCache Redis | | rds_endpoint | PostgreSQL host |

📁 Cấu trúc dự án

.
├── backend/                  # FastAPI + Google ADK
│   ├── app/
│   │   ├── agents/           # ADK Agent + 9 Tools
│   │   ├── api/v1/           # REST endpoints
│   │   ├── core/             # Config, Cache, DB, DI
│   │   ├── repositories/     # Data access layer
│   │   ├── services/         # Business logic
│   │   └── schemas/          # Pydantic models
│   ├── tests/                # pytest (~40 test files)
│   ├── Dockerfile
│   └── pyproject.toml
│
├── frontend/                 # React 18 + Vite + TypeScript
│   └── src/
│       ├── api/              # Axios clients
│       ├── components/       # UI components
│       ├── hooks/            # React Query hooks
│       ├── store/            # Zustand state
│       └── types/            # TypeScript types
│
├── infrastructure/           # Terraform (AWS)
│   ├── ecs.tf                # ECS cluster + task def
│   ├── rds.tf                # PostgreSQL
│   ├── elasticache.tf        # Redis
│   ├── dynamodb.tf           # Sessions + Meetings
│   ├── s3_frontend.tf        # Frontend hosting
│   ├── alb.tf                # Load balancer
│   └── variables.tf          # Input variables
│
├── docs/                     # Documentation
│   ├── codebase.md           # Kiến trúc chi tiết
│   ├── spec.md               # Product specification
│   ├── wiki.md               # Wiki system design
│   └── cicd-flow.md          # CI/CD flow
│
├── .github/workflows/
│   ├── ci-cd.yml             # Backend CI/CD
│   └── deploy-frontend.yml   # Frontend deploy
│
└── docker-compose.yml        # Local dev stack

🛠️ Development Rules

Để đảm bảo chất lượng và deploy mượt mà:

1. 🧪 Chạy full test suite trước khi hoàn thành bất kỳ task nào:

   cd backend && uv run pytest

2. 📝 Bổ sung test case cho mọi tính năng mới (unit + integration).
3. 📚 Cập nhật docs — docs/, CLAUDE.md, README.md khi thay đổi kiến trúc.
4. 🎨 Format code trước khi commit:

   cd backend && uv run ruff format .

🌐 Environment Variables

📄 License

MIT © 2026 minh2004pd