# C4-Container Architecture (Developer Onboarding)

Diagram ini berada pada Level B (setara dengan C4-Container). Diagram ini berfungsi sebagai "jembatan" bagi *developer* yang baru bergabung. Fokusnya bukan pada aliran data yang sangat detail, melainkan pada **peta modul atau komponen utama (Containers)** di dalam *source code*, apa tanggung jawab mereka, dan bagaimana mereka saling berkomunikasi.

```mermaid
flowchart TB
    classDef externalSystem fill:#8C84FA,stroke:#232F3E,stroke-width:2px,color:#FFFFFF,rx:5px,ry:5px;
    classDef database fill:#3355CC,stroke:#232F3E,stroke-width:2px,color:#FFFFFF,rx:5px,ry:5px;
    classDef container fill:#00A4A6,stroke:#232F3E,stroke-width:2px,color:#FFFFFF,rx:5px,ry:5px;
    classDef orchestrator fill:#FF9900,stroke:#232F3E,stroke-width:2px,color:#FFFFFF,rx:5px,ry:5px;

    %% Boundary Sistem Backend SRE
    subgraph SystemBoundary ["📦 Backend SRE System (Python / Server)"]
        direction TB
        
        Orchestrator["⚙️ Ingestion Orchestrator<br/>[app/services/ingestion.py]<br/>Pengendali utama yang mengatur<br/>alur kerja asinkron and sinkron."]:::orchestrator
        
        subgraph ParserServices ["🛠️ Parser and Processing Services"]
            direction TB
            HybridParser["📑 Hybrid Parser<br/>[hybrid_parser.py]<br/>PDF to Raw Markdown<br/>(PyMuPDF + RapidOCR)"]:::container
            SmartChunker["✂️ Smart Chunker<br/>[smart_chunker.py]<br/>Markdown to Chunks<br/>and JIT Purification"]:::container
            Retriever["🔍 Semantic Retriever<br/>[semantic_retriever.py]<br/>Local Embedding (E5-Small)<br/>and Anchor-Density Search"]:::container
            LLMExtractor["🧠 LLM Extractor<br/>[llm_extractor.py]<br/>Pydantic Validation<br/>and Prompt Engineering"]:::container
        end
        
        subgraph StorageServices ["💾 Storage and Maintenance Services"]
            direction TB
            SupabaseWorker["⚡ Supabase Uploader<br/>[supabase_client.py]<br/>Async Background Worker<br/>via Queue"]:::container
            CronWorker["⏱️ Global Threshold Updater<br/>[update_global_threshold.py]<br/>Cron Job (Z-Score Math)"]:::container
        end
        
        %% Hubungan Internal
        Orchestrator -->|Meminta teks Markdown| HybridParser
        Orchestrator -->|Meminta pemotongan data| SmartChunker
        Orchestrator -->|Meminta pencarian lokal| Retriever
        Orchestrator -->|Meminta ekstraksi pilar| LLMExtractor
        Orchestrator -->|Mengirim Raw Chunks| SupabaseWorker
    end

    %% Aktor / Data Eksternal
    PDFs["📁 Input PDFs<br/>[Local Filesystem]"]:::externalSystem
    Thresholds["⚙️ thresholds.json<br/>[Local File]"]:::externalSystem
    
    DashScope["🤖 Alibaba DashScope API<br/>[Qwen LLM]"]:::externalSystem
    OpenAI["🤖 OpenAI API<br/>[text-embedding-3-small]"]:::externalSystem
    
    Neo4j[("🕸️ Neo4j AuraDB<br/>[Vector and Graph DB]")]:::database
    SupabaseDB[("🗄️ Supabase<br/>[PostgreSQL]")]:::database

    %% Hubungan ke Luar Sistem
    PDFs -->|Dibaca oleh| Orchestrator
    Thresholds -.->|Dibaca oleh| Orchestrator
    CronWorker -->|Menulis ke| Thresholds
    
    LLMExtractor <-->|REST API| DashScope
    Orchestrator <-->|REST API| OpenAI
    
    Orchestrator <-->|Cypher Query MERGE and Search| Neo4j
    CronWorker <-->|Cypher Query Sampling| Neo4j
    
    SupabaseWorker -->|PostgreSQL Insert| SupabaseDB
```

### Panduan bagi Developer Baru:
1. **Ingestion Orchestrator (`ingestion.py`):** Ini adalah jantung dari aplikasi. Jika Anda ingin mencari tahu di mana semua proses dipanggil dan disatukan (termasuk *ThreadPoolExecutor*), mulailah dari sini.
2. **Parser & Processing Services (`app/services/parser/`):** Direktori ini berisi modul-modul pekerja spesialis. 
   - Modifikasi cara membaca PDF? Buka `hybrid_parser.py`.
   - Modifikasi Regex untuk membersihkan teks *noise*? Buka `smart_chunker.py`.
   - Ingin mengubah model pencarian lokal (E5-Small)? Buka `semantic_retriever.py`.
   - Ingin mengubah tata bahasa (*prompt*) untuk AI? Buka `llm_extractor.py`.
3. **Storage Services:** Proses yang menangani database. Khusus untuk penyimpanan *Raw Chunks* ke Supabase, sistem ini menggunakan arsitektur antrean (*Queue* dan *Daemon Thread*) di `supabase_client.py` agar tidak memblokir laju *Ingestion Pipeline* utama.
4. **Maintenance (Cron):** Skrip `update_global_threshold.py` hidup di luar *pipeline* utama dan didesain untuk dipicu oleh penjadwal sistem operasi (seperti `crontab`).
