# priyanshu-t-singh/le-grimoire architecture

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

- Interactive diagram: https://gitdiagram.com/priyanshu-t-singh/le-grimoire
- Repository: https://github.com/priyanshu-t-singh/le-grimoire

## Overview

Le Grimoire is a Go e-ink reading service: devices authenticate, navigate a library, request rendered pages, and retain per-device navigation state. Its HTTP handlers are the device workflow entry point; provider, state, rendering, and persistence components support that flow. A separate terminal UI offers interactive reading. The composition and middleware wiring are visible in sampled source; handler internals and several domain implementations were not sampled, so uncertain call relationships are omitted.

Main entry points: [`internal/server/server.go`](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/server/server.go) (Service bootstrap), [`internal/handlers/routes.go`](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/handlers/routes.go) (API handlers), [`internal/device/repository.go`](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/device/repository.go) (Device repository), [`internal/provider/factory.go`](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/factory.go) (Provider factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application Runtime"]
  node_server["HTTP server<br/>[server.go]"]
  node_composition["Service bootstrap<br/>[server.go]"]
  node_middleware["Request middleware<br/>[middleware.go]"]
  node_auth["Device authentication<br/>[auth.go]"]
end

subgraph group_deviceflow["Device Reading"]
  node_handlers["API handlers<br/>[routes.go]"]
end

subgraph group_content["Book Content"]
  node_book_provider["Book provider<br/>[provider.go]"]
  node_provider_factory["Provider factory<br/>[factory.go]"]
  node_kavita["Kavita connector<br/>[kavita.go]"]
  node_localfs["Local filesystem provider<br/>[localfs.go]"]
  node_renderer["E-ink renderer<br/>[image.go]"]
  node_frame_cache[("Frame cache<br/>[cache.go]")]
end

subgraph group_state["Device State"]
  node_device_repo["Device repository<br/>[repository.go]"]
  node_sqlite[("SQLite database<br/>[db.go]")]
  node_state_machine["Navigation state machine<br/>[machine.go]"]
  node_state_model["Navigation state<br/>[models.go]"]
end

subgraph group_terminal["Terminal Reader"]
  node_tui["Terminal UI<br/>[app.go]"]
end

node_device(("E-ink device"))
node_kavita_service["Kavita server"]
node_browser["Chromium"]
node_terminal_actor(("Terminal reader"))

node_composition -->|"creates and connects"| node_book_provider
node_composition -->|"selects provider"| node_provider_factory
node_composition -->|"creates"| node_device_repo
node_composition -->|"creates"| node_state_machine
node_composition -->|"creates"| node_renderer
node_composition -->|"creates"| node_frame_cache
node_composition -->|"opens"| node_sqlite
node_composition -->|"wires dependencies"| node_handlers
node_composition -->|"starts"| node_server
node_server -->|"wraps router"| node_middleware
node_middleware -->|"dispatches through"| node_auth
node_auth -->|"checks device key"| node_device_repo
node_device_repo -->|"reads and writes"| node_sqlite
node_device_repo -->|"loads and saves"| node_state_model
node_device -->|"requests pages and buttons"| node_handlers
node_handlers -->|"processes navigation"| node_state_machine
node_handlers -->|"requests library content"| node_book_provider
node_handlers -->|"requests rendered frames"| node_renderer
node_handlers -->|"checks and updates frames"| node_frame_cache
node_provider_factory -->|"selects when configured"| node_kavita
node_kavita -->|"calls REST API"| node_kavita_service
node_provider_factory -.->|"selects when configured"| node_localfs
node_renderer -->|"captures pages"| node_browser
node_terminal_actor -->|"navigates and reads"| node_tui
node_tui -->|"loads book content"| node_book_provider

click node_server "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/core/server.go"
click node_composition "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/server/server.go"
click node_handlers "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/handlers/routes.go"
click node_middleware "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/middleware/middleware.go"
click node_auth "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/middleware/auth.go"
click node_device_repo "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/device/repository.go"
click node_sqlite "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/database/db.go"
click node_state_machine "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/state/machine.go"
click node_state_model "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/state/models.go"
click node_book_provider "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/library/provider.go"
click node_provider_factory "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/factory.go"
click node_kavita "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/kavita/kavita.go"
click node_localfs "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/localfs/localfs.go"
click node_renderer "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/render/image.go"
click node_frame_cache "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/render/cache.go"
click node_tui "https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/tui/app.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_server,node_composition,node_middleware,node_auth toneBlue
class node_handlers toneAmber
class node_book_provider,node_provider_factory,node_kavita,node_localfs,node_renderer,node_frame_cache,node_kavita_service toneMint
class node_device_repo,node_sqlite,node_state_machine,node_state_model toneRose
class node_tui,node_device,node_browser,node_terminal_actor toneIndigo
```

## Components

### Application Runtime

- [HTTP server](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/core/server.go): `internal/core/server.go`
- [Service bootstrap](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/server/server.go): `internal/server/server.go`
- [Request middleware](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/middleware/middleware.go): `internal/middleware/middleware.go`
- [Device authentication](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/middleware/auth.go): `internal/middleware/auth.go`

### Device Reading

- [API handlers](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/handlers/routes.go): `internal/handlers/routes.go`

### Book Content

- [Book provider](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/library/provider.go): `internal/library/provider.go`
- [Provider factory](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/factory.go): `internal/provider/factory.go`
- [Kavita connector](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/kavita/kavita.go): `internal/provider/kavita/kavita.go`
- [Local filesystem provider](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/provider/localfs/localfs.go): `internal/provider/localfs/localfs.go`
- [E-ink renderer](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/render/image.go): `internal/render/image.go`
- [Frame cache](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/render/cache.go): `internal/render/cache.go`

### Device State

- [Device repository](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/device/repository.go): `internal/device/repository.go`
- [SQLite database](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/database/db.go): `internal/database/db.go`
- [Navigation state machine](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/state/machine.go): `internal/state/machine.go`
- [Navigation state](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/state/models.go): `internal/state/models.go`

### Terminal Reader

- [Terminal UI](https://github.com/priyanshu-t-singh/le-grimoire/blob/main/internal/tui/app.go): `internal/tui/app.go`

### Other components

- **E-ink device**
- **Kavita server**
- **Chromium**
- **Terminal reader**

## Connections

- Service bootstrap → Book provider: creates and connects
- Service bootstrap → Provider factory: selects provider
- Service bootstrap → Device repository: creates
- Service bootstrap → Navigation state machine: creates
- Service bootstrap → E-ink renderer: creates
- Service bootstrap → Frame cache: creates
- Service bootstrap → SQLite database: opens
- Service bootstrap → API handlers: wires dependencies
- Service bootstrap → HTTP server: starts
- HTTP server → Request middleware: wraps router
- Request middleware → Device authentication: dispatches through
- Device authentication → Device repository: checks device key
- Device repository → SQLite database: reads and writes
- Device repository → Navigation state: loads and saves
- E-ink device → API handlers: requests pages and buttons
- API handlers → Navigation state machine: processes navigation
- API handlers → Book provider: requests library content
- API handlers → E-ink renderer: requests rendered frames
- API handlers → Frame cache: checks and updates frames
- Provider factory → Kavita connector: selects when configured
- Kavita connector → Kavita server: calls REST API
- Provider factory → Local filesystem provider: selects when configured
- E-ink renderer → Chromium: captures pages
- Terminal reader → Terminal UI: navigates and reads
- Terminal UI → Book provider: loads book content