TECH_STACK.md | mdview.io

<![CDATA[<div align="center"> # 🧠 Nusa Slide — Technology Stack ### AI-Powered Presentation Generator *Arsitektur modern, scalable, dan production-ready untuk generasi presentasi berbasis AI* --- </div> ## 📋 Daftar Isi - [Ringkasan Arsitektur](#-ringkasan-arsitektur) - [System Architecture Diagram](#-system-architecture-diagram) - [Frontend Stack](#-frontend-stack) - [Backend Stack](#-backend-stack) - [AI & LLM Engine](#-ai--llm-engine) - [Database Layer](#-database-layer) - [Authentication & Security](#-authentication--security) - [DevOps & Infrastructure](#-devops--infrastructure) - [Export Pipeline](#-export-pipeline) - [Integrasi & Protokol](#-integrasi--protokol) - [Tech Stack Summary Table](#-tech-stack-summary-table) - [Kenapa Stack Ini?](#-kenapa-stack-ini) --- ## 🏗 Ringkasan Arsitektur Nusa Slide dibangun dengan arsitektur **microservice-ready monorepo** yang memisahkan concern secara jelas antara frontend, backend AI, dan export pipeline. Sistem ini dirancang untuk: - **Self-hosted** — Tidak ada vendor lock-in, deploy di mana saja - **Multi-provider AI** — Mendukung 7+ LLM provider secara plug-and-play - **Production-grade** — Docker, Nginx reverse proxy, database migration, SSO - **Extensible** — MCP protocol, REST API, custom template pipeline --- ## 🔷 System Architecture Diagram ```mermaid graph TB subgraph CLIENT["🖥️ Client Layer"] Browser["🌐 Web Browser"] end subgraph PROXY["🔀 Reverse Proxy"] Nginx["Nginx Load Balancer & Static Assets"] end subgraph FRONTEND["⚛️ Frontend — Next.js 14"] NextJS["Next.js App Router React 18 + TypeScript"] Redux["Redux Toolkit State Management"] Radix["Radix UI + Tailwind CSS Component Library"] TipTap["TipTap Editor Rich Text Editing"] Recharts["Recharts Data Visualization"] DndKit["dnd-kit Drag & Drop"] end subgraph BACKEND["🐍 Backend — FastAPI"] FastAPI["FastAPI + Uvicorn Async Python API"] LLMClient["LLM Client Multi-Provider Adapter"] DocParser["Docling Document Parsing"] ImgService["Image Generation DALL-E / Imagen / Stock"] ThemeGen["Theme Generator Color & Typography AI"] ResearchAgent["Research Agent LangGraph Workflow"] end subgraph AI_PROVIDERS["🤖 AI Providers"] OpenAI["OpenAI GPT-4o / DALL-E 3"] Google["Google Gemini 2.5 / Imagen"] Anthropic["Anthropic Claude 3.5 Sonnet"] Bedrock["AWS Bedrock Nova / Claude"] Ollama["Ollama Local LLM"] DeepSeek["DeepSeek Reasoner"] Custom["Custom Provider OpenAI-Compatible"] end subgraph DATABASE["🗄️ Database Layer"] PostgreSQL["PostgreSQL Primary Database"] SQLite["SQLite Container DB / Dev"] ChromaDB["ChromaDB Vector Store"] Redis["Redis Cache & Queue"] end subgraph EXPORT["📤 Export Pipeline"] Puppeteer["Puppeteer + Chromium HTML → Screenshot"] PythonPPTX["python-pptx PPTX Generation"] LibreOffice["LibreOffice PDF Conversion"] Sharp["Sharp Image Processing"] end subgraph AUTH["🔐 Authentication"] Keycloak["Keycloak SSO OpenID Connect"] JWT["JWT / HS256 Session Tokens"] end subgraph MCP_LAYER["🔌 MCP Protocol"] MCPServer["FastMCP Server Model Context Protocol"] end Browser --> Nginx Nginx -->|"/ (port 3000)"| NextJS Nginx -->|"/api/v1/ (port 8000)"| FastAPI Nginx -->|"/mcp/ (port 8001)"| MCPServer Nginx -->|"/static, /app_data"| Nginx NextJS --> Redux NextJS --> Radix NextJS --> TipTap NextJS --> Recharts NextJS --> DndKit FastAPI --> LLMClient FastAPI --> DocParser FastAPI --> ImgService FastAPI --> ThemeGen FastAPI --> ResearchAgent LLMClient --> OpenAI LLMClient --> Google LLMClient --> Anthropic LLMClient --> Bedrock LLMClient --> Ollama LLMClient --> DeepSeek LLMClient --> Custom FastAPI --> PostgreSQL FastAPI --> SQLite FastAPI --> ChromaDB FastAPI --> Redis FastAPI --> Puppeteer FastAPI --> PythonPPTX FastAPI --> LibreOffice Puppeteer --> Sharp FastAPI --> JWT JWT --> Keycloak MCPServer --> FastAPI style CLIENT fill:#e8f4fd,stroke:#2196F3,color:#000 style PROXY fill:#fff3e0,stroke:#FF9800,color:#000 style FRONTEND fill:#e8f5e9,stroke:#4CAF50,color:#000 style BACKEND fill:#fce4ec,stroke:#E91E63,color:#000 style AI_PROVIDERS fill:#f3e5f5,stroke:#9C27B0,color:#000 style DATABASE fill:#fff8e1,stroke:#FFC107,color:#000 style EXPORT fill:#e0f2f1,stroke:#009688,color:#000 style AUTH fill:#fbe9e7,stroke:#FF5722,color:#000 style MCP_LAYER fill:#e8eaf6,stroke:#3F51B5,color:#000 ``` --- ## 🟢 Frontend Stack ```mermaid mindmap root((Frontend)) Framework Next.js 14 React 18 TypeScript 5 App Router UI Components Radix UI Primitives Tailwind CSS 3 Lucide Icons class-variance-authority tailwind-merge State Management Redux Toolkit React Redux Rich Editing TipTap Editor tiptap-markdown react-simple-code-editor Data Visualization Recharts Mermaid.js Interaction dnd-kit Core dnd-kit Sortable react-rnd react-colorful Code Processing Babel Parser Babel Standalone Babel Traverse Zod Schema Utilities jose JWT html2canvas marked uuid sonner Toast next-themes ``` | Kategori | Teknologi | Versi | Fungsi | |----------|-----------|-------|--------| | **Framework** | Next.js | 14.x | Full-stack React framework dengan App Router | | **UI Library** | React | 18.x | Reactive UI rendering | | **Language** | TypeScript | 5.x | Type-safe development | | **Component Library** | Radix UI | Latest | 15+ accessible, unstyled primitives | | **Styling** | Tailwind CSS | 3.x | Utility-first CSS framework | | **State Management** | Redux Toolkit | 2.x | Predictable state container | | **Rich Text Editor** | TipTap | 2.x | Extensible WYSIWYG editor | | **Charts** | Recharts | 2.x | Composable chart components | | **Drag & Drop** | dnd-kit | 6.x | Modern drag-and-drop toolkit | | **Code Transform** | Babel | 7.x | Runtime JSX/TSX compilation | | **Schema Validation** | Zod | 4.x | TypeScript-first schema validation | | **Image Capture** | html2canvas | 1.x | DOM-to-canvas screenshot | | **Resize/Drag** | react-rnd | 10.x | Resizable & draggable elements | | **Icons** | Lucide React | Latest | Beautiful open-source icons | | **Diagrams** | Mermaid.js | 11.x | Diagram rendering dari text | | **Analytics** | Mixpanel | 2.x | User behavior tracking | | **Testing** | Playwright + Cypress | Latest | E2E testing | --- ## 🔴 Backend Stack ```mermaid mindmap root((Backend)) Framework FastAPI Uvicorn ASGI Python 3.11 Pydantic v2 ORM & Database SQLModel SQLAlchemy 2.0 Alembic Migrations asyncpg aiosqlite aiomysql Document Processing Docling python-pptx python-docx pdfplumber pdf2image Image Processing Pillow OpenCV Headless EasyOCR Sharp Node.js AI Framework LangChain Core LangChain AWS LangGraph LangChain Community Search Tavily API ChromaDB Utilities httpx aiohttp fonttools lxml NLTK NumPy ``` | Kategori | Teknologi | Versi | Fungsi | |----------|-----------|-------|--------| | **Framework** | FastAPI | Latest | High-performance async API framework | | **ASGI Server** | Uvicorn | Latest | Lightning-fast ASGI server | | **Language** | Python | 3.11 | Backend runtime | | **ORM** | SQLModel + SQLAlchemy | 2.0 | Async ORM dengan type hints | | **Validation** | Pydantic | v2 | Data validation & serialization | | **Migration** | Alembic | Latest | Database schema migration | | **HTTP Client** | httpx + aiohttp | Latest | Async HTTP requests | | **Document Parsing** | Docling | Latest | AI-powered document understanding | | **PDF Processing** | pdfplumber + pdf2image | Latest | PDF text & image extraction | | **PPTX Engine** | python-pptx | 1.x | PowerPoint file generation | | **DOCX Engine** | python-docx | Latest | Word document parsing | | **OCR** | EasyOCR | 1.x | Optical character recognition | | **Computer Vision** | OpenCV | 4.x | Image analysis & processing | | **NLP** | NLTK | Latest | Natural language processing | | **Font Analysis** | fonttools | Latest | Font metadata extraction | | **MCP Server** | FastMCP | 2.x | Model Context Protocol server | --- ## 🤖 AI & LLM Engine ```mermaid flowchart LR subgraph INPUT["📥 Input Sources"] Prompt["💬 Text Prompt"] Doc["📄 Document Upload"] PPTX_IN["📊 PPTX Template"] Web["🌐 Web Search"] end subgraph LLM_CLIENT["🧠 LLM Client — Multi-Provider Adapter"] direction TB Router["Provider Router"] Structured["Structured Output"] Stream["Streaming Response"] ToolCalls["Tool Calls Handler"] end subgraph PROVIDERS["☁️ Supported Providers"] direction TB P1["OpenAI — GPT-4o, GPT-4o-mini"] P2["Google — Gemini 2.5 Flash/Pro"] P3["Anthropic — Claude 3.5 Sonnet"] P4["AWS Bedrock — Nova, Claude"] P5["DeepSeek — Reasoner"] P6["Ollama — Llama, Mistral, etc."] P7["Custom — OpenAI-Compatible API"] end subgraph IMAGE_GEN["🎨 Image Generation"] direction TB I1["DALL-E 3 — OpenAI"] I2["Imagen — Google Gemini"] I3["Pexels — Stock Photos"] I4["Pixabay — Stock Photos"] I5["Custom Imagen — Ngrok/Local"] end subgraph RESEARCH["🔬 Research Agent"] direction TB Plan["📋 Plan Node"] Search["🔍 Search Node"] Eval["✅ Evaluate Node"] Synth["📝 Synthesize Node"] end subgraph PIPELINE["⚙️ Generation Pipeline"] Outline["1. Generate Outline"] Structure["2. Build Structure"] Content["3. Generate Content"] Theme["4. Generate Theme"] Slides["5. Render Slides"] Export["6. Export PPTX/PDF"] end Input --> LLM_CLIENT Prompt --> LLM_CLIENT Doc --> LLM_CLIENT Web --> RESEARCH LLM_CLIENT --> PROVIDERS Router --> Structured Router --> Stream Router --> ToolCalls RESEARCH --> Plan --> Search --> Eval --> Synth Synth --> LLM_CLIENT LLM_CLIENT --> PIPELINE Outline --> Structure --> Content --> Theme --> Slides --> Export IMAGE_GEN --> Slides style INPUT fill:#e3f2fd,stroke:#1565C0,color:#000 style LLM_CLIENT fill:#fce4ec,stroke:#C62828,color:#000 style PROVIDERS fill:#f3e5f5,stroke:#6A1B9A,color:#000 style IMAGE_GEN fill:#fff3e0,stroke:#E65100,color:#000 style RESEARCH fill:#e8f5e9,stroke:#2E7D32,color:#000 style PIPELINE fill:#e0f7fa,stroke:#00695C,color:#000 ``` ### Multi-Provider LLM Support | Provider | Model | Fitur Utama | |----------|-------|-------------| | **OpenAI** | GPT-4o, GPT-4o-mini | Structured output, tool calls, streaming | | **Google Gemini** | Gemini 2.5 Flash/Pro | Extended thinking, web grounding | | **Anthropic** | Claude 3.5 Sonnet | Deep reasoning, long context | | **AWS Bedrock** | Nova Lite/Pro, Claude | Enterprise-grade, managed infrastructure | | **DeepSeek** | Reasoner | Advanced reasoning capabilities | | **Ollama** | Llama, Mistral, dll. | 100% local, zero data leakage | | **Custom** | Any OpenAI-compatible | Bring your own endpoint | ### Research Agent (LangGraph) ```mermaid stateDiagram-v2 [*] --> Plan: User Query + Context Plan --> Search: Research Angles Search --> Evaluate: Search Results Evaluate --> Search: Need More Data Evaluate --> Synthesize: Data Sufficient Synthesize --> [*]: Enhanced Outline note right of Plan Menganalisis topik dan menentukan sudut riset end note note right of Search Tavily Web Search API untuk data real-time end note note right of Evaluate Menilai kualitas dan kelengkapan data end note note right of Synthesize Menggabungkan hasil riset menjadi outline presentasi end note ``` --- ## 🗄 Database Layer ```mermaid erDiagram POSTGRESQL ||--o{ PRESENTATIONS : stores POSTGRESQL ||--o{ TEMPLATES : stores POSTGRESQL ||--o{ IMAGE_ASSETS : stores POSTGRESQL ||--o{ USER_ACCOUNTS : stores POSTGRESQL ||--o{ ASYNC_TASKS : stores POSTGRESQL ||--o{ WEBHOOKS : stores SQLITE ||--o{ CONTAINER_CONFIG : stores SQLITE ||--o{ OLLAMA_STATUS : stores CHROMADB ||--o{ EMBEDDINGS : stores REDIS ||--o{ CACHE : stores REDIS ||--o{ QUEUE : stores PRESENTATIONS { uuid id PK uuid user_id FK json theme json slides timestamp created_at } TEMPLATES { uuid id PK string name json layout_codes json settings } USER_ACCOUNTS { uuid id PK string sso_id UK string email string fullname } ``` | Database | Engine | Fungsi | |----------|--------|--------| | **PostgreSQL** | asyncpg | Primary database — presentations, templates, users, assets | | **SQLite** | aiosqlite | Container DB — local config, Ollama status, dev fallback | | **MySQL** | aiomysql | Alternative primary DB (supported) | | **ChromaDB** | — | Vector store untuk semantic search & embeddings | | **Redis** | — | Caching layer & task queue | | **Alembic** | — | Schema migration management dengan version control | --- ## 🔐 Authentication & Security ```mermaid sequenceDiagram participant User as 🧑 User participant Next as ⚛️ Next.js participant API as 🐍 FastAPI participant KC as 🔑 Keycloak SSO participant DB as 🗄️ PostgreSQL User->>Next: Login Request Next->>KC: Redirect to SSO KC->>User: Login Page User->>KC: Credentials KC->>Next: Authorization Code Next->>KC: Exchange Code → Access Token Next->>API: POST /auth/sso (token) API->>KC: Verify via Userinfo Endpoint KC-->>API: User Payload (sub, email, name) API->>DB: Upsert UserAccount (sso_id) API->>API: Create Session Token (HS256) API-->>Next: Set session_token Cookie Next-->>User: Authenticated ✅ Note over API: Subsequent requests use session_token (HS256) cookie for fast local verification ``` | Komponen | Teknologi | Detail | |----------|-----------|--------| | **SSO Provider** | Keycloak | OpenID Connect, PKCE flow | | **Token Format** | JWT (RS256 + HS256) | Keycloak RS256, Session HS256 | | **Session Management** | Cookie-based | HttpOnly, configurable TTL (7 days default) | | **Token Verification** | Dual strategy | HS256 → local verify, RS256 → Keycloak userinfo | | **User Ownership** | Row-level | user_id FK di semua tabel utama | | **JWT Library** | PyJWT + jose | Backend Python + Frontend JS | --- ## 🐳 DevOps & Infrastructure ```mermaid flowchart TB subgraph DEV["🛠️ Development"] Local["Local Dev Node.js + Python venv"] DockerDev["Docker Compose dev profile"] end subgraph BUILD["🔨 Build Pipeline"] GitLab["GitLab CI/CD"] DockerBuild["Docker Build Multi-stage"] end subgraph RUNTIME["🚀 Production Runtime"] DockerProd["Docker Container"] NginxRT["Nginx Reverse Proxy"] NodeStart["Node.js Orchestrator start.js"] NextProd["Next.js :3000"] FastAPIProd["FastAPI :8000"] MCPProd["MCP Server :8001"] end subgraph INFRA["☁️ Infrastructure"] EC2["AWS EC2 Ubuntu Server"] Volumes["Docker Volumes /app_data"] end Local --> DockerDev DockerDev --> GitLab GitLab -->|"staging branch"| DockerBuild DockerBuild --> DockerProd DockerProd --> NginxRT DockerProd --> NodeStart NodeStart --> NextProd NodeStart --> FastAPIProd NodeStart --> MCPProd DockerProd --> EC2 DockerProd --> Volumes style DEV fill:#e8f5e9,stroke:#388E3C,color:#000 style BUILD fill:#fff3e0,stroke:#F57C00,color:#000 style RUNTIME fill:#e3f2fd,stroke:#1976D2,color:#000 style INFRA fill:#fce4ec,stroke:#D32F2F,color:#000 ``` | Komponen | Teknologi | Detail | |----------|-----------|--------| | **Containerization** | Docker | Multi-stage build, Python 3.11 slim base | | **Orchestration** | Docker Compose | Dev & prod profiles | | **Reverse Proxy** | Nginx | Load balancing, static assets, WebSocket support | | **Process Manager** | Node.js (start.js) | Orchestrates Next.js + FastAPI + MCP | | **CI/CD** | GitLab CI | Auto-deploy ke staging via SSH | | **Base Image** | python:3.11-slim-bookworm | Minimal footprint | | **System Dependencies** | LibreOffice, Chromium, Poppler | Document conversion & rendering | | **Package Manager** | npm + uv (Python) | Fast, reliable dependency management | --- ## 📤 Export Pipeline ```mermaid flowchart LR subgraph INPUT["Slide Data"] JSON["JSON Slide Model"] HTML["HTML + Tailwind CSS"] TSX["TSX Components"] end subgraph RENDER["Rendering Engine"] Babel_R["Babel TSX → JS Runtime"] Puppeteer_R["Puppeteer + Chromium HTML → Screenshot"] Sharp_R["Sharp Image Optimization"] end subgraph CONVERT["Conversion"] PPTX_C["python-pptx PPTX Generation"] LO["LibreOffice PPTX → PDF"] Poppler["Poppler Utils PDF Processing"] end subgraph OUTPUT["📦 Output"] PPTX_O["📊 .pptx"] PDF_O["📄 .pdf"] PNG_O["🖼️ .png Thumbnails"] end JSON --> Babel_R --> Puppeteer_R --> Sharp_R HTML --> Puppeteer_R TSX --> Babel_R Sharp_R --> PPTX_C --> PPTX_O PPTX_C --> LO --> PDF_O Sharp_R --> PNG_O Puppeteer_R --> Poppler style INPUT fill:#e8eaf6,stroke:#283593,color:#000 style RENDER fill:#fce4ec,stroke:#AD1457,color:#000 style CONVERT fill:#e0f2f1,stroke:#00695C,color:#000 style OUTPUT fill:#f1f8e9,stroke:#558B2F,color:#000 ``` --- ## 🔌 Integrasi & Protokol ```mermaid flowchart TB subgraph API_LAYER["🌐 API Endpoints"] REST["REST API /api/v1/*"] SSE["Server-Sent Events Streaming Responses"] WS["WebSocket Real-time Updates"] MCP["MCP Protocol /mcp/*"] end subgraph EXTERNAL["🔗 External Services"] Tavily["Tavily Web Search API"] Pexels["Pexels API Stock Photos"] Pixabay["Pixabay API Stock Photos"] GoogleFonts["Google Fonts Font CDN"] ICCN["ICCN API Organization Integration"] end subgraph PROTOCOLS["📡 Protocols"] OIDC["OpenID Connect SSO Authentication"] PKCE["PKCE Flow Secure Auth Code"] JWT_P["JWT RS256/HS256 Token Verification"] end REST --> Tavily REST --> Pexels REST --> Pixabay REST --> GoogleFonts REST --> ICCN MCP --> REST OIDC --> PKCE --> JWT_P style API_LAYER fill:#e3f2fd,stroke:#1565C0,color:#000 style EXTERNAL fill:#f3e5f5,stroke:#7B1FA2,color:#000 style PROTOCOLS fill:#fff8e1,stroke:#F9A825,color:#000 ``` --- ## 📊 Tech Stack Summary Table ```mermaid pie title Distribusi Teknologi per Layer "Frontend (Next.js + React)" : 30 "Backend (FastAPI + Python)" : 25 "AI/LLM Engine" : 20 "Database & Storage" : 10 "DevOps & Infra" : 10 "Auth & Security" : 5 ``` | Layer | Teknologi Utama | Bahasa | Highlight | |-------|----------------|--------|-----------| | **Frontend** | Next.js 14, React 18, Redux Toolkit, Radix UI, Tailwind CSS, TipTap, Recharts, dnd-kit | TypeScript | SSR/SSG, App Router, 15+ Radix primitives | | **Backend** | FastAPI, Uvicorn, SQLModel, Alembic, Pydantic v2 | Python 3.11 | Fully async, auto-generated OpenAPI docs | | **AI Engine** | LLMClient (custom), LangGraph, LangChain | Python | 7 provider, structured output, streaming, tool calls | | **Image AI** | DALL-E 3, Imagen, Pexels, Pixabay, Custom | Multi | Multi-provider image generation | | **Database** | PostgreSQL, SQLite, MySQL, ChromaDB, Redis | SQL + Vector | Multi-engine support, async drivers | | **Auth** | Keycloak SSO, JWT (RS256 + HS256), PKCE | — | Enterprise SSO, session tokens | | **Export** | python-pptx, Puppeteer, LibreOffice, Sharp | Python + Node.js | PPTX, PDF, PNG output | | **Protocol** | REST, SSE, WebSocket, MCP (Model Context Protocol) | — | Real-time streaming, AI agent integration | | **DevOps** | Docker, Docker Compose, Nginx, GitLab CI | YAML | One-command deploy, auto-migration | | **Doc Parsing** | Docling, pdfplumber, EasyOCR, OpenCV | Python | AI document understanding, OCR | | **Testing** | Playwright, Cypress, Pytest | TS + Python | E2E + unit testing | --- ## 💡 Kenapa Stack Ini? ### Keputusan Arsitektur Kunci ```mermaid mindmap root((Design Decisions)) Performance FastAPI async Uvicorn ASGI Nginx reverse proxy Redis caching Streaming SSE Flexibility 7+ LLM providers 3 database engines 5 image providers Custom templates MCP protocol Security Keycloak SSO JWT dual strategy Row-level ownership PKCE auth flow Session cookies Developer Experience TypeScript frontend Pydantic validation Auto OpenAPI docs Alembic migrations Docker one-command Scalability Async everywhere Stateless backend Container-ready Database agnostic Horizontal scaling ``` | Keputusan | Alasan | |-----------|--------| | **Next.js + FastAPI** | Best of both worlds — React SSR untuk UX, Python untuk AI/ML ecosystem | | **Multi-provider LLM** | Tidak ada vendor lock-in, user pilih provider sesuai kebutuhan & budget | | **SQLModel + Alembic** | Type-safe ORM dengan migration management yang mature | | **Keycloak SSO** | Enterprise-grade auth tanpa build from scratch | | **Docker + Nginx** | Production-ready deployment dalam satu command | | **LangGraph** | Stateful research agent dengan graph-based workflow | | **MCP Protocol** | Standar terbuka untuk integrasi dengan AI agents (Claude, dll.) | | **Puppeteer + python-pptx** | Pixel-perfect slide rendering + native PPTX generation | --- <div align="center"> ### 🚀 Built with Modern Tech for the AI Era *Nusa Slide — Open Source AI Presentation Generator* **Next.js** · **FastAPI** · **LangGraph** · **Multi-LLM** · **Docker** · **Keycloak SSO** --- *Dokumen ini di-generate berdasarkan analisis codebase aktual project Nusa Slide* *Last updated: April 2026* </div> ]]>