diff --git a/project-specs/BACKEND_SPEC.md b/project-specs/BACKEND_SPEC.md new file mode 100644 index 0000000..cca7399 --- /dev/null +++ b/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 + diff --git a/project-specs/ROUTES.md b/project-specs/ROUTES.md new file mode 100644 index 0000000..f9a056c --- /dev/null +++ b/project-specs/ROUTES.md @@ -0,0 +1,69 @@ +# Routes + +This is a proposed route map for the rebuilt app using server-rendered pages plus HTMX fragments. + +## Public + +| Route | Purpose | +| --- | --- | +| `/login` | Login page | +| `/problem-login` | Login error / access problem screen | +| `/splash` | Initial redirect / loading screen | + +## App Shell + +| Route | Purpose | +| --- | --- | +| `/` | Dashboard home | +| `/orders` | Order list | +| `/results` | Result list / history | +| `/fpp` | FPP area | +| `/patients` | Patient registration landing | +| `/settings` | Account and profile area | + +## Order Flow + +| Route | Purpose | +| --- | --- | +| `/orders/new` | Start new order / patient registration | +| `/orders/new/demografi` | Demographic step | +| `/orders/new/diagnosa` | Diagnosis step | +| `/orders/new/pemeriksaan` | Examination step | +| `/orders/new/qrcode` | QR-based entry | +| `/orders/new/review` | Review and submit | +| `/orders/:id` | Order detail | +| `/orders/:id/pesan-khusus` | Special message | + +## Results Flow + +| Route | Purpose | +| --- | --- | +| `/results/historical` | Historical results | +| `/results/pending` | Result pending list | +| `/results/:id` | Result detail | + +## Settings + +| Route | Purpose | +| --- | --- | +| `/settings/change-password` | Change password form | +| `/settings/account` | Profile/account page | + +## HTMX Fragment Routes + +| Route | Purpose | +| --- | --- | +| `/fragments/orders/table` | Filtered order table | +| `/fragments/orders/detail/:id` | Order detail pane | +| `/fragments/results/table` | Result table or cards | +| `/fragments/results/detail/:id` | Result detail pane | +| `/fragments/fpp/list` | FPP list fragment | +| `/fragments/forms/order-step/:step` | Form step content | +| `/fragments/modals/pesan-khusus` | Special message modal content | + +## Notes + +- Keep route names boring and predictable. +- Use fragments for dynamic updates, not full page duplication. +- Avoid the old app habit of making every step a separate top-level page unless it truly helps navigation. + diff --git a/project-specs/SCREEN_MAP.md b/project-specs/SCREEN_MAP.md new file mode 100644 index 0000000..2763357 --- /dev/null +++ b/project-specs/SCREEN_MAP.md @@ -0,0 +1,41 @@ +# Screen Map + +This maps the route names found in the compiled build to a cleaner new-project structure. + +## Old To New + +| Old route / screen | New module | Notes | +| --- | --- | --- | +| `/splashScreen` | `auth/splash` | Startup / redirect logic | +| `/problemLoginRoute` | `auth/problem-login` | Login error or auth problem state | +| Login screen | `auth/login` | Uses `auth/login` API | +| `/changePasswordRoute` | `settings/change-password` | Uses `auth/change_password` | +| `/pendaftaranPasienStepper` | `orders/create/stepper` | Multi-step patient registration | +| `/pendaftaranPasien` | `orders/create` | Base registration form | +| `/pendaftaranPasienDemografi` | `orders/create/demografi` | Demographic step | +| `/pendaftaranPasienDiagnosa` | `orders/create/diagnosa` | Diagnosis step | +| `/pendaftaranPasienPemeriksaan` | `orders/create/pemeriksaan` | Exam selection step | +| `/pendaftaranPasienPemeriksaanv2` | `orders/create/pemeriksaan-v2` | Newer exam step variant | +| `/pendaftaranPasienQrCode` | `orders/create/qrcode` | QR-based patient entry | +| `/pesanKhususScreen` | `orders/pesan-khusus` | Special message entry | +| `/historicalResult` | `results/historical` | Historical results view | +| `/hasilBelumKeluar` | `results/pending` | Orders with results not yet released | +| `/hasil` | `results/detail` | Result detail view | +| `Order` tab | `orders/list` | Order listing and search | +| `Home` tab | `dashboard/home` | Landing dashboard | +| `Akun` tab | `settings/account` | Account/profile area | + +## Data-Flows To Preserve + +- Login returns token and user metadata +- Order creation posts patient identity plus detail items +- Search uses token + doctor id + search string +- Result retrieval uses token + patient or order id +- Special message uses token + order id + message text + +## Notes + +- The old app is heavily mobile-first and route-heavy. +- The new app should collapse many of those routes into fewer, clearer pages. +- Where a route is just a step in a form, keep it inside a single flow rather than separate full pages. + diff --git a/project-specs/TECH_STACK.md b/project-specs/TECH_STACK.md new file mode 100644 index 0000000..9d8469e --- /dev/null +++ b/project-specs/TECH_STACK.md @@ -0,0 +1,86 @@ +# Tech Stack Recommendation + +## Short Answer + +If you are rebuilding this app from scratch, I would use: + +- HTMX + Tailwind if you want a simple server-rendered web app +- Flutter Web only if you want to stay in the Flutter ecosystem + +## Recommendation + +For this app, HTMX + Tailwind is the better default if the priority is: + +- simpler architecture +- faster screen-by-screen rebuild +- less frontend complexity +- server-rendered HTML with progressive enhancement + +Flutter Web is still viable if: + +- you want to preserve Flutter skills +- you expect the app to stay mostly in the Flutter ecosystem +- you are okay spending more time on desktop layout tuning + +React is also viable, but it is more framework than you need if the app mostly consists of forms, lists, and detail pages. + +## Suggested Stack + +### Frontend + +- HTMX +- Tailwind CSS +- server templates +- optional Alpine.js for small interactions +- optional server-side form validation helpers + +### UI Structure + +- responsive app shell +- partial page updates +- reusable template fragments +- shared table/card patterns +- modal and drawer patterns only when needed + +### Data + +- server-side API adapter +- request/response DTO layer +- session or token handling on the backend +- HTML forms with progressive enhancement + +### Testing + +- backend unit tests for API adapter and request parsing +- template rendering tests for key pages +- smoke tests for login and order flow + +## Why This Fits the Problem + +- The current app is mobile-heavy and likely needs a cleaner desktop shell. +- HTMX keeps the frontend thin while still allowing dynamic interactions. +- Tailwind gives fast control over responsive layouts without building a large component system. +- Server-rendered pages are easier to keep consistent while you rebuild screen by screen. + +## If You Stay On Flutter + +Use: + +- Flutter Web +- go_router +- Riverpod or Bloc +- responsive layout helpers +- separate desktop sidebar shell from mobile bottom-nav shell + +Flutter is fine, but the layout work will be more manual. + +## If You Choose HTMX + Tailwind + +Use: + +- backend templates for pages and fragments +- HTMX for partial swaps +- Tailwind utility classes for responsive layout +- a small amount of JS only for UI gaps HTMX does not cover + +This is the cleanest fit if you want the new app to stay simple and maintainable. diff --git a/project-specs/TEMPLATE_STRUCTURE.md b/project-specs/TEMPLATE_STRUCTURE.md new file mode 100644 index 0000000..30f883a --- /dev/null +++ b/project-specs/TEMPLATE_STRUCTURE.md @@ -0,0 +1,102 @@ +# Template Structure + +Recommended file organization for an HTMX + Tailwind rebuild. + +## Example Layout + +```text +app/ + templates/ + layouts/ + base.html + auth.html + shell.html + pages/ + login.html + dashboard.html + orders/ + list.html + detail.html + new.html + results/ + list.html + detail.html + fpp/ + list.html + settings/ + account.html + change-password.html + fragments/ + orders/ + table.html + detail.html + stepper.html + results/ + table.html + detail.html + fpp/ + list.html + modals/ + pesan-khusus.html + components/ + sidebar.html + topbar.html + cards.html + table.html + empty-state.html + form-fields.html + pagination.html +``` + +## Layouts + +### `base.html` + +- Includes global Tailwind styles +- Loads HTMX +- Defines meta tags and page title + +### `auth.html` + +- Used for login and problem-login screens +- Simple centered layout + +### `shell.html` + +- Used for authenticated app pages +- Includes sidebar on desktop and nav on mobile + +## Components + +Keep components small and reusable: + +- sidebar +- topbar +- action bar +- stat cards +- search/filter bar +- table rows +- empty states +- confirm dialogs +- modal shells + +## Fragment Rules + +- A fragment should contain only the markup needed for the swap target +- Fragments must be valid standalone HTML snippets +- Do not duplicate full page layout in a fragment + +## Tailwind Rules + +- Use a consistent spacing scale +- Define semantic color tokens in the design system layer +- Make desktop breakpoints explicit +- Prefer utility composition over custom CSS unless a pattern repeats often + +## Responsive Behavior + +- Mobile first +- Sidebar becomes drawer or bottom nav +- Tables become cards on small screens +- Forms collapse to one column +