# stackthefennec/telegram-export-parser architecture

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

- Interactive diagram: https://gitdiagram.com/stackthefennec/telegram-export-parser
- Repository: https://github.com/stackthefennec/telegram-export-parser

## Overview

This TypeScript library turns Telegram Desktop exports into typed chat data. Users can parse a file, JSON string, or raw object through the public API, or analyze an export with the CLI; the processor is the high-level runtime entry point. The parser registry dispatches raw items to message, event, and text-entity parsers, with shared parsing utilities handling common fields and actors. Typed models cover messages, service events, rich-text entities, and shared export data. The README documents broad parsing and analysis capabilities; unsampled implementation details are represented only where documented or indexed.

Main entry points: [`src/parsers/index.ts`](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/index.ts) (Parser registry), [`src/types/index.ts`](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/index.ts) (Type exports), [`src/index.ts`](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/index.ts) (Public API), [`src/parsers/base.ts`](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/base.ts) (Common parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_publicapi["Public API<br/>[index.ts]"]
  node_cli["CLI analysis<br/>[cli.ts]"]
end

subgraph group_runtime["Parsing runtime"]
  node_processor["Export processor<br/>[main.ts]"]
  node_registry["Parser registry<br/>[index.ts]"]
  node_factory["Priority factory<br/>[factory.ts]"]
  node_parsercontract["Parser contract<br/>[parser.ts]"]
  node_errors["Parse errors<br/>[errors.ts]"]
end

subgraph group_domain["Telegram parsing"]
  node_messageparsers["Message parsers<br/>[messages.ts]"]
  node_eventparsers["Event parsers<br/>[events.ts]"]
  node_entityparsers["Text entity parsers<br/>[text-entities.ts]"]
  node_common["Common parsing<br/>[base.ts]"]
  node_actors["Actor parsing<br/>[actors.ts]"]
end

subgraph group_models["Typed domain models"]
  node_sharedtypes["Shared export types<br/>[shared.ts]"]
  node_messagetypes["Message types<br/>[messages.ts]"]
  node_eventtypes["Service event types<br/>[events.ts]"]
  node_entitytypes["Text entity types<br/>[text-entities.ts]"]
  node_rawtypes["Raw export types<br/>[raw-export.ts]"]
  node_typebarrel["Type exports<br/>[index.ts]"]
end

node_user(("Library user"))
node_cliuser(("CLI user"))

node_user -->|"invokes"| node_publicapi
node_user -->|"parses directly"| node_processor
node_cliuser -->|"runs"| node_cli
node_publicapi -->|"exports entry"| node_processor
node_publicapi -->|"exports parser API"| node_registry
node_cli -->|"loads and iterates"| node_processor
node_processor -.->|"parses items"| node_registry
node_registry -->|"registers and dispatches"| node_factory
node_registry -->|"registers"| node_messageparsers
node_registry -->|"registers"| node_eventparsers
node_registry -->|"registers"| node_entityparsers
node_factory -->|"uses contract"| node_parsercontract
node_factory -->|"throws"| node_errors
node_messageparsers -.->|"builds from helpers"| node_common
node_eventparsers -.->|"uses shared parsing"| node_common
node_common -->|"parses text entities"| node_registry
node_common -->|"resolves actors"| node_actors
node_entityparsers -.->|"creates typed entities"| node_entitytypes
node_messageparsers -.->|"creates typed messages"| node_messagetypes
node_eventparsers -.->|"creates typed events"| node_eventtypes
node_typebarrel -->|"re-exports"| node_sharedtypes
node_typebarrel -->|"re-exports"| node_messagetypes
node_typebarrel -->|"re-exports"| node_eventtypes
node_typebarrel -->|"re-exports"| node_entitytypes
node_typebarrel -->|"re-exports"| node_rawtypes
node_publicapi -->|"exports types"| node_typebarrel

click node_publicapi "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/index.ts"
click node_cli "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/cli.ts"
click node_processor "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/processors/main.ts"
click node_registry "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/index.ts"
click node_factory "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/core/factory.ts"
click node_parsercontract "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/core/parser.ts"
click node_errors "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/core/errors.ts"
click node_messageparsers "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/messages.ts"
click node_eventparsers "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/events.ts"
click node_entityparsers "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/text-entities.ts"
click node_common "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/base.ts"
click node_actors "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/actors.ts"
click node_sharedtypes "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/shared.ts"
click node_messagetypes "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/messages.ts"
click node_eventtypes "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/events.ts"
click node_entitytypes "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/text-entities.ts"
click node_rawtypes "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/raw-export.ts"
click node_typebarrel "https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/index.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_publicapi,node_cli,node_user,node_cliuser toneBlue
class node_processor,node_registry,node_factory,node_parsercontract,node_errors toneAmber
class node_messageparsers,node_eventparsers,node_entityparsers,node_common,node_actors toneMint
class node_sharedtypes,node_messagetypes,node_eventtypes,node_entitytypes,node_rawtypes,node_typebarrel toneRose
```

## Components

### User entry points

- [Public API](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/index.ts): `src/index.ts`
- [CLI analysis](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/cli.ts): `src/cli.ts`

### Parsing runtime

- [Export processor](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/processors/main.ts): `src/processors/main.ts`
- [Parser registry](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/index.ts): `src/parsers/index.ts`
- [Priority factory](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/core/factory.ts): `src/core/factory.ts`
- [Parser contract](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/core/parser.ts): `src/core/parser.ts`
- [Parse errors](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/core/errors.ts): `src/core/errors.ts`

### Telegram parsing

- [Message parsers](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/messages.ts): `src/parsers/messages.ts`
- [Event parsers](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/events.ts): `src/parsers/events.ts`
- [Text entity parsers](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/text-entities.ts): `src/parsers/text-entities.ts`
- [Common parsing](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/base.ts): `src/parsers/base.ts`
- [Actor parsing](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/parsers/actors.ts): `src/parsers/actors.ts`

### Typed domain models

- [Shared export types](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/shared.ts): `src/types/shared.ts`
- [Message types](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/messages.ts): `src/types/messages.ts`
- [Service event types](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/events.ts): `src/types/events.ts`
- [Text entity types](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/text-entities.ts): `src/types/text-entities.ts`
- [Raw export types](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/raw-export.ts): `src/types/raw-export.ts`
- [Type exports](https://github.com/stackthefennec/telegram-export-parser/blob/main/src/types/index.ts): `src/types/index.ts`

### Other components

- **Library user**
- **CLI user**

## Connections

- Library user → Public API: invokes (evidence: `README.md`)
- Library user → Export processor: parses directly (evidence: `README.md`)
- CLI user → CLI analysis: runs (evidence: `src/cli.ts`)
- Public API → Export processor: exports entry (evidence: `src/index.ts`)
- Public API → Parser registry: exports parser API (evidence: `src/index.ts`)
- CLI analysis → Export processor: loads and iterates (evidence: `src/cli.ts`)
- Export processor → Parser registry: parses items
- Parser registry → Priority factory: registers and dispatches (evidence: `src/parsers/index.ts`)
- Parser registry → Message parsers: registers (evidence: `src/parsers/index.ts`)
- Parser registry → Event parsers: registers (evidence: `src/parsers/index.ts`)
- Parser registry → Text entity parsers: registers (evidence: `src/parsers/index.ts`)
- Priority factory → Parser contract: uses contract (evidence: `src/core/factory.ts`)
- Priority factory → Parse errors: throws (evidence: `src/core/factory.ts`)
- Message parsers → Common parsing: builds from helpers
- Event parsers → Common parsing: uses shared parsing
- Common parsing → Parser registry: parses text entities (evidence: `src/parsers/base.ts`)
- Common parsing → Actor parsing: resolves actors (evidence: `src/parsers/base.ts`)
- Text entity parsers → Text entity types: creates typed entities
- Message parsers → Message types: creates typed messages
- Event parsers → Service event types: creates typed events
- Type exports → Shared export types: re-exports (evidence: `src/types/index.ts`)
- Type exports → Message types: re-exports (evidence: `src/types/index.ts`)
- Type exports → Service event types: re-exports (evidence: `src/types/index.ts`)
- Type exports → Text entity types: re-exports (evidence: `src/types/index.ts`)
- Type exports → Raw export types: re-exports (evidence: `src/types/index.ts`)
- Public API → Type exports: exports types (evidence: `src/index.ts`)