lhumina_code/hero_books
20
0
Fork 0
Code Issues 7 Pull requests 2 Projects Releases 1 Packages Wiki Activity Actions

make herobooks API driven & make widget #10

New issue
Open
opened 2026-02-07 14:50:06 +00:00 by despiegk · 4 comments
despiegk commented 2026-02-07 14:50:06 +00:00
Owner
Copy link

make oschema driven

  • make good prompt (skill): to convert openrpc server to schema driven server (oschema), make build.rs (skill)
  • result: a server like hero0 which we can now access over http
  • on server: make sure accept server requests (cors)
  • better documentation wise

convert UI

  • to webassembly dioxus
  • widget: links to proper URL, chose library, ...

remarks

  • no security
## make oschema driven - make good prompt (skill): to convert openrpc server to schema driven server (oschema), make build.rs (skill) - result: a server like hero0 which we can now access over http - on server: make sure accept server requests (cors) - better documentation wise ## convert UI - to webassembly dioxus - widget: links to proper URL, chose library, ... ## remarks - no security
despiegk added this to the now milestone 2026-02-07 14:50:06 +00:00
despiegk added this to the ACTIVE project 2026-02-07 14:50:06 +00:00
despiegk commented 2026-02-07 14:52:17 +00:00
Author
Owner
Copy link

see #4

see #4
despiegk commented 2026-02-07 15:04:54 +00:00
Author
Owner
Copy link

all stays in herobooks

all stays in herobooks
despiegk modified the milestone from now to next 2026-02-07 15:05:01 +00:00
despiegk removed this from the ACTIVE project 2026-02-07 15:12:47 +00:00
mik-tf commented 2026-02-09 23:35:27 +00:00
Owner
Copy link

Implementation Plan

Full plan: docs/plan.md

Part 1: OSchema-Driven API

Convert the monolithic tiny_http server (~4,900 LOC, 30+ hand-routed endpoints) into a schema-first JSON-RPC server with auto-generated types and dispatch.

What already exists:

  • 9 oschema files in specs/schemas/publishing/ (data types)
  • Generated OSIS server in src/publishing/server/ (auto-CRUD for 6 root objects)
  • herolib-osis dependency with rpc feature
  • Axum + Tokio in Cargo.toml (unused — tiny_http is current)

Phases:

Phase 1: Define web service oschema

  • specs/schemas/webservice/books.oschema — browsing & listing
  • specs/schemas/webservice/search.oschema — search & AI summary
  • specs/schemas/webservice/pdf.oschema — PDF generation, versions, permalinks
  • specs/schemas/webservice/import.oschema — collection import
  • specs/schemas/webservice/admin.oschema — admin & system ops

14 RPC methods mapped from current handlers:

RPC method Current handler Description
books.list serve_books_api List all books
books.list_libraries serve_index List libraries with counts
books.list_by_library serve_library Books in a library/namespace
books.get serve_book Book detail with pages
books.get_page serve_page Page content (rendered HTML)
search.query serve_search_api Semantic search
search.ai_summary serve_ai_summary_api AI-generated summary
search.transcribe serve_transcribe_api Audio to text
pdf.generate_book serve_book_pdf Generate book PDF
pdf.generate_page serve_page_pdf Generate page PDF
pdf.list_versions serve_pdf_versions_api PDF version history
pdf.convert_url serve_convert_submit Markdown URL to PDF
import.start serve_import_submit Start collection import
import.get_log serve_import_log Import job progress

Phase 2: Generate server code

  • Add webservice domain to build.rs
  • Run oschema generator, commit generated types and RPC dispatcher
  • Implement RPC method handlers in rpc.rs
  • Wire into /rpc endpoint

Phase 3: Migrate handlers to RPC

  • Refactor HTML handlers to call RPC methods internally
  • JSON API handlers become pass-through to RPC
  • Verify all existing pages + APIs still work

Phase 4: Transition to Axum

  • Replace tiny_http with Axum async router
  • Add tower-http CORS middleware
  • Static file serving for WASM bundle
  • Async handlers (remove block_on workarounds)

Part 2: Dioxus Widget UI

Replace 13 Askama HTML templates (3,284 LOC) with a Dioxus 0.7 WebAssembly frontend.

Phase 1: Scaffold Dioxus project

  • Create crates/hero-books-ui/ workspace member
  • Route definitions matching current URL structure
  • RPC client module, dev/build scripts

Phase 2: Core components

  • Navbar, ThemeToggle, Footer
  • SearchBar + VoiceInput
  • LibraryCard, BookCard, PageListItem
  • PdfVersionsDropdown, TagFilter, Toast

Phase 3: Feature pages (simplest first)

  • Docs, Home, Books
  • Library, Book, Page
  • Search, Import, Convert

Phase 4: Integration & deployment

  • Production WASM build, serve from server
  • Client-side routing, deploy to VM
  • Verify mobile + desktop, remove deprecated templates

Risk areas

Risk Mitigation
Voice recording in WASM web-sys Web Audio API; fallback endpoint
Mermaid diagrams Load Mermaid.js, call via web-sys
Large WASM bundle Code splitting, wasm-opt
Markdown rendering Return pre-rendered HTML from RPC
## Implementation Plan Full plan: [`docs/plan.md`](https://forge.ourworld.tf/lhumina_code/hero_books/src/branch/development/docs/plan.md) ### Part 1: OSchema-Driven API Convert the monolithic `tiny_http` server (~4,900 LOC, 30+ hand-routed endpoints) into a schema-first JSON-RPC server with auto-generated types and dispatch. **What already exists:** - 9 oschema files in `specs/schemas/publishing/` (data types) - Generated OSIS server in `src/publishing/server/` (auto-CRUD for 6 root objects) - `herolib-osis` dependency with `rpc` feature - Axum + Tokio in Cargo.toml (unused — tiny_http is current) **Phases:** **Phase 1: Define web service oschema** - [ ] `specs/schemas/webservice/books.oschema` — browsing & listing - [ ] `specs/schemas/webservice/search.oschema` — search & AI summary - [ ] `specs/schemas/webservice/pdf.oschema` — PDF generation, versions, permalinks - [ ] `specs/schemas/webservice/import.oschema` — collection import - [ ] `specs/schemas/webservice/admin.oschema` — admin & system ops 14 RPC methods mapped from current handlers: | RPC method | Current handler | Description | |------------|----------------|-------------| | `books.list` | `serve_books_api` | List all books | | `books.list_libraries` | `serve_index` | List libraries with counts | | `books.list_by_library` | `serve_library` | Books in a library/namespace | | `books.get` | `serve_book` | Book detail with pages | | `books.get_page` | `serve_page` | Page content (rendered HTML) | | `search.query` | `serve_search_api` | Semantic search | | `search.ai_summary` | `serve_ai_summary_api` | AI-generated summary | | `search.transcribe` | `serve_transcribe_api` | Audio to text | | `pdf.generate_book` | `serve_book_pdf` | Generate book PDF | | `pdf.generate_page` | `serve_page_pdf` | Generate page PDF | | `pdf.list_versions` | `serve_pdf_versions_api` | PDF version history | | `pdf.convert_url` | `serve_convert_submit` | Markdown URL to PDF | | `import.start` | `serve_import_submit` | Start collection import | | `import.get_log` | `serve_import_log` | Import job progress | **Phase 2: Generate server code** - [ ] Add `webservice` domain to `build.rs` - [ ] Run oschema generator, commit generated types and RPC dispatcher - [ ] Implement RPC method handlers in `rpc.rs` - [ ] Wire into `/rpc` endpoint **Phase 3: Migrate handlers to RPC** - [ ] Refactor HTML handlers to call RPC methods internally - [ ] JSON API handlers become pass-through to RPC - [ ] Verify all existing pages + APIs still work **Phase 4: Transition to Axum** - [ ] Replace `tiny_http` with Axum async router - [ ] Add `tower-http` CORS middleware - [ ] Static file serving for WASM bundle - [ ] Async handlers (remove `block_on` workarounds) ### Part 2: Dioxus Widget UI Replace 13 Askama HTML templates (3,284 LOC) with a Dioxus 0.7 WebAssembly frontend. **Phase 1: Scaffold Dioxus project** - [ ] Create `crates/hero-books-ui/` workspace member - [ ] Route definitions matching current URL structure - [ ] RPC client module, dev/build scripts **Phase 2: Core components** - [ ] `Navbar`, `ThemeToggle`, `Footer` - [ ] `SearchBar` + `VoiceInput` - [ ] `LibraryCard`, `BookCard`, `PageListItem` - [ ] `PdfVersionsDropdown`, `TagFilter`, `Toast` **Phase 3: Feature pages** (simplest first) - [ ] `Docs`, `Home`, `Books` - [ ] `Library`, `Book`, `Page` - [ ] `Search`, `Import`, `Convert` **Phase 4: Integration & deployment** - [ ] Production WASM build, serve from server - [ ] Client-side routing, deploy to VM - [ ] Verify mobile + desktop, remove deprecated templates ### Risk areas | Risk | Mitigation | |------|------------| | Voice recording in WASM | `web-sys` Web Audio API; fallback endpoint | | Mermaid diagrams | Load Mermaid.js, call via `web-sys` | | Large WASM bundle | Code splitting, wasm-opt | | Markdown rendering | Return pre-rendered HTML from RPC |
mik-tf commented 2026-02-09 23:36:07 +00:00
Owner
Copy link

Branching Strategy

See BRANCHING.md for full details.

main — Stable, public-facing

Currently deployed at https://herobooks.gent02.grid.tf. Only receives critical bug fixes.

development — Active feature work

All Part 1 + Part 2 work happens here. No merge to main until the full plan is complete and verified.

Bug fix flow

  1. Fix on main (directly or via hotfix/ branch)
  2. Cherry-pick the fix into development
  3. Deploy main to VM

This works because:

  • Current HTML templates stay functional throughout — no user-facing breakage
  • Part 1 (oschema API) is additive — adds /rpc methods alongside existing routes, nothing removed
  • Part 2 (Dioxus) is a separate crate — does not touch existing server code until the final swap
  • Main stays deployable at all times
## Branching Strategy See [BRANCHING.md](https://forge.ourworld.tf/lhumina_code/hero_books/src/branch/main/BRANCHING.md) for full details. ### main — Stable, public-facing Currently deployed at https://herobooks.gent02.grid.tf. Only receives critical bug fixes. ### development — Active feature work All Part 1 + Part 2 work happens here. **No merge to main until the full plan is complete and verified.** ### Bug fix flow 1. Fix on main (directly or via hotfix/ branch) 2. Cherry-pick the fix into development 3. Deploy main to VM This works because: - Current HTML templates stay functional throughout — no user-facing breakage - Part 1 (oschema API) is additive — adds /rpc methods alongside existing routes, nothing removed - Part 2 (Dioxus) is a separate crate — does not touch existing server code until the final swap - Main stays deployable at all times
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_mik
cleanup/remove-deps-txt
main
v0.1.5
v0.1.4
v0.1.3
v0.1.2
v0.1.1
v0.1.0
v0.0.1-rc1
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
next
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_books#10
No description provided.