Backend Spec

Goal:

Serve HTML pages and fragments for a responsive web app
Keep the backend thin but explicit
Use the existing API contract as the data source

Responsibilities

The backend should:

Render full pages for first load and direct navigation
Render partial fragments for HTMX swaps
Proxy or adapt the existing API endpoints
Handle authentication and session state
Validate forms before sending data to the upstream API

Suggested Flow

Browser -> Backend page route -> Backend renders HTML -> HTMX requests fragment routes when needed -> Backend calls upstream API -> Backend returns HTML fragment or redirect

Data Handling

Keep a small server-side adapter layer for:

login
token storage
order creation
result lookup
patient registration
password change
special message submission

HTTP Patterns

Use standard web forms for non-dynamic actions.

Use HTMX for:

table filtering
list refresh
modal content
detail pane updates
stepper transitions

Session Strategy

Prefer one of these:

Server session cookie
Signed session token stored server-side

Avoid exposing long-lived API tokens directly to the browser unless the backend design truly requires it.

Validation

Validate on both sides:

browser for quick feedback
backend for trust

Error Handling

Return clear HTML states for:

invalid login
expired session
upstream API error
empty search result
validation failure

Responsive Output Rules

Desktop pages should be wide enough for sidebars and tables
Mobile pages should collapse to single-column layouts
Partial responses should never depend on client-side rendering state

1.7 KiB Raw Blame History