# 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:

1. Render full pages for first load and direct navigation
2. Render partial fragments for HTMX swaps
3. Proxy or adapt the existing API endpoints
4. Handle authentication and session state
5. 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:

1. Server session cookie
2. 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