# fillin-dev/fillin architecture

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

- Interactive diagram: https://gitdiagram.com/fillin-dev/fillin
- Repository: https://github.com/fillin-dev/fillin

## Overview

Fillin’s main product is a local-first Chrome extension: users create and organize text, template, and visual snippets, then expand them in web editors through keyboard shortcuts or the in-page palette/suggestions. The popup manages the library and settings; content-script coordination detects triggers, adapts editor fields, resolves templates, and inserts results. Media, backups, stats, blacklist, and the independent landing site are distinct capabilities. Edges cite only shown calls or README-described behavior; unsampled relationships are omitted or marked unverified.

Main entry points: [`apps/extension/src/popup/App.tsx`](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/popup/App.tsx) (Popup UI), [`apps/extension/src/content/suggestions/SuggestionController.ts`](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/suggestions/SuggestionController.ts) (Shortcut suggestions), [`apps/extension/src/services/MediaSnippetService.ts`](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/MediaSnippetService.ts) (Visual snippet service), [`apps/extension/src/content/expansion/ExpansionCoordinator.ts`](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/expansion/ExpansionCoordinator.ts) (Expansion coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_popup["Library management"]
  node_popup_app["Popup UI<br/>[App.tsx]"]
  node_snippet_form["Snippet editor<br/>[SnippetForm.tsx]"]
  node_snippet_list["Snippet library list<br/>[SnippetList.tsx]"]
  node_blacklist_ui["Blacklist settings<br/>[BlacklistModal.tsx]"]
  node_onboarding["First-use guide<br/>[FirstUseGuide.tsx]"]
end

subgraph group_runtime["Page expansion"]
  node_content_script["Content script<br/>[index.ts]"]
  node_suggestions["Shortcut suggestions"]
  node_expansion["Expansion coordinator"]
  node_adapter_factory["Editor adapter selection<br/>[AdapterFactory.ts]"]
  node_google_docs["Google Docs adapter"]
  node_template_flow["Template interaction<br/>[TemplateDialog.ts]"]
  node_inline_edit["Inline placeholders<br/>[InlineSession.ts]"]
  node_shared_engine["Trigger and replacement engine<br/>[detector.ts]"]
  node_template_resolver["Template resolver<br/>[resolveTemplate.ts]"]
end

subgraph group_data["Local data"]
  node_services["Snippet and settings services<br/>[SnippetService.ts]"]
  node_blacklist_service["Blacklist service"]
  node_stats_service["Usage statistics<br/>[StatsService.ts]"]
  node_snippet_store[("Snippet repository")]
  node_chrome_store[("Chrome local storage")]
end

subgraph group_media_backup["Media and backup"]
  node_media_service["Visual snippet service"]
  node_media_store[("Media asset store")]
  node_media_prepare["Media preparation<br/>[prepareMedia.ts]"]
  node_backup_service["Backup and restore<br/>[BackupService.ts]"]
  node_backup_controls["Backup controls<br/>[BackupControls.tsx]"]
end

subgraph group_web["Public website"]
  node_landing["Marketing and install site<br/>[App.tsx]"]
  node_landing_api["Optional health API<br/>[app.ts]"]
end

node_user(("Extension user"))
node_page_user(("Website visitor"))
node_browser_editor["Browser text editor"]

node_user -->|"manages snippets"| node_popup_app
node_popup_app -->|"renders"| node_snippet_list
node_popup_app -->|"renders"| node_snippet_form
node_popup_app -->|"renders"| node_blacklist_ui
node_popup_app -->|"renders"| node_onboarding
node_popup_app -->|"uses"| node_services
node_services -.->|"reads and writes"| node_snippet_store
node_chrome_store -->|"implements"| node_snippet_store
node_content_script -.->|"initializes"| node_suggestions
node_user -->|"types in"| node_browser_editor
node_browser_editor -->|"signals input"| node_suggestions
node_suggestions -->|"detects trigger"| node_shared_engine
node_suggestions -->|"previews fields"| node_template_resolver
node_suggestions -->|"requests insertion"| node_expansion
node_suggestions -->|"selects adapter"| node_adapter_factory
node_expansion -.->|"replaces trigger"| node_shared_engine
node_expansion -.->|"collects values"| node_template_flow
node_template_flow -.->|"enables editing"| node_inline_edit
node_adapter_factory -.->|"supports Docs"| node_google_docs
node_expansion -.->|"inserts text"| node_browser_editor
node_popup_app -->|"opens editor"| node_media_service
node_media_service -->|"prepares files"| node_media_prepare
node_media_service -->|"reads and saves metadata"| node_snippet_store
node_media_service -->|"reads and stores assets"| node_media_store
node_backup_controls -.->|"initiates backup"| node_backup_service
node_backup_service -->|"snapshots assets"| node_media_service
node_backup_service -->|"imports snippets"| node_snippet_store
node_backup_service -->|"stages assets"| node_media_store
node_popup_app -.->|"manages domains"| node_blacklist_service
node_popup_app -.->|"shows totals"| node_stats_service
node_page_user -->|"visits"| node_landing
node_landing -.->|"health API separate"| node_landing_api

click node_popup_app "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/popup/App.tsx"
click node_snippet_form "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/SnippetForm.tsx"
click node_snippet_list "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/SnippetList.tsx"
click node_blacklist_ui "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/BlacklistModal.tsx"
click node_onboarding "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/FirstUseGuide.tsx"
click node_content_script "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/index.ts"
click node_suggestions "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/suggestions/SuggestionController.ts"
click node_expansion "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/expansion/ExpansionCoordinator.ts"
click node_adapter_factory "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/adapters/AdapterFactory.ts"
click node_google_docs "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/adapters/GoogleDocsAdapter.ts"
click node_template_flow "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/templates/TemplateDialog.ts"
click node_inline_edit "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/templates/InlineSession.ts"
click node_shared_engine "https://github.com/fillin-dev/fillin/blob/main/packages/shared/src/engine/detector.ts"
click node_template_resolver "https://github.com/fillin-dev/fillin/blob/main/packages/shared/src/templates/resolveTemplate.ts"
click node_services "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/SnippetService.ts"
click node_blacklist_service "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/BlacklistService.ts"
click node_stats_service "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/StatsService.ts"
click node_snippet_store "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/storage/SnippetRepository.ts"
click node_chrome_store "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/storage/ChromeStorageRepository.ts"
click node_media_service "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/MediaSnippetService.ts"
click node_media_store "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/storage/MediaAssetRepository.ts"
click node_media_prepare "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/media/prepareMedia.ts"
click node_backup_service "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/backup/BackupService.ts"
click node_backup_controls "https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/BackupControls.tsx"
click node_landing "https://github.com/fillin-dev/fillin/blob/main/apps/landing/frontend/src/App.tsx"
click node_landing_api "https://github.com/fillin-dev/fillin/blob/main/apps/landing/backend/src/app.ts"

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_app,node_snippet_form,node_snippet_list,node_blacklist_ui,node_onboarding,node_user,node_browser_editor toneBlue
class node_content_script,node_suggestions,node_expansion,node_adapter_factory,node_google_docs,node_template_flow,node_inline_edit,node_shared_engine,node_template_resolver toneAmber
class node_services,node_blacklist_service,node_stats_service,node_snippet_store,node_chrome_store toneMint
class node_media_service,node_media_store,node_media_prepare,node_backup_service,node_backup_controls toneRose
class node_landing,node_landing_api,node_page_user toneIndigo
```

## Components

### Library management

- [Popup UI](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/popup/App.tsx): `apps/extension/src/popup/App.tsx`
- [Snippet editor](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/SnippetForm.tsx): `apps/extension/src/components/SnippetForm.tsx`
- [Snippet library list](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/SnippetList.tsx): `apps/extension/src/components/SnippetList.tsx`
- [Blacklist settings](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/BlacklistModal.tsx): `apps/extension/src/components/BlacklistModal.tsx`
- [First-use guide](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/FirstUseGuide.tsx): `apps/extension/src/components/FirstUseGuide.tsx`

### Page expansion

- [Content script](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/index.ts): `apps/extension/src/content/index.ts`
- [Shortcut suggestions](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/suggestions/SuggestionController.ts): `apps/extension/src/content/suggestions/SuggestionController.ts`
- [Expansion coordinator](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/expansion/ExpansionCoordinator.ts): `apps/extension/src/content/expansion/ExpansionCoordinator.ts`
- [Editor adapter selection](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/adapters/AdapterFactory.ts): `apps/extension/src/content/adapters/AdapterFactory.ts`
- [Google Docs adapter](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/adapters/GoogleDocsAdapter.ts): `apps/extension/src/content/adapters/GoogleDocsAdapter.ts`
- [Template interaction](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/templates/TemplateDialog.ts): `apps/extension/src/content/templates/TemplateDialog.ts`
- [Inline placeholders](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/content/templates/InlineSession.ts): `apps/extension/src/content/templates/InlineSession.ts`
- [Trigger and replacement engine](https://github.com/fillin-dev/fillin/blob/main/packages/shared/src/engine/detector.ts): `packages/shared/src/engine/detector.ts`
- [Template resolver](https://github.com/fillin-dev/fillin/blob/main/packages/shared/src/templates/resolveTemplate.ts): `packages/shared/src/templates/resolveTemplate.ts`

### Local data

- [Snippet and settings services](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/SnippetService.ts): `apps/extension/src/services/SnippetService.ts`
- [Blacklist service](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/BlacklistService.ts): `apps/extension/src/services/BlacklistService.ts`
- [Usage statistics](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/StatsService.ts): `apps/extension/src/services/StatsService.ts`
- [Snippet repository](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/storage/SnippetRepository.ts): `apps/extension/src/storage/SnippetRepository.ts`
- [Chrome local storage](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/storage/ChromeStorageRepository.ts): `apps/extension/src/storage/ChromeStorageRepository.ts`

### Media and backup

- [Visual snippet service](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/services/MediaSnippetService.ts): `apps/extension/src/services/MediaSnippetService.ts`
- [Media asset store](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/storage/MediaAssetRepository.ts): `apps/extension/src/storage/MediaAssetRepository.ts`
- [Media preparation](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/media/prepareMedia.ts): `apps/extension/src/media/prepareMedia.ts`
- [Backup and restore](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/backup/BackupService.ts): `apps/extension/src/backup/BackupService.ts`
- [Backup controls](https://github.com/fillin-dev/fillin/blob/main/apps/extension/src/components/BackupControls.tsx): `apps/extension/src/components/BackupControls.tsx`

### Public website

- [Marketing and install site](https://github.com/fillin-dev/fillin/blob/main/apps/landing/frontend/src/App.tsx): `apps/landing/frontend/src/App.tsx`
- [Optional health API](https://github.com/fillin-dev/fillin/blob/main/apps/landing/backend/src/app.ts): `apps/landing/backend/src/app.ts`

### Other components

- **Extension user**
- **Website visitor**
- **Browser text editor**

## Connections

- Extension user → Popup UI: manages snippets (evidence: `README.md`)
- Popup UI → Snippet library list: renders (evidence: `apps/extension/src/popup/App.tsx`)
- Popup UI → Snippet editor: renders (evidence: `apps/extension/src/popup/App.tsx`)
- Popup UI → Blacklist settings: renders (evidence: `apps/extension/src/popup/App.tsx`)
- Popup UI → First-use guide: renders (evidence: `apps/extension/src/popup/App.tsx`)
- Popup UI → Snippet and settings services: uses (evidence: `apps/extension/src/popup/App.tsx`)
- Snippet and settings services → Snippet repository: reads and writes
- Chrome local storage → Snippet repository: implements (evidence: `apps/extension/src/storage/ChromeStorageRepository.ts`)
- Content script → Shortcut suggestions: initializes
- Extension user → Browser text editor: types in (evidence: `README.md`)
- Browser text editor → Shortcut suggestions: signals input (evidence: `apps/extension/src/content/suggestions/SuggestionController.ts`)
- Shortcut suggestions → Trigger and replacement engine: detects trigger (evidence: `apps/extension/src/content/suggestions/SuggestionController.ts`)
- Shortcut suggestions → Template resolver: previews fields (evidence: `apps/extension/src/content/suggestions/SuggestionController.ts`)
- Shortcut suggestions → Expansion coordinator: requests insertion (evidence: `apps/extension/src/content/suggestions/SuggestionController.ts`)
- Shortcut suggestions → Editor adapter selection: selects adapter (evidence: `apps/extension/src/content/suggestions/SuggestionController.ts`)
- Expansion coordinator → Trigger and replacement engine: replaces trigger
- Expansion coordinator → Template interaction: collects values
- Template interaction → Inline placeholders: enables editing
- Editor adapter selection → Google Docs adapter: supports Docs
- Expansion coordinator → Browser text editor: inserts text
- Popup UI → Visual snippet service: opens editor (evidence: `apps/extension/src/popup/App.tsx`)
- Visual snippet service → Media preparation: prepares files (evidence: `apps/extension/src/services/MediaSnippetService.ts`)
- Visual snippet service → Snippet repository: reads and saves metadata (evidence: `apps/extension/src/services/MediaSnippetService.ts`)
- Visual snippet service → Media asset store: reads and stores assets (evidence: `apps/extension/src/services/MediaSnippetService.ts`)
- Backup controls → Backup and restore: initiates backup
- Backup and restore → Visual snippet service: snapshots assets (evidence: `apps/extension/src/backup/BackupService.ts`)
- Backup and restore → Snippet repository: imports snippets (evidence: `apps/extension/src/backup/BackupService.ts`)
- Backup and restore → Media asset store: stages assets (evidence: `apps/extension/src/backup/BackupService.ts`)
- Popup UI → Blacklist service: manages domains
- Popup UI → Usage statistics: shows totals
- Website visitor → Marketing and install site: visits (evidence: `apps/landing/frontend/src/App.tsx`)
- Marketing and install site → Optional health API: health API separate
