Architecture and deployment notes for the office stack #5

New issue

Closed

opened 2026-04-26 07:47:40 +00:00 by zaelgohary · 0 comments

zaelgohary commented

2026-04-26 07:47:40 +00:00

Member

Acceptance

A short README.md (or doc/architecture.md) in the hero_office repo covering:

Component map: hero_office_server (RPC) <-> hero_office_ui (HTML host) <-> hero_office_bridge (UDS -> TCP) <-> onlyoffice-documentserver Docker container.
doc_key derivation (context + filename + mtime), why mtime matters, when to touch a file to force a fresh key.
On-disk cache layout: /var/lib/onlyoffice/documentserver/App_Data/cache/files/data/<key>/{Editor.bin,origin.<ext>}. When to wipe.
Required headers: hero_router must inject X-Forwarded-Host so docservice does not emit http://localhost/... cache URLs.
Standard failure modes: "Download failed" = wrong host in Editor.bin URL; "Unknown error" = poisoned cache, clear and touch source.

There is no doc explaining how the office stack hangs together. Anyone debugging an editor failure has to retrace the diagnostics from scratch — proxy chain, doc_key semantics, cache-poisoning class. ## Acceptance A short README.md (or `doc/architecture.md`) in the hero_office repo covering: - Component map: hero_office_server (RPC) <-> hero_office_ui (HTML host) <-> hero_office_bridge (UDS -> TCP) <-> onlyoffice-documentserver Docker container. - doc_key derivation (`context + filename + mtime`), why mtime matters, when to touch a file to force a fresh key. - On-disk cache layout: `/var/lib/onlyoffice/documentserver/App_Data/cache/files/data/<key>/{Editor.bin,origin.<ext>}`. When to wipe. - Required headers: hero_router must inject `X-Forwarded-Host` so docservice does not emit `http://localhost/...` cache URLs. - Standard failure modes: "Download failed" = wrong host in Editor.bin URL; "Unknown error" = poisoned cache, clear and touch source.