The main application is a TypeScript modular service: a Hono API and React/Vite assets share domain operations. The native companion and MCP handler call those same operations. Private PDF processing and external transport adapters sit across explicit boundaries; they do not own approval or quota decisions.
Open the Mermaid diagrams for logical system, dispatch and document flows with downloadable sources.
Read the complete explanation
- Workers control. The API and MCP surface call the shared domain service. Tenant context comes from authenticated membership; permissions and approval are checked on the server.
- Private persistence. D1 stores business records, approval, quota and the outbox. R2 stores private document bytes. Download access is scoped; the public website is not the document store.
- Validate and queue. Private document services inspect or transform documents. Accepted work is published from the outbox to a queue. Queue transport can repeat; an attempt claim protects provider submission.
- External delivery. Telnyx handles fax, Pingen handles printing and post, and Resend handles email. Provider callbacks and reconciliation update the domain record. Acceptance does not prove final delivery.
Runtime responsibilities
| Component | Owns | Boundary |
|---|---|---|
| Application Worker | Authentication, route contracts and service orchestration | Resolve current workspace authority or the separate personal owner principal, according to the route |
| D1 | Membership, immutable versions, dispatches, approvals, budgets, outbox and durable events | Constraints and transactional writes enforce business commitments |
| R2 | Exact private PDFs/source objects and independently encrypted shared/personal objects | Object keys grant no access; authorized reads recheck policy and integrity |
| Document Worker | Isolated rendering, page review and postal document checks | Explicit private bindings and bounded inputs/outputs |
| Scanner | Antivirus verification of the exact submitted bytes | Missing, stale or mismatched proof cannot promote a PDF to ready |
| PDF validator | Separate PDF conformance/accessibility diagnostics | Diagnostics do not replace security verification or modify originals |
| Queues and consumers | Asynchronous provider work from durable references | Duplicate messages do not create unconditional duplicate attempts |
| Provider adapters | Fax, email and postal request/response translation | Enabled configuration is necessary but does not itself approve a dispatch |
The application can run production rules against synthetic local data for tests. That execution mode is distinct from contacting a hosted provider. The independent browser-only preview has no business bindings at all.
Why D1 is the commitment boundary
A communication must not be queued without a matching approval and reservation. Acceptance therefore commits the dispatch transition, quota reservation and outbox row atomically. SQL constraints and triggers participate in that invariant; moving one check into a client would weaken it.
An outbox publisher transfers persisted work to an interactive or bulk queue. Publication may repeat after a lost acknowledgement. A consumer conditionally claims the eligible dispatch and records an attempt before contacting a provider. The dispatch lifecycle explains the states and the treatment of uncertainty.
Private processing is a separate trust boundary
PDFs and source archives are untrusted input. The API bounds input before heavier processing; private services return bounded verification/rendering results tied to the expected bytes. Rendering a document creates a new immutable object rather than editing an original already used by a dispatch.
Service bindings are intentional private connections. They are not an invitation to accept arbitrary user-supplied service URLs. Public HTTPS import has its own egress and redirect rules, separate from private scanner/renderer access.
Identity and external systems
Auth0 supplies identity/OAuth tokens. Current membership, connection binding, revocation, role permissions and any delegation remain application decisions. Telnyx, Pingen and Resend/SES adapters supply transport facts; their responses do not overwrite the approval model. Verified callbacks become durable events before status projection.
The status service is independently deployed and observes bounded public endpoints. Its health observations are not access to customer documents or proof that an authenticated delivery journey succeeds. This engineering site is a static documentation surface with no business binding. The separate Belvédère administration guide explains platform oversight, its metadata-only projections and its operator authority.
External services have specific jobs
| Dependency | What Guteneo delegates | What remains in Guteneo |
|---|---|---|
| Auth0 | Identity-provider login and authorization-server token evidence | Stable identity mapping, current sessions/membership, document policy, role/scopes and approval |
| Telnyx | Fax submission, outcome callbacks and supported usage reads | Qualified route/price policy, exact approved bytes, funded ceiling, attempt fencing and reconciliation |
| Pingen | Postal preparation/calculation and authorized letter processing | Transfer consent, final preparation equivalence, approval and send authority |
| Resend / SES | Configured email transport and authenticated provider events | Sender/recipient policy, account/workspace quotas, quote, approval and outcome interpretation |
| Stripe | Existing customer/customer-portal operations and signed billing-object events | Browser administrator access, application credit/entitlement ledger and webhook deduplication |
These dependencies are not interchangeable fallbacks. Their enabled flags and credentials do not grant consent, and one provider’s qualification cannot prove another’s route or billing semantics. Provider maintenance explains tariff/contract refresh without rewriting approved commitments.
Queues also carry secure rendering and personal-deposit work, separately from provider dispatch. Scheduled reconciliation handles durable callbacks, leases, scans, Studio jobs, secure jobs and bounded retention. Read background jobs for ordering and recovery.
Browser rendering, scheduling and optional services
The private document Worker uses Cloudflare’s browser binding for isolated PDF processing, final-page review and supported document generation. Browser execution is a processing dependency with its own resource/corpus/residency qualification; it is not a general browser session in the recipient’s account. The local browser substitute exercises controlled tests, not hosted Browser Run performance.
Cron drives the application’s bounded reconciliation/maintenance; a separate status Cron performs anonymous availability reads. Queues carry recorded work, while D1 remains the commitment authority. Current application configuration does not declare a Durable Objects binding: realtime Durable Objects/WebSocket ideas in older design studies are proposals, not the current polling implementation. Do not add a fourth state store to a diagram because Cloudflare supports it.
Likewise, the current live configuration has no Workers AI binding. The optional Studio model adapter is a separately configured proposal generator; it is not live-qualified by source presence and cannot approve, send or bypass deterministic schema validation. No confidential PDF is implicitly routed to Cloudflare AI. Future provider/model integration needs an explicit data-transfer, capability, cost and review contract, plus synchronized engineering documentation.
Legacy SES/SNS email remains an adapter/configuration path with its own regional sender, topic and signature requirements; it is not a second automatically active email transport or a fallback around Resend. Historical SNS/host-migration notes remain dated evidence. Read current capability/configuration rather than inferring activation from an old provider record.
Billing projections also remain bounded: current browser administrator and applicable Horizon entitlement guard billing reads/actions; assistant tokens cannot open a customer portal. Signed Stripe events are deduplicated and canonical objects reread before projection. Promotional credit, sending reservations and monthly credit-funded entitlement are distinct from a Stripe invoice or card charge. There is no automatic purchase/top-up/checkout implied by this module, and source tests establish no live commercial account.
Location and qualification
The checked-in configuration uses EU jurisdiction for relevant D1/R2 resources. That setting is not a claim that all identity, browser execution, provider, subprocessor, log or backup processing occurs in Europe. Runtime configuration, external contracts and actual hosted journeys require their own qualification.
Continue with the data model for record relationships, authority and tenancy for access decisions and security and reliability for the controls that survive failures.