# pouuup/docshelf architecture

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

- Interactive diagram: https://gitdiagram.com/pouuup/docshelf
- Repository: https://github.com/pouuup/docshelf

## Overview

DocShelf is a terminal document reader: a user supplies a URL, the app fetches and parses the page into titled sections and text/code blocks, saves or updates it under `data`, then presents it for keyboard-driven reading. The map follows the sampled entry point, import, parser, storage, and TUI code. The README is empty and several TUI modules are represented only by the tree, so uncertain internal calls are omitted.

Main entry points: [`internal/parser/parser.go`](https://github.com/pouuup/docshelf/blob/main/internal/parser/parser.go) (Page parser), [`cmd/docshelf/main.go`](https://github.com/pouuup/docshelf/blob/main/cmd/docshelf/main.go) (CLI entry), [`internal/app/import.go`](https://github.com/pouuup/docshelf/blob/main/internal/app/import.go) (Import workflow), [`internal/storage/storage.go`](https://github.com/pouuup/docshelf/blob/main/internal/storage/storage.go) (JSON storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_import["Import and parsing"]
  node_importer["Import workflow<br/>[import.go]"]
  node_parser["Page parser<br/>[parser.go]"]
  node_models["Document model<br/>[document.go]"]
  node_sections["Section model<br/>[section.go]"]
  node_blocks["Block model<br/>[block.go]"]
end

subgraph group_persistence["Document storage"]
  node_storage[("JSON storage<br/>[storage.go]")]
  node_data[("Document files")]
end

subgraph group_reader["Terminal reader"]
  node_tui_model["Reader state<br/>[model.go]"]
  node_tui_update["Key handling<br/>[update.go]"]
  node_tui_view["Screen rendering<br/>[view.go]"]
  node_tui_content["Content formatting<br/>[content.go]"]
  node_tui_code["Code highlighting<br/>[code.go]"]
  node_bubbletea["Terminal runtime"]
end

node_user(("User"))
node_main["CLI entry<br/>[main.go]"]
node_web["Web page"]

node_user -->|"enters URL"| node_main
node_main -->|"imports URL"| node_importer
node_importer -->|"parses URL"| node_parser
node_parser -->|"fetches HTML"| node_web
node_parser -->|"builds document"| node_models
node_parser -->|"builds sections"| node_sections
node_parser -->|"builds blocks"| node_blocks
node_importer -->|"checks, saves or updates"| node_storage
node_storage -->|"reads and writes"| node_data
node_importer -->|"returns document"| node_main
node_main -->|"creates reader state"| node_tui_model
node_main -->|"starts program"| node_bubbletea
node_bubbletea -->|"dispatches input"| node_tui_update
node_tui_update -->|"updates state"| node_tui_model
node_bubbletea -->|"requests view"| node_tui_view
node_tui_view -->|"formats section content"| node_tui_content
node_tui_content -->|"highlights code"| node_tui_code
node_bubbletea -->|"shows screen"| node_user
node_user -->|"presses keys"| node_bubbletea

click node_main "https://github.com/pouuup/docshelf/blob/main/cmd/docshelf/main.go"
click node_importer "https://github.com/pouuup/docshelf/blob/main/internal/app/import.go"
click node_parser "https://github.com/pouuup/docshelf/blob/main/internal/parser/parser.go"
click node_models "https://github.com/pouuup/docshelf/blob/main/internal/models/document.go"
click node_sections "https://github.com/pouuup/docshelf/blob/main/internal/models/section.go"
click node_blocks "https://github.com/pouuup/docshelf/blob/main/internal/models/block.go"
click node_storage "https://github.com/pouuup/docshelf/blob/main/internal/storage/storage.go"
click node_data "https://github.com/pouuup/docshelf/tree/main/data"
click node_tui_model "https://github.com/pouuup/docshelf/blob/main/internal/tui/model.go"
click node_tui_update "https://github.com/pouuup/docshelf/blob/main/internal/tui/update.go"
click node_tui_view "https://github.com/pouuup/docshelf/blob/main/internal/tui/view.go"
click node_tui_content "https://github.com/pouuup/docshelf/blob/main/internal/tui/content.go"
click node_tui_code "https://github.com/pouuup/docshelf/blob/main/internal/tui/code.go"

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_importer,node_parser,node_models,node_sections,node_blocks,node_user toneBlue
class node_storage,node_data toneAmber
class node_tui_model,node_tui_update,node_tui_view,node_tui_content,node_tui_code,node_bubbletea toneMint
class node_main toneTeal
class node_web toneIndigo
```

## Components

### Import and parsing

- [Import workflow](https://github.com/pouuup/docshelf/blob/main/internal/app/import.go): `internal/app/import.go`
- [Page parser](https://github.com/pouuup/docshelf/blob/main/internal/parser/parser.go): `internal/parser/parser.go`
- [Document model](https://github.com/pouuup/docshelf/blob/main/internal/models/document.go): `internal/models/document.go`
- [Section model](https://github.com/pouuup/docshelf/blob/main/internal/models/section.go): `internal/models/section.go`
- [Block model](https://github.com/pouuup/docshelf/blob/main/internal/models/block.go): `internal/models/block.go`

### Document storage

- [JSON storage](https://github.com/pouuup/docshelf/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Document files](https://github.com/pouuup/docshelf/tree/main/data): `data`

### Terminal reader

- [Reader state](https://github.com/pouuup/docshelf/blob/main/internal/tui/model.go): `internal/tui/model.go`
- [Key handling](https://github.com/pouuup/docshelf/blob/main/internal/tui/update.go): `internal/tui/update.go`
- [Screen rendering](https://github.com/pouuup/docshelf/blob/main/internal/tui/view.go): `internal/tui/view.go`
- [Content formatting](https://github.com/pouuup/docshelf/blob/main/internal/tui/content.go): `internal/tui/content.go`
- [Code highlighting](https://github.com/pouuup/docshelf/blob/main/internal/tui/code.go): `internal/tui/code.go`
- **Terminal runtime**

### Other components

- **User**
- [CLI entry](https://github.com/pouuup/docshelf/blob/main/cmd/docshelf/main.go): `cmd/docshelf/main.go`
- **Web page**

## Connections

- User → CLI entry: enters URL
- CLI entry → Import workflow: imports URL
- Import workflow → Page parser: parses URL
- Page parser → Web page: fetches HTML
- Page parser → Document model: builds document
- Page parser → Section model: builds sections
- Page parser → Block model: builds blocks
- Import workflow → JSON storage: checks, saves or updates
- JSON storage → Document files: reads and writes
- Import workflow → CLI entry: returns document
- CLI entry → Reader state: creates reader state
- CLI entry → Terminal runtime: starts program
- Terminal runtime → Key handling: dispatches input
- Key handling → Reader state: updates state
- Terminal runtime → Screen rendering: requests view
- Screen rendering → Content formatting: formats section content
- Content formatting → Code highlighting: highlights code
- Terminal runtime → User: shows screen
- User → Terminal runtime: presses keys