# hughhowey/neo architecture

> Architecture diagram of the GitHub repository hughhowey/neo, 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/hughhowey/neo
- Repository: https://github.com/hughhowey/neo

## Overview

NEO is a local-first, distraction-free book-writing app. Authors organize books on shelves, write and structure chapters, manage outlines and deferred passages, track goals, then export or back up manuscripts. The Electron renderer owns the writing experience and calls desktop services through a preload bridge; those services store readable files locally. Cover design and optional AI painting augment the bookshelf. Pocket is an Android companion that reads and writes the same library files. Several product features are documented but their implementation was not sampled, so their wiring is shown only where supported.

Main entry points: [`app.js`](https://github.com/hughhowey/neo/blob/main/app.js) (App renderer), [`main.js`](https://github.com/hughhowey/neo/blob/main/main.js) (Electron shell), [`preload.js`](https://github.com/hughhowey/neo/blob/main/preload.js) (Preload bridge), [`art.js`](https://github.com/hughhowey/neo/blob/main/art.js) (AI cover painting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_renderer["App renderer<br/>[app.js]"]
  node_shell["Electron shell<br/>[main.js]"]
  node_bridge["Preload bridge<br/>[preload.js]"]
end

subgraph group_writing["Writing workflow"]
  node_shelves["Bookshelf<br/>[app.js]"]
  node_editor["Manuscript editor<br/>[app.js]"]
  node_outline["Outline and notes<br/>[app.js]"]
  node_darlings["Darlings and stickies<br/>[app.js]"]
  node_goals["Goals and progress<br/>[app.js]"]
  node_coverdesign["Cover design<br/>[covers.js]"]
  node_coverui["Cover workflow<br/>[app.js]"]
end

subgraph group_storage["Library and files"]
  node_library[("Library files<br/>[main.js]")]
end

subgraph group_services["Import and output"]
  node_import["Manuscript import<br/>[main.js]"]
  node_export["Document export<br/>[app.js]"]
  node_backup["Zip backups<br/>[main.js]"]
  node_spell["On-demand spellcheck<br/>[main.js]"]
  node_art["AI cover painting<br/>[art.js]"]
end

subgraph group_pocket["Pocket companion"]
  node_pocketapp["Pocket web app<br/>[index.html]"]
  node_pocketbridge["Pocket file bridge<br/>[pocket-bridge.js]"]
  node_android["Android host<br/>[MainActivity.java]"]
  node_sharedfiles[("Shared library files")]
end

node_author(("Author"))
node_localfiles[("Author's disk")]
node_openai{{"OpenAI"}}

node_author -->|"uses"| node_renderer
node_renderer -->|"renders"| node_shelves
node_renderer -->|"opens books"| node_editor
node_renderer -->|"manages"| node_outline
node_renderer -->|"manages"| node_darlings
node_renderer -->|"tracks"| node_goals
node_renderer -->|"manages"| node_coverui
node_renderer -->|"renders covers"| node_coverdesign
node_renderer -->|"prepares exports"| node_export
node_renderer -->|"requests checks"| node_spell
node_renderer -->|"calls API"| node_bridge
node_bridge -->|"invokes IPC"| node_shell
node_shell -->|"reads and writes"| node_library
node_library -->|"stores"| node_localfiles
node_renderer -->|"requests import"| node_import
node_import -->|"creates books"| node_library
node_export -->|"saves output"| node_bridge
node_shell -->|"creates archives"| node_backup
node_backup -->|"archives library"| node_localfiles
node_coverui -->|"requests painting"| node_bridge
node_bridge -->|"dispatches painting"| node_shell
node_shell -->|"calls"| node_art
node_art -.->|"requests text and images"| node_openai
node_art -->|"stores painting"| node_library
node_android -->|"hosts"| node_pocketapp
node_pocketapp -->|"calls file API"| node_pocketbridge
node_pocketbridge -->|"reads and writes"| node_sharedfiles
node_sharedfiles -.->|"syncs optionally"| node_localfiles

click node_renderer "https://github.com/hughhowey/neo/blob/main/app.js"
click node_shell "https://github.com/hughhowey/neo/blob/main/main.js"
click node_bridge "https://github.com/hughhowey/neo/blob/main/preload.js"
click node_shelves "https://github.com/hughhowey/neo/blob/main/app.js"
click node_editor "https://github.com/hughhowey/neo/blob/main/app.js"
click node_outline "https://github.com/hughhowey/neo/blob/main/app.js"
click node_darlings "https://github.com/hughhowey/neo/blob/main/app.js"
click node_goals "https://github.com/hughhowey/neo/blob/main/app.js"
click node_coverdesign "https://github.com/hughhowey/neo/blob/main/covers.js"
click node_coverui "https://github.com/hughhowey/neo/blob/main/app.js"
click node_library "https://github.com/hughhowey/neo/blob/main/main.js"
click node_import "https://github.com/hughhowey/neo/blob/main/main.js"
click node_export "https://github.com/hughhowey/neo/blob/main/app.js"
click node_backup "https://github.com/hughhowey/neo/blob/main/main.js"
click node_spell "https://github.com/hughhowey/neo/blob/main/main.js"
click node_art "https://github.com/hughhowey/neo/blob/main/art.js"
click node_pocketapp "https://github.com/hughhowey/neo/blob/main/pocket/www/index.html"
click node_pocketbridge "https://github.com/hughhowey/neo/blob/main/pocket/www/pocket-bridge.js"
click node_android "https://github.com/hughhowey/neo/blob/main/pocket/android/app/src/main/java/com/hughhowey/neopocket/MainActivity.java"

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_renderer,node_shell,node_bridge toneBlue
class node_shelves,node_editor,node_outline,node_darlings,node_goals,node_coverdesign,node_coverui,node_localfiles toneAmber
class node_library toneMint
class node_import,node_export,node_backup,node_spell,node_art toneRose
class node_pocketapp,node_pocketbridge,node_android,node_sharedfiles,node_author,node_openai toneIndigo
```

## Components

### Desktop experience

- [App renderer](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Electron shell](https://github.com/hughhowey/neo/blob/main/main.js): `main.js`
- [Preload bridge](https://github.com/hughhowey/neo/blob/main/preload.js): `preload.js`

### Writing workflow

- [Bookshelf](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Manuscript editor](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Outline and notes](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Darlings and stickies](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Goals and progress](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Cover design](https://github.com/hughhowey/neo/blob/main/covers.js): `covers.js`
- [Cover workflow](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`

### Library and files

- [Library files](https://github.com/hughhowey/neo/blob/main/main.js): `main.js`

### Import and output

- [Manuscript import](https://github.com/hughhowey/neo/blob/main/main.js): `main.js`
- [Document export](https://github.com/hughhowey/neo/blob/main/app.js): `app.js`
- [Zip backups](https://github.com/hughhowey/neo/blob/main/main.js): `main.js`
- [On-demand spellcheck](https://github.com/hughhowey/neo/blob/main/main.js): `main.js`
- [AI cover painting](https://github.com/hughhowey/neo/blob/main/art.js): `art.js`

### Pocket companion

- [Pocket web app](https://github.com/hughhowey/neo/blob/main/pocket/www/index.html): `pocket/www/index.html`
- [Pocket file bridge](https://github.com/hughhowey/neo/blob/main/pocket/www/pocket-bridge.js): `pocket/www/pocket-bridge.js`
- [Android host](https://github.com/hughhowey/neo/blob/main/pocket/android/app/src/main/java/com/hughhowey/neopocket/MainActivity.java): `pocket/android/app/src/main/java/com/hughhowey/neopocket/MainActivity.java`
- **Shared library files**

### Other components

- **Author**
- **Author's disk**
- **OpenAI**

## Connections

- Author → App renderer: uses
- App renderer → Bookshelf: renders
- App renderer → Manuscript editor: opens books
- App renderer → Outline and notes: manages
- App renderer → Darlings and stickies: manages
- App renderer → Goals and progress: tracks
- App renderer → Cover workflow: manages
- App renderer → Cover design: renders covers
- App renderer → Document export: prepares exports
- App renderer → On-demand spellcheck: requests checks
- App renderer → Preload bridge: calls API
- Preload bridge → Electron shell: invokes IPC
- Electron shell → Library files: reads and writes
- Library files → Author's disk: stores
- App renderer → Manuscript import: requests import
- Manuscript import → Library files: creates books
- Document export → Preload bridge: saves output
- Electron shell → Zip backups: creates archives
- Zip backups → Author's disk: archives library
- Cover workflow → Preload bridge: requests painting
- Preload bridge → Electron shell: dispatches painting
- Electron shell → AI cover painting: calls
- AI cover painting → OpenAI: requests text and images
- AI cover painting → Library files: stores painting
- Android host → Pocket web app: hosts
- Pocket web app → Pocket file bridge: calls file API
- Pocket file bridge → Shared library files: reads and writes
- Shared library files → Author's disk: syncs optionally