{
    "title": "Platform Architecture Overview",
    "description": "Cái nhìn tổng quan về kiến trúc 5 lớp của Canifa AI Platform, từ giao diện người dùng đến các module API và hạ tầng dữ liệu.",
    "diagram": "diagrams/platform-architecture.svg",
    "sections": [
        {
            "title": "1. Tổng quan (Overview)",
            "type": "text",
            "content": "Canifa AI Platform được thiết kế theo mô hình <b>Micro-modular Monolith</b>. Mô hình này giúp hệ thống dễ dàng triển khai như một khối thống nhất (Monolith) nhưng lại giữ được sự tách biệt logic của từng tính năng (Micro-modular), cho phép mở rộng nhanh chóng các tính năng AI mà không làm ảnh hưởng đến lõi hệ thống."
        },
        {
            "title": "2. Kiến trúc & Luồng dữ liệu (5-Layer Stack)",
            "type": "text",
            "content": "Hệ thống chia làm 5 lớp rõ rệt:<br><br><b>1. Client Layer:</b> Trình duyệt web chạy <code>main.html</code> đóng vai trò App Shell, quản lý Navigation Sidebar, Global State (Auth Token) và Light/Dark mode.<br><b>2. Interface Layer:</b> Hệ thống sử dụng Iframe để tải các Micro-frontend (MFE). Nhờ vậy, CSS/JS của từng tính năng (Chatbot, Dashboard, Social) hoàn toàn bị cô lập, không gây conflict.<br><b>3. Gateway Layer:</b> FastAPI Router điều phối tất cả các API requests, đi qua các Middleware (Rate Limit, Auth Guard, CORS).<br><b>4. Module Layer:</b> Chứa 36+ module nghiệp vụ. Các module giao tiếp với nhau thông qua Dependency Injection và EventBus (FastStream).<br><b>5. Data Layer:</b> Database lai giữa SQLite (dành cho Local Dev & Metadata nhanh) và StarRocks/Postgres (Olap Analytics cho dữ liệu lớn)."
        },
        {
            "title": "3. Core Logic: Khởi chạy hệ thống (Lifespan)",
            "type": "text",
            "content": "Thay vì dùng <code>@app.on_event</code> kiểu cũ, hệ thống đã chuyển sang chuẩn <b>FastAPI Lifespan</b> (context manager) để quản lý Graceful Startup và Shutdown. Tại đây, các resource như Redis Cache, EventBus, Background Tasks (Social Publisher) sẽ được khởi tạo cẩn thận và đóng an toàn khi server stop, tránh hiện tượng rò rỉ bộ nhớ (Memory Leak) hoặc treo worker (Zombie process)."
        },
        {
            "title": "4. Code Snippet Thực Tế (server.py)",
            "type": "code",
            "language": "python",
            "code": "from contextlib import asynccontextmanager\nfrom fastapi import FastAPI\nfrom common.cache import redis_cache\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    # 1. Khởi tạo Redis cache\n    await redis_cache.initialize()\n    logger.info(\"✅ Redis cache initialized\")\n\n    # 2. Start EventBus & Background workers\n    await event_bus.start()\n    start_publish_engine(app)\n    \n    yield  # Server bắt đầu phục vụ requests\n\n    # 3. Cleanup khi Shutdown (Ctrl+C hoặc Reload)\n    await event_bus.stop()\n    db_pool.close_all()\n    logger.info(\"🛑 Postgres Connection Pool nicely closed\")\n\napp = FastAPI(\n    title=\"Canifa AI Platform\",\n    lifespan=lifespan,\n)"
        },
        {
            "title": "5. Danh sách API Modules quan trọng",
            "type": "api",
            "endpoints": [
                { "method": "GET", "path": "/api/auth/me", "description": "Lấy thông tin User Session và cài đặt LLM Key cá nhân." },
                { "method": "POST", "path": "/api/chat", "description": "Endpoint chính xử lý Chatbot reasoning với n8n." },
                { "method": "GET", "path": "/api/live-monitor", "description": "WebSocket endpoint bắn log Realtime." }
            ]
        },
        {
            "title": "6. Troubleshooting & Gotchas",
            "type": "text",
            "content": "<b>🚫 Lỗi không load được ảnh/SVG:</b><br>Khi code frontend, các file SVG phải được escape ký tự <code>&amp;</code> chuẩn xác, nếu không trình duyệt sẽ block không cho hiển thị. Static files được serve qua route <code>/static/{file_path:path}</code>, do đó các URL tương đối trong Iframe sẽ tự động map đúng về thư mục <code>static/</code>.<br><br><b>🚫 Lỗi treo Port (Zombie Process):</b><br>Nếu dùng uvicorn reload và gặp lỗi Port in use, nguyên nhân là do Background Tasks hoặc DB Connections không được đóng đàng hoàng ở block <code>yield</code> của Lifespan. Luôn phải gọi <code>.close()</code> trong hàm shutdown."
        }
    ]
}
