Upload files to "project-specs"

2026-04-13 11:26:58 +07:00
parent 82aecb7e9d
commit 98939f050a
5 changed files with 380 additions and 0 deletions
--- a/project-specs/BACKEND_SPEC.md
+++ 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
+
--- a/project-specs/ROUTES.md
+++ 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.
+
--- a/project-specs/SCREEN_MAP.md
+++ 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.
+
--- a/project-specs/TECH_STACK.md
+++ 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.
--- a/project-specs/TEMPLATE_STRUCTURE.md
+++ 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
+