Upload files to "project-specs"

project-specs/BACKEND_SPEC.md

@@ -0,0 +1,82 @@
+# 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
+