# marslento/your-name-for-threads architecture

> Architecture diagram of the GitHub repository marslento/your-name-for-threads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marslento/your-name-for-threads
- Repository: https://github.com/marslento/your-name-for-threads

## Overview

Your Name for Threads is a local-first browser extension for attaching private nicknames to Threads identities and keeping notes in an account-specific directory. Users onboard in the popup, add nicknames from Threads profile pages, and manage contacts, conflicts, and backups in a Dashboard opened from a confirmed Threads tab. The content integration covers profiles and feed/reply/quoted-post authors; the Dashboard also provides recovery and diagnostics. Edges reflect sampled imports/calls or README-described behavior; unsampled subsystem links are omitted where wiring is not evidenced.

Main entry points: [`src/dashboard/App.tsx`](https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/App.tsx) (Dashboard router), [`src/content/index.ts`](https://github.com/marslento/your-name-for-threads/blob/main/src/content/index.ts) (Content integration), [`src/storage/BrowserStorageContactsRepository.ts`](https://github.com/marslento/your-name-for-threads/blob/main/src/storage/BrowserStorageContactsRepository.ts) (Contacts repository), [`src/popup/App.tsx`](https://github.com/marslento/your-name-for-threads/blob/main/src/popup/App.tsx) (Popup and onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Extension entry points"]
  node_popup["Popup and onboarding<br/>[App.tsx]"]
  node_worker["Background worker<br/>[serviceWorker.ts]"]
  node_account["Account context"]
end

subgraph group_threads["Threads integration"]
  node_content_entry["Content integration<br/>[index.ts]"]
  node_runtime["Surface runtime<br/>[ThreadsRuntime.ts]"]
  node_profile_ui["Profile nickname UI"]
  node_author_ui["Post author labels"]
  node_identity["Identity observation"]
end

subgraph group_directory["Directory and storage"]
  node_contacts_repo["Contacts repository"]
  node_directory_access["Account directory access<br/>[directoryAccess.ts]"]
  node_migration["Storage migration<br/>[migrations.ts]"]
  node_browser_storage[("Browser local storage")]
end

subgraph group_dashboard["Dashboard workflows"]
  node_dashboard_app["Dashboard router<br/>[App.tsx]"]
  node_dashboard_store["Dashboard state<br/>[DashboardStore.ts]"]
  node_directory_views["Directory and conflicts<br/>[DirectoryPage.tsx]"]
  node_backup_ui["Backup review flow"]
end

subgraph group_safety["Portability and recovery"]
  node_portability["Backup import/export<br/>[importSession.ts]"]
  node_recovery["Recovery restore<br/>[recoveryRestore.ts]"]
  node_diagnostics["Diagnostics"]
end

node_user(("Extension user"))
node_threads_site(("Threads pages"))

node_user -->|"opens"| node_popup
node_popup -->|"checks account"| node_account
node_popup -->|"requests Dashboard"| node_worker
node_worker -->|"handles context"| node_account
node_threads_site -->|"hosts integration"| node_content_entry
node_content_entry -->|"starts runtime"| node_runtime
node_content_entry -->|"registers surface"| node_profile_ui
node_content_entry -->|"creates adapter"| node_author_ui
node_content_entry -->|"initializes coordinator"| node_identity
node_author_ui -->|"looks up contacts"| node_contacts_repo
node_user -->|"opens directory"| node_dashboard_app
node_dashboard_app -->|"creates store"| node_dashboard_store
node_dashboard_app -->|"creates repository"| node_contacts_repo
node_dashboard_app -->|"routes pages"| node_directory_views
node_dashboard_app -->|"routes import flow"| node_backup_ui
node_dashboard_store -->|"uses repository"| node_contacts_repo
node_contacts_repo -->|"reads and mutates"| node_directory_access
node_directory_access -->|"loads quarantined storage"| node_migration
node_migration -->|"migrates data"| node_browser_storage
node_backup_ui -->|"records decisions"| node_portability
node_dashboard_app -->|"previews and commits"| node_recovery
node_dashboard_app -->|"reports issues"| node_diagnostics

click node_popup "https://github.com/marslento/your-name-for-threads/blob/main/src/popup/App.tsx"
click node_worker "https://github.com/marslento/your-name-for-threads/blob/main/src/background/serviceWorker.ts"
click node_account "https://github.com/marslento/your-name-for-threads/blob/main/src/account/AccountContextRegistry.ts"
click node_content_entry "https://github.com/marslento/your-name-for-threads/blob/main/src/content/index.ts"
click node_runtime "https://github.com/marslento/your-name-for-threads/blob/main/src/content/runtime/ThreadsRuntime.ts"
click node_profile_ui "https://github.com/marslento/your-name-for-threads/blob/main/src/content/surfaces/profile/ProfileSurfaceAdapter.tsx"
click node_author_ui "https://github.com/marslento/your-name-for-threads/blob/main/src/content/surfaces/post-author/PostAuthorSurfaceAdapter.ts"
click node_identity "https://github.com/marslento/your-name-for-threads/blob/main/src/content/identity/IdentityCoordinator.ts"
click node_dashboard_app "https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/App.tsx"
click node_dashboard_store "https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/store/DashboardStore.ts"
click node_directory_views "https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/routes/DirectoryPage.tsx"
click node_backup_ui "https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/backup/ImportReviewDrawer.tsx"
click node_contacts_repo "https://github.com/marslento/your-name-for-threads/blob/main/src/storage/BrowserStorageContactsRepository.ts"
click node_directory_access "https://github.com/marslento/your-name-for-threads/blob/main/src/storage/directoryAccess.ts"
click node_migration "https://github.com/marslento/your-name-for-threads/blob/main/src/storage/migrations.ts"
click node_portability "https://github.com/marslento/your-name-for-threads/blob/main/src/portability/importSession.ts"
click node_recovery "https://github.com/marslento/your-name-for-threads/blob/main/src/recovery/recoveryRestore.ts"
click node_diagnostics "https://github.com/marslento/your-name-for-threads/blob/main/src/diagnostics/collectDiagnosticSummary.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,node_worker,node_account,node_user toneBlue
class node_content_entry,node_runtime,node_profile_ui,node_author_ui,node_identity toneAmber
class node_contacts_repo,node_directory_access,node_migration,node_browser_storage toneMint
class node_dashboard_app,node_dashboard_store,node_directory_views,node_backup_ui toneRose
class node_portability,node_recovery,node_diagnostics,node_threads_site toneIndigo
```

## Components

### Extension entry points

- [Popup and onboarding](https://github.com/marslento/your-name-for-threads/blob/main/src/popup/App.tsx): `src/popup/App.tsx`
- [Background worker](https://github.com/marslento/your-name-for-threads/blob/main/src/background/serviceWorker.ts): `src/background/serviceWorker.ts`
- [Account context](https://github.com/marslento/your-name-for-threads/blob/main/src/account/AccountContextRegistry.ts): `src/account/AccountContextRegistry.ts`

### Threads integration

- [Content integration](https://github.com/marslento/your-name-for-threads/blob/main/src/content/index.ts): `src/content/index.ts`
- [Surface runtime](https://github.com/marslento/your-name-for-threads/blob/main/src/content/runtime/ThreadsRuntime.ts): `src/content/runtime/ThreadsRuntime.ts`
- [Profile nickname UI](https://github.com/marslento/your-name-for-threads/blob/main/src/content/surfaces/profile/ProfileSurfaceAdapter.tsx): `src/content/surfaces/profile/ProfileSurfaceAdapter.tsx`
- [Post author labels](https://github.com/marslento/your-name-for-threads/blob/main/src/content/surfaces/post-author/PostAuthorSurfaceAdapter.ts): `src/content/surfaces/post-author/PostAuthorSurfaceAdapter.ts`
- [Identity observation](https://github.com/marslento/your-name-for-threads/blob/main/src/content/identity/IdentityCoordinator.ts): `src/content/identity/IdentityCoordinator.ts`

### Directory and storage

- [Contacts repository](https://github.com/marslento/your-name-for-threads/blob/main/src/storage/BrowserStorageContactsRepository.ts): `src/storage/BrowserStorageContactsRepository.ts`
- [Account directory access](https://github.com/marslento/your-name-for-threads/blob/main/src/storage/directoryAccess.ts): `src/storage/directoryAccess.ts`
- [Storage migration](https://github.com/marslento/your-name-for-threads/blob/main/src/storage/migrations.ts): `src/storage/migrations.ts`
- **Browser local storage**

### Dashboard workflows

- [Dashboard router](https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/App.tsx): `src/dashboard/App.tsx`
- [Dashboard state](https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/store/DashboardStore.ts): `src/dashboard/store/DashboardStore.ts`
- [Directory and conflicts](https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/routes/DirectoryPage.tsx): `src/dashboard/routes/DirectoryPage.tsx`
- [Backup review flow](https://github.com/marslento/your-name-for-threads/blob/main/src/dashboard/backup/ImportReviewDrawer.tsx): `src/dashboard/backup/ImportReviewDrawer.tsx`

### Portability and recovery

- [Backup import/export](https://github.com/marslento/your-name-for-threads/blob/main/src/portability/importSession.ts): `src/portability/importSession.ts`
- [Recovery restore](https://github.com/marslento/your-name-for-threads/blob/main/src/recovery/recoveryRestore.ts): `src/recovery/recoveryRestore.ts`
- [Diagnostics](https://github.com/marslento/your-name-for-threads/blob/main/src/diagnostics/collectDiagnosticSummary.ts): `src/diagnostics/collectDiagnosticSummary.ts`

### Other components

- **Extension user**
- **Threads pages**

## Connections

- Extension user → Popup and onboarding: opens (evidence: `README.md`)
- Popup and onboarding → Account context: checks account (evidence: `src/popup/App.tsx`)
- Popup and onboarding → Background worker: requests Dashboard (evidence: `src/popup/App.tsx`)
- Background worker → Account context: handles context (evidence: `src/background/serviceWorker.ts`)
- Threads pages → Content integration: hosts integration (evidence: `README.md`)
- Content integration → Surface runtime: starts runtime (evidence: `src/content/index.ts`)
- Content integration → Profile nickname UI: registers surface (evidence: `src/content/index.ts`)
- Content integration → Post author labels: creates adapter (evidence: `src/content/index.ts`)
- Content integration → Identity observation: initializes coordinator (evidence: `src/content/index.ts`)
- Post author labels → Contacts repository: looks up contacts (evidence: `src/content/surfaces/post-author/PostAuthorSurfaceAdapter.ts`)
- Extension user → Dashboard router: opens directory (evidence: `README.md`)
- Dashboard router → Dashboard state: creates store (evidence: `src/dashboard/App.tsx`)
- Dashboard router → Contacts repository: creates repository (evidence: `src/dashboard/App.tsx`)
- Dashboard router → Directory and conflicts: routes pages (evidence: `src/dashboard/App.tsx`)
- Dashboard router → Backup review flow: routes import flow (evidence: `src/dashboard/App.tsx`)
- Dashboard state → Contacts repository: uses repository (evidence: `src/dashboard/store/DashboardStore.ts`)
- Contacts repository → Account directory access: reads and mutates (evidence: `src/storage/BrowserStorageContactsRepository.ts`)
- Account directory access → Storage migration: loads quarantined storage (evidence: `src/storage/directoryAccess.ts`)
- Storage migration → Browser local storage: migrates data (evidence: `src/storage/migrations.ts`)
- Backup review flow → Backup import/export: records decisions (evidence: `src/dashboard/backup/ImportReviewDrawer.tsx`)
- Dashboard router → Recovery restore: previews and commits (evidence: `src/dashboard/App.tsx`)
- Dashboard router → Diagnostics: reports issues (evidence: `src/dashboard/App.tsx`)
