# hddevteam/smart-form-filler architecture

> Architecture diagram of the GitHub repository hddevteam/smart-form-filler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hddevteam/smart-form-filler
- Repository: https://github.com/hddevteam/smart-form-filler

## Overview

Smart Form Filler is a browser extension backed by an API service: users extract page content, chat with that data, and analyze and fill web forms using selectable cloud or local AI models. The extension also manages backend settings and connection status. The graph includes the documented popup modules and backend API/AI layers; some extension wiring and backend route details are not shown in the excerpts, so uncertain edges are omitted.

Main entry points: [`extension/src/modules/popupManager.js`](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupManager.js) (Popup coordinator), [`backend/routes/api.js`](https://github.com/hddevteam/smart-form-filler/blob/main/backend/routes/api.js) (API routes), [`backend/services/gptService/modelAdapters/AdapterFactory.js`](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/AdapterFactory.js) (Adapter selection), [`backend/services/gptService/apiService.js`](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/apiService.js) (LLM requests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension_ui["Extension experience"]
  node_popup_entry["Popup entry<br/>[popup-main.js]"]
  node_popup_manager["Popup coordinator<br/>[popupManager.js]"]
  node_popup_events["Popup events"]
  node_popup_models["Model selection"]
  node_popup_settings["Backend settings"]
  node_ui_controller["UI state<br/>[uiController.js]"]
  node_results["Results display<br/>[resultsHandler.js]"]
  node_api_client["API client<br/>[apiClient.js]"]
end

subgraph group_page_features["Page features"]
  node_extractor["Page extraction<br/>[dataExtractor.js]"]
  node_chat["Data chat<br/>[chatHandler.js]"]
  node_form_handler["Form filling"]
  node_form_analysis["Form analysis"]
  node_form_detection["Form detection"]
end

subgraph group_backend_api["Backend API"]
  node_backend["Backend server<br/>[server.js]"]
  node_api_routes["API routes<br/>[api.js]"]
  node_extraction_controller["Extraction API"]
  node_analysis_controller["Data analysis"]
  node_form_controller["Form analysis API"]
  node_core_controller["Model and health API"]
end

subgraph group_ai_service["AI services"]
  node_gpt_config["Model configuration<br/>[config.js]"]
  node_gpt_api["LLM requests<br/>[apiService.js]"]
  node_adapter_factory["Adapter selection<br/>[AdapterFactory.js]"]
  node_base_adapter["Adapter interface<br/>[BaseAdapter.js]"]
  node_ollama_adapter["Ollama adapter<br/>[OllamaAdapter.js]"]
  node_deepseek_adapter["DeepSeek adapter<br/>[DeepSeekAdapter.js]"]
  node_oseries_adapter["O-series adapter<br/>[OSeriesAdapter.js]"]
  node_templates["Prompt templates<br/>[templates.js]"]
end

node_user(("Browser user"))
node_local_ollama(("Ollama service"))
node_cloud_models(("Cloud AI providers"))

node_user -->|"opens extension"| node_popup_entry
node_popup_entry -->|"initializes"| node_popup_manager
node_popup_manager -->|"coordinates"| node_popup_events
node_popup_manager -->|"manages models"| node_popup_models
node_popup_manager -->|"manages settings"| node_popup_settings
node_popup_manager -->|"coordinates"| node_form_handler
node_popup_manager -->|"coordinates"| node_ui_controller
node_popup_manager -->|"coordinates"| node_results
node_user -->|"requests extraction"| node_extractor
node_user -->|"asks about data"| node_chat
node_user -->|"requests filling"| node_form_handler
node_form_handler -->|"detects fields"| node_form_detection
node_form_handler -->|"maps form fields"| node_form_analysis
node_extractor -->|"sends extraction request"| node_api_client
node_chat -->|"sends chat request"| node_api_client
node_form_analysis -->|"requests mapping"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"mounts routes"| node_api_routes
node_api_routes -->|"routes requests"| node_extraction_controller
node_api_routes -->|"routes requests"| node_analysis_controller
node_api_routes -->|"routes requests"| node_form_controller
node_api_routes -->|"routes requests"| node_core_controller
node_analysis_controller -->|"requests model response"| node_gpt_api
node_form_controller -->|"requests model response"| node_gpt_api
node_core_controller -->|"loads model configuration"| node_gpt_config
node_gpt_api -->|"reads model settings"| node_gpt_config
node_gpt_api -->|"selects adapter"| node_adapter_factory
node_adapter_factory -->|"creates adapter"| node_base_adapter
node_adapter_factory -->|"creates adapter"| node_deepseek_adapter
node_adapter_factory -->|"creates adapter"| node_oseries_adapter
node_adapter_factory -->|"creates adapter"| node_ollama_adapter
node_ollama_adapter -->|"extends"| node_base_adapter
node_gpt_config -->|"discovers local models"| node_ollama_adapter
node_ollama_adapter -->|"calls local API"| node_local_ollama
node_gpt_api -->|"sends model requests"| node_cloud_models

click node_popup_entry "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/popup-main.js"
click node_popup_manager "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupManager.js"
click node_popup_events "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupEventHandlers.js"
click node_popup_models "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupModelManager.js"
click node_popup_settings "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupSettingsManager.js"
click node_ui_controller "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/uiController.js"
click node_results "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/resultsHandler.js"
click node_extractor "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/dataExtractor.js"
click node_chat "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/chatHandler.js"
click node_form_handler "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/formFillerHandler.js"
click node_form_analysis "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/formAnalysisService.js"
click node_form_detection "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/formDetectionService.js"
click node_api_client "https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/api/apiClient.js"
click node_backend "https://github.com/hddevteam/smart-form-filler/blob/main/backend/server.js"
click node_api_routes "https://github.com/hddevteam/smart-form-filler/blob/main/backend/routes/api.js"
click node_extraction_controller "https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/dataExtractionController.js"
click node_analysis_controller "https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/dataAnalysisController.js"
click node_form_controller "https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/formFillerController.js"
click node_core_controller "https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/extensionCoreController.js"
click node_gpt_config "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/config.js"
click node_gpt_api "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/apiService.js"
click node_adapter_factory "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/AdapterFactory.js"
click node_base_adapter "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/BaseAdapter.js"
click node_ollama_adapter "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/OllamaAdapter.js"
click node_deepseek_adapter "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/DeepSeekAdapter.js"
click node_oseries_adapter "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/OSeriesAdapter.js"
click node_templates "https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/templates.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_popup_entry,node_popup_manager,node_popup_events,node_popup_models,node_popup_settings,node_ui_controller,node_results,node_api_client,node_user toneBlue
class node_extractor,node_chat,node_form_handler,node_form_analysis,node_form_detection toneAmber
class node_backend,node_api_routes,node_extraction_controller,node_analysis_controller,node_form_controller,node_core_controller toneMint
class node_gpt_config,node_gpt_api,node_adapter_factory,node_base_adapter,node_ollama_adapter,node_deepseek_adapter,node_oseries_adapter,node_templates toneRose
class node_local_ollama,node_cloud_models toneIndigo
```

## Components

### Extension experience

- [Popup entry](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/popup-main.js): `extension/src/popup-main.js`
- [Popup coordinator](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupManager.js): `extension/src/modules/popupManager.js`
- [Popup events](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupEventHandlers.js): `extension/src/modules/popupEventHandlers.js`
- [Model selection](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupModelManager.js): `extension/src/modules/popupModelManager.js`
- [Backend settings](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/popupSettingsManager.js): `extension/src/modules/popupSettingsManager.js`
- [UI state](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/uiController.js): `extension/src/modules/uiController.js`
- [Results display](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/resultsHandler.js): `extension/src/modules/resultsHandler.js`
- [API client](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/api/apiClient.js): `extension/src/api/apiClient.js`

### Page features

- [Page extraction](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/dataExtractor.js): `extension/src/modules/dataExtractor.js`
- [Data chat](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/chatHandler.js): `extension/src/modules/chatHandler.js`
- [Form filling](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/formFillerHandler.js): `extension/src/modules/formFillerHandler.js`
- [Form analysis](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/formAnalysisService.js): `extension/src/modules/formAnalysisService.js`
- [Form detection](https://github.com/hddevteam/smart-form-filler/blob/main/extension/src/modules/formDetectionService.js): `extension/src/modules/formDetectionService.js`

### Backend API

- [Backend server](https://github.com/hddevteam/smart-form-filler/blob/main/backend/server.js): `backend/server.js`
- [API routes](https://github.com/hddevteam/smart-form-filler/blob/main/backend/routes/api.js): `backend/routes/api.js`
- [Extraction API](https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/dataExtractionController.js): `backend/controllers/dataExtractionController.js`
- [Data analysis](https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/dataAnalysisController.js): `backend/controllers/dataAnalysisController.js`
- [Form analysis API](https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/formFillerController.js): `backend/controllers/formFillerController.js`
- [Model and health API](https://github.com/hddevteam/smart-form-filler/blob/main/backend/controllers/extensionCoreController.js): `backend/controllers/extensionCoreController.js`

### AI services

- [Model configuration](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/config.js): `backend/services/gptService/config.js`
- [LLM requests](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/apiService.js): `backend/services/gptService/apiService.js`
- [Adapter selection](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/AdapterFactory.js): `backend/services/gptService/modelAdapters/AdapterFactory.js`
- [Adapter interface](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/BaseAdapter.js): `backend/services/gptService/modelAdapters/BaseAdapter.js`
- [Ollama adapter](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/OllamaAdapter.js): `backend/services/gptService/modelAdapters/OllamaAdapter.js`
- [DeepSeek adapter](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/DeepSeekAdapter.js): `backend/services/gptService/modelAdapters/DeepSeekAdapter.js`
- [O-series adapter](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/modelAdapters/OSeriesAdapter.js): `backend/services/gptService/modelAdapters/OSeriesAdapter.js`
- [Prompt templates](https://github.com/hddevteam/smart-form-filler/blob/main/backend/services/gptService/templates.js): `backend/services/gptService/templates.js`

### Other components

- **Browser user**
- **Ollama service**
- **Cloud AI providers**

## Connections

- Browser user → Popup entry: opens extension (evidence: `README.md`)
- Popup entry → Popup coordinator: initializes (evidence: `README.md`)
- Popup coordinator → Popup events: coordinates (evidence: `README.md`)
- Popup coordinator → Model selection: manages models (evidence: `README.md`)
- Popup coordinator → Backend settings: manages settings (evidence: `README.md`)
- Popup coordinator → Form filling: coordinates (evidence: `README.md`)
- Popup coordinator → UI state: coordinates (evidence: `README.md`)
- Popup coordinator → Results display: coordinates (evidence: `README.md`)
- Browser user → Page extraction: requests extraction (evidence: `README.md`)
- Browser user → Data chat: asks about data (evidence: `README.md`)
- Browser user → Form filling: requests filling (evidence: `README.md`)
- Form filling → Form detection: detects fields (evidence: `README.md`)
- Form filling → Form analysis: maps form fields (evidence: `README.md`)
- Page extraction → API client: sends extraction request (evidence: `README.md`)
- Data chat → API client: sends chat request (evidence: `README.md`)
- Form analysis → API client: requests mapping (evidence: `README.md`)
- API client → Backend server: calls API (evidence: `README.md`)
- Backend server → API routes: mounts routes (evidence: `backend/server.js`)
- API routes → Extraction API: routes requests (evidence: `backend/routes/api.js`)
- API routes → Data analysis: routes requests (evidence: `backend/routes/api.js`)
- API routes → Form analysis API: routes requests (evidence: `backend/routes/api.js`)
- API routes → Model and health API: routes requests (evidence: `backend/routes/api.js`)
- Data analysis → LLM requests: requests model response (evidence: `backend/controllers/dataAnalysisController.js`)
- Form analysis API → LLM requests: requests model response (evidence: `backend/controllers/formFillerController.js`)
- Model and health API → Model configuration: loads model configuration (evidence: `backend/controllers/extensionCoreController.js`)
- LLM requests → Model configuration: reads model settings (evidence: `backend/services/gptService/apiService.js`)
- LLM requests → Adapter selection: selects adapter (evidence: `backend/services/gptService/apiService.js`)
- Adapter selection → Adapter interface: creates adapter (evidence: `backend/services/gptService/modelAdapters/AdapterFactory.js`)
- Adapter selection → DeepSeek adapter: creates adapter (evidence: `backend/services/gptService/modelAdapters/AdapterFactory.js`)
- Adapter selection → O-series adapter: creates adapter (evidence: `backend/services/gptService/modelAdapters/AdapterFactory.js`)
- Adapter selection → Ollama adapter: creates adapter (evidence: `backend/services/gptService/modelAdapters/AdapterFactory.js`)
- Ollama adapter → Adapter interface: extends (evidence: `backend/services/gptService/modelAdapters/OllamaAdapter.js`)
- Model configuration → Ollama adapter: discovers local models (evidence: `backend/services/gptService/config.js`)
- Ollama adapter → Ollama service: calls local API (evidence: `backend/services/gptService/modelAdapters/OllamaAdapter.js`)
- LLM requests → Cloud AI providers: sends model requests (evidence: `backend/services/gptService/apiService.js`)