docs/architecture/03-component-diagram.md

03 — Component Diagram

Overview

This diagram shows how BAYAN's software components are organized and interact across Frontend, API, NLP, and Data layers.

Component Diagram

graph TB
    subgraph "Frontend SPA"
        direction TB
        subgraph "Pages"
            HOME["🏠 Landing Page"]
            FEATURES["⚡ Features Page"]
            EDITOR_PAGE["📝 Editor Page"]
            PRICING["💰 Pricing Page"]
            P404["🚫 404 Page"]
        end

        subgraph "Editor Core"
            EDITOR["editor.js<br/>State · Undo/Redo · Analysis"]
            RENDERER["renderer.js<br/>Error Highlighting · Spans"]
            SELECTION["selection.js<br/>Caret · Range · Offset"]
            FORMAT["format.js<br/>Bold · Italic · Lists · Colors"]
        end

        subgraph "Auth System"
            AUTH_GATE["Auth Gate<br/>Login Modal"]
            AUTH_JS["auth.js<br/>Guest · Google · Link"]
            AUTH_UI["auth-ui.js<br/>Menu · Avatar · Banner"]
            SESSION["session.js<br/>Token Refresh"]
            SB_CLIENT["client.js<br/>Supabase Init"]
        end

        subgraph "Data Modules"
            DOC_API["documents-api.js<br/>CRUD Operations"]
            DOC_UI["documents-ui.js<br/>Sidebar · List · Search"]
            DOC_STATE["documents-state.js<br/>Current Doc Tracking"]
            SUMM_API["summaries-api.js<br/>Save · Load · Delete"]
            SUMM_UI_MOD["summaries-ui.js<br/>Display · Export TXT"]
            SET_API["settings-api.js<br/>Load · Save"]
            SET_SYNC["settings-sync.js<br/>Apply · Sync"]
        end

        subgraph "Sync Engine"
            SYNC_MGR["sync-manager.js<br/>Online/Offline"]
            SYNC_Q["sync-queue.js<br/>Operation Queue"]
            SYNC_RES["sync-resolver.js<br/>Conflict Resolution"]
        end

        subgraph "Utilities"
            API_JS["api.js<br/>HTTP Client"]
            THEME["theme.js<br/>Dark/Light Toggle"]
            UI_JS["ui.js<br/>Toast · Score · Suggestions"]
        end
    end

    subgraph "API Layer (Flask)"
        FLASK["Flask App<br/>app.py"]
        
        subgraph "Endpoints"
            E_HEALTH["/api/health"]
            E_ANALYZE["/api/analyze"]
            E_SPELL["/api/spelling"]
            E_GRAMMAR["/api/grammar"]
            E_PUNCT["/api/punctuation"]
            E_SUMMARY["/api/summarize"]
            E_AUTO["/api/autocomplete"]
            E_DEBUG["/api/debug/models"]
        end
    end

    subgraph "NLP Services"
        LOADER["model_loader.py<br/>Lazy Loading · Caching"]
        
        subgraph "Models"
            M_SPELL["AraSpell<br/>araspell_service.py<br/>araspell_rules.py"]
            M_GRAM["Grammar Service<br/>grammar_service.py"]
            M_PUNCT["PuncAra-v1<br/>Punctuation Model"]
            M_AUTO["AutoComplete<br/>Language Model"]
            M_SUMM["Summarization<br/>MBart (float16)"]
        end

        HF_API["hf_inference.py<br/>Remote HF API Fallback"]
    end

    subgraph "Data Layer"
        SUPABASE["Supabase<br/>PostgreSQL + Auth + RLS"]
        LOCALSTORAGE["localStorage<br/>Drafts · Goals · Dismissed"]
    end

    %% Connections
    EDITOR --> API_JS
    API_JS --> FLASK
    FLASK --> E_HEALTH & E_ANALYZE & E_SPELL & E_GRAMMAR & E_PUNCT & E_SUMMARY & E_AUTO

    E_ANALYZE --> LOADER
    E_SPELL --> LOADER
    E_GRAMMAR --> LOADER
    E_PUNCT --> LOADER
    E_SUMMARY --> LOADER
    E_AUTO --> LOADER

    LOADER --> M_SPELL & M_GRAM & M_PUNCT & M_AUTO & M_SUMM
    LOADER --> HF_API

    DOC_API --> SUPABASE
    SUMM_API --> SUPABASE
    SET_API --> SUPABASE
    AUTH_JS --> SUPABASE
    SYNC_MGR --> DOC_API

    EDITOR --> LOCALSTORAGE

    style FLASK fill:#059669,color:#fff
    style SUPABASE fill:#3B82F6,color:#fff
    style LOADER fill:#7C3AED,color:#fff

Component Responsibilities

Component	Files	Responsibility
Editor Core	editor.js, renderer.js, selection.js, format.js	Text editing, error highlighting, formatting
Auth System	auth.js, auth-ui.js, session.js, client.js, config.js	Authentication flow, session management
Documents	documents-api.js, documents-ui.js, documents-state.js	Document CRUD, sidebar, search
Summaries	summaries-api.js, summaries-ui.js	Summary storage and display
Settings	settings-api.js, settings-sync.js	User preferences persistence
Sync Engine	sync-manager.js, sync-queue.js, sync-resolver.js	Offline support, conflict resolution
API Client	api.js	HTTP request abstraction
Flask API	app.py	8 REST endpoints
NLP Services	model_loader.py, araspell_service.py, hf_inference.py	Model loading, inference

Extension Points

• New pages: Add HTML section + showPage() entry.
• New NLP model: Add to model_loader.py + new /api/ route.
• New Supabase table: Add migration SQL + API module + UI module.