--- title: "Waroku Home-Visit Nursing — Cloud Care Platform — Tran Manh Tuan" description: "A cloud platform for home-visit nursing in Japan: patients and their homes, case records and handover, nursing orders and plans, visit schedules, reports and assessments." canonical: "https://tmtuan.dev/en/projects/waroku-home-visit-nursing" language: "en" image: "https://tmtuan.dev/_img/projects/waroku-home-visit-nursing/waroku-home-visit-nursing.1da7585d-og.jpg" tokens: 6111 --- # Waroku Home-Visit Nursing **Waroku Home-Visit Nursing** is a cloud platform for home-visit nursing in Japan. Nurses and care staff visit patients where they live, so the system has to hold more than a chart: who the patient is, the home they live in, what care was ordered, how it is planned and scheduled, what happened at each visit, and how the patient is progressing. In 2022 I was the **Project Leader and Tech Lead** of the development team in Vietnam. Our scope was the web frontend, in Vue with Vuetify, built against a REST API that the team in Japan delivered in stages. The team had several developers and an IT communicator; the specifications, designs and APIs came from Japan. > **Why it is a management-system project:** every module comes back to one patient — their information, home, case records, orders, plans, schedules, visit records, reports and assessments — and to one organisation of offices, staff and roles. A single visit touches the schedule, the record, the diary, the report and the next assessment. Keeping dozens of screens consistent with that model, while designs and APIs kept changing, was the core of the job. ## Modules and how they connect About twenty groups of screens cover sign-in, the header and global menu, patients, patient information and living environment, case records and handover, home-visit nursing records, nursing orders, plans, schedules, diaries and reports, patient assessment, the monthly inventory, a feedback report for a research partner, and the management of offices, staff, organisations and files. ```mermaid flowchart TB accTitle: Waroku Home-Visit Nursing system overview accDescr: Nurses, staff and administrators sign in, and sign-in sets their organisation, office and role. From there they reach patient management and a patient's information. Patient information leads to the living environment, to case records and handover, to assessment, and to the nursing order. The order leads to the nursing plan, the plan to the visit schedule, the schedule to the visit record, the record to the nursing diary, and the diary to the nursing report. Assessment leads to the monthly inventory and to the feedback report of the research-partner variant. STAFF["Nurses / staff / admins"] AUTH["Authentication"] ORG["Organisation / office / role"] PATIENT["Patient management"] INFO["Patient information"] ENV["Living environment"] CASE["Case record / handover"] ORDER["Nursing order"] PLAN["Nursing plan"] SCHEDULE["Visit schedule"] RECORD["Visit record"] DIARY["Nursing diary"] REPORT["Nursing report"] ASSESS["Assessment"] INVENTORY["Monthly inventory"] FEEDBACK["Partner feedback report"] STAFF --> AUTH AUTH --> ORG ORG --> PATIENT PATIENT --> INFO INFO --> ENV INFO --> CASE INFO --> ORDER ORDER --> PLAN PLAN --> SCHEDULE SCHEDULE --> RECORD RECORD --> DIARY DIARY --> REPORT INFO --> ASSESS ASSESS --> INVENTORY ASSESS --> FEEDBACK ``` _Everything starts from the context set at sign-in, and almost everything leads back to one patient._ ## My responsibilities - Reviewed implementation and pull requests, and checked that the UI and forms matched the design. - Owned the shared components and kept them consistent across developers. - Split and tracked tasks, handled issues that came up during each sprint and prioritised work to meet the client's milestones. - Resolved conflicts between the design and the API, and supported the team when an API was incomplete or differed from the design. - Tracked the progress of API integration. - Clarified requirements with the IT communicator and the team in Japan. - Controlled quality before screens went to QA testing, and assessed schedule and release risk. ## Sign-in, organisation and office Staff sign in with a user name and password, with a password reminder and a password change. A first sign-in with an initial password leads straight to changing it, which keeps account provisioning apart from the user's ownership of their password; otherwise the user lands on their initial page, usually the patient list. The sign-in and password APIs use an API key; after sign-in, every business API is called with the user's access token. The sign-in response carries the context the rest of the system depends on: organisation, office, staff member, role, account type, initial page and token expiry. The header shows the organisation, the current office and the signed-in user, and lets the user switch office. The global menu is not hard-coded: the API returns its levels, order and names for the account and role, so one platform serves different organisations and account types — the standard account, a variant for a research partner with some screens and reports of its own, and management accounts. ```mermaid flowchart TD accTitle: Account context after sign-in accDescr: Sign-in resolves the organisation, then the office within it, then the staff member and their role. The role decides the dynamic global menu, and the menu decides which features the user can reach. LOGIN["Sign-in"] ORG["Organisation"] OFFICE["Office"] STAFF["Staff"] ROLE["Role"] MENU["Dynamic global menu"] APP["Available features"] LOGIN --> ORG ORG --> OFFICE OFFICE --> STAFF STAFF --> ROLE ROLE --> MENU MENU --> APP ``` _Organisation, office, staff and role decide the menu — and the menu decides what the user can do._ The sign-in requirements also anticipate sharing accounts with Waroku Hospital Karte within the same organisation. That is a direction in the documents, not a feature I can confirm as shipped. ## The care cycle The system organises home-visit nursing as a cycle rather than a single chart. An assessment of the patient leads to a nursing order, which says what needs to be done, and the order to a nursing plan, which says how and when. The plan becomes monthly and daily visit schedules; each visit produces a record, a diary entry and a report, and the report feeds the next assessment. ```mermaid flowchart TB accTitle: The home-visit nursing care cycle accDescr: The cycle starts with the patient and an assessment. The assessment leads to a nursing order, the order to a care and visit plan, and the plan to the monthly and daily schedule. The schedule leads to the home visit, the visit to the visit record, the record to the diary, the diary to the report and the report to a progress review. The progress review feeds the next assessment, which closes the loop. PATIENT["Patient"] ASSESS["Assessment"] ORDER["Nursing order"] PLAN["Care / visit plan"] SCHEDULE["Monthly / daily schedule"] VISIT["Home visit"] RECORD["Visit record"] DIARY["Diary"] REPORT["Report"] REVIEW["Progress review"] PATIENT --> ASSESS ASSESS --> ORDER ORDER --> PLAN PLAN --> SCHEDULE SCHEDULE --> VISIT VISIT --> RECORD RECORD --> DIARY DIARY --> REPORT REPORT --> REVIEW REVIEW --> ASSESS ``` _What is learnt at one visit becomes the input of the next assessment and plan._ ## One patient at the centre The patient list is the main entry point: search, filters, groups, care levels and summary counts, then the patient's information. Patient information — the patient's chart — holds identity, date of birth and age, blood type, height, weight, BMI and BSA, address and contact details, and related doctors, hospitals and departments. From it, staff move into every other workflow of that patient. ```mermaid flowchart TB accTitle: Patient-centric data accDescr: The patient links to basic information, address and contact, related doctors and hospitals, the living environment, assessments, case records, attachments and nursing orders. Each nursing order leads to nursing plans, plans lead to visit records, and visit records lead to nursing reports. PATIENT["Patient"] BASIC["Basic information"] CONTACT["Address / contact"] DOCTOR["Related doctors / hospitals"] ENV["Living environment"] ASSESS["Assessments"] CASE["Case records"] FILE["Attachments"] ORDER["Nursing orders"] PLAN["Nursing plans"] VISIT["Visit records"] REPORT["Nursing reports"] PATIENT --> BASIC PATIENT --> CONTACT PATIENT --> DOCTOR PATIENT --> ENV PATIENT --> ASSESS PATIENT --> CASE PATIENT --> FILE PATIENT --> ORDER ORDER --> PLAN PLAN --> VISIT VISIT --> REPORT ``` _Information, home, records, files and the whole chain from order to report hang off one patient._ ## The patient's home The living environment is specific to care at home, because the care that can be given depends on the place. The system records the floor plan; the room — private or not, floor, lift, bed or mattress, lighting, heating and air conditioning; the toilet — type, handrails and steps; the bathroom — handrails and steps; and facilities such as the washing machine, water heater, refrigerator and kitchen. Every area can carry notes and photos, so staff record the conditions as they are, not only in words. ```mermaid flowchart TB accTitle: The living environment of a patient accDescr: A patient's living environment is recorded in five areas: floor plan, room, toilet, bathroom and facilities. Each area can carry photos and other attachments. PATIENT["Patient"] ENV["Living environment"] FLOOR["Floor plan"] ROOM["Room"] TOILET["Toilet"] BATH["Bathroom"] FACILITY["Facilities"] FILE["Photos / attachments"] PATIENT --> ENV ENV --> FLOOR ENV --> ROOM ENV --> TOILET ENV --> BATH ENV --> FACILITY FLOOR --> FILE ROOM --> FILE TOILET --> FILE BATH --> FILE FACILITY --> FILE ``` _Five areas of the home, each with its own notes and photos._ ## Case records and handover A case record is a flexible model shared by many kinds of care information: a title and free text, the author, receivers who are staff members or groups, a linked order and order type, tags, flags for important, urgent, handover, private and history, and attachments. The handover flag turns a record into information passed between shifts, staff, groups and offices, and comments on a record were expected to behave close to a real-time chat. Tags have their own create, read, update and delete APIs. ```mermaid flowchart TD accTitle: Creating a case record accDescr: A staff member creates a case record with a title and free text, receivers who are staff members or groups, important and urgent flags, a handover flag, tags and attachments. All of them go into the patient's record history. USER["Staff"] RECORD["Create a case record"] TITLE["Title / free text"] RECEIVER["Receivers: staff / group"] FLAGS["Important / urgent"] HANDOVER["Handover"] TAG["Tags"] ATTACH["Attachments"] HISTORY["Patient record history"] USER --> RECORD RECORD --> TITLE RECORD --> RECEIVER RECORD --> FLAGS RECORD --> HANDOVER RECORD --> TAG RECORD --> ATTACH TITLE --> HISTORY RECEIVER --> HISTORY FLAGS --> HISTORY HANDOVER --> HISTORY TAG --> HISTORY ATTACH --> HISTORY ``` _One record model carries receivers, flags, tags and files — and marks what must be handed over._ ## Orders, plans and schedules - **Nursing orders** are the instructions for care at home, with list, create, edit and detail screens. The list comes in normal, special and psychiatric variants. - **Nursing plans** sit between the order and the actual schedule: list, detail and edit, with assessment-related data and a variant for the research partner. - **Visit schedules** come in two views, monthly and daily, and tie together the patient, staff, time, office and the state of the plan. ## Visit records, diaries and reports Home-visit nursing record I has a history list, create and edit, detail, business forms, conversion into a case record, printing and attachments. Record II has PC, mobile and research-partner variants, and part of it belongs to a later phase. After visits, staff write the nursing diary, with a list, detail and edit, a calendar and printing. Nursing reports come in normal, psychiatric, combined and attachment types, with detail, edit and print screens and, on some screens, an electronic stamp for approval; the combined type adds GAF data. ```mermaid flowchart LR accTitle: From a home visit to the patient's history accDescr: A home visit produces a visit record, the record goes into the nursing diary, the diary feeds the nursing report, the report is reviewed and assessed, and the result joins the patient's history. VISIT["Home visit"] RECORD["Visit record"] DIARY["Nursing diary"] REPORT["Nursing report"] REVIEW["Review / assessment"] HISTORY["Patient history"] VISIT --> RECORD RECORD --> DIARY DIARY --> REPORT REPORT --> REVIEW REVIEW --> HISTORY ``` _A visit is recorded, written up, reported and reviewed — and becomes part of the patient's history._ ## Assessments that track progress Assessment is split by method — bedsore (pressure ulcer), ADL, IADL and GAF — and by time, so the system follows change rather than a single score. Bedsore assessments keep their images through a file route of their own. The personal assessment shows one patient's domains block by block; the overview assessment brings many domains onto one screen, with many APIs, blocks and data formats. The month-end inventory summarises a month of home-visit nursing for each patient and links to patient information and assessment progress, and the research-partner variant adds a feedback report of its own. ```mermaid flowchart TB accTitle: Patient assessment accDescr: A patient's assessment covers four methods: bedsore, ADL, IADL and GAF. All four feed the personal assessment of that patient; the personal assessment feeds the overview assessment, and the overview builds the progress history. PATIENT["Patient"] ASSESS["Patient assessment"] BEDSORE["Bedsore"] ADL["ADL"] IADL["IADL"] GAF["GAF"] PERSONAL["Personal assessment"] OVERVIEW["Overview assessment"] PROGRESS["Progress history"] PATIENT --> ASSESS ASSESS --> BEDSORE ASSESS --> ADL ASSESS --> IADL ASSESS --> GAF BEDSORE --> PERSONAL ADL --> PERSONAL IADL --> PERSONAL GAF --> PERSONAL PERSONAL --> OVERVIEW OVERVIEW --> PROGRESS ``` _Four assessment methods feed one patient's assessment — and, over time, a history of progress._ ## Files everywhere Attachments cut across the whole system and go through one file service. A file is uploaded first; the API stores it in Amazon S3 and returns its UUID, name, size, URL, thumbnail URL and content type; the business record then refers to it by UUID. Upload routes are scoped by purpose: bedsores, prescriptions, living environments, nursing orders, case records and staff stamps. ```mermaid flowchart LR accTitle: Uploading a clinical attachment accDescr: The web client uploads the file to the file API as multipart form data. The API stores the file in Amazon S3 and returns its metadata to the client. The client then saves the clinical record, which refers to the file by the UUID in that metadata. UI["Web client"] API["File API"] STORAGE["Amazon S3"] META["File metadata"] DOMAIN["Clinical record"] UI -->|"multipart/form-data"| API API --> STORAGE STORAGE --> API API --> META META --> UI UI --> DOMAIN DOMAIN -->|"file UUID"| META ``` _Upload first, then link: the clinical record keeps only a reference to the file._ ## API, authentication and permissions The REST API speaks JSON with GET, POST, PUT, PATCH and DELETE, grouped into authentication, accounts, patients, staff, organisations, offices, assessments, case records, nursing records, orders, plans, schedules, reports, files, tags and master data. Select boxes and forms take their options — roles, care levels, assessment methods, body parts, prefectures, departments, order types — from master-data APIs instead of hard-coding them. Not every user may call every API: permission checks combine role, organisation, office and account type, and errors distinguish invalid parameters, authentication, permission, missing resources, unsupported methods, database errors and unexpected failures. ```mermaid sequenceDiagram accTitle: Authentication and permission on every request accDescr: The web client sends a sign-in request with an API key. The API asks the auth and permission layer to validate the credentials, receives the user, role and organisation, and returns an access token with that context. Every business request then carries the access token as a bearer token, and the API asks the auth layer to validate the token and the permission. If the request is allowed, the API returns a JSON response; if not, it returns 401 or 403. participant UI as Web client participant API as REST API participant AUTH as Auth / permission layer UI->>API: Sign-in request + API key API->>AUTH: Validate credentials AUTH-->>API: User / role / organisation API-->>UI: Access token + context UI->>API: Business request + bearer token API->>AUTH: Validate token and permission alt Allowed AUTH-->>API: Allowed API-->>UI: JSON response else Not allowed AUTH-->>API: Denied API-->>UI: 401 / 403 end ``` _An API key to sign in, a bearer token after that, and a permission check on every call._ ## Leading a team through changing designs and staged APIs - **APIs arrived after the UI.** The team built screens first on mock data, read the API specifications, integrated the real API later and fixed the places where the API differed from the design. - **Designs kept changing.** New designs, conflicting pages, APIs that disagreed with the design, blocks to rebuild, tabs and menus that moved, screens without a full design. My job was to keep those changes from turning into different implementations by different developers. - **Shared components** — header, global menu, patient header, tables, form blocks, popups, select boxes, notifications, assessment blocks — so that many domains used the same pieces. Assessment domains were split across several developers on top of them. - **Quality before QA.** A screen went through implementation, pull request and review, deployment to development and QA testing; bugs came back for fixing and retesting, and the daily meetings tracked where each page stood. - **Tablet as well as desktop.** Lists and tables needed horizontal scrolling, alignment that holds, and layouts for 4:3 and tablet screens. The 2022 phase was a responsive web application; the documents do not show a native app in it. The Phase 1 release covered sign-in and password, patients and their chart, living conditions, assessment, case records, nursing records, orders, plans, reports and departments, with their detail and edit screens. ```mermaid flowchart LR accTitle: How a screen went from design to release accDescr: Requirements and design become mock data and a mock API, then implementation. Implementation goes through the leader's code review, deployment to the development environment and QA testing. An issue found in QA becomes a bug or feedback item and goes back to implementation; a screen that passes QA goes to release. SPEC["Requirements / design"] MOCK["Mock data / mock API"] DEV["Implementation"] REVIEW["Leader / code review"] DEPLOY["Deploy to dev"] QA["QA test"] BUG["Bug / feedback"] RELEASE["Release"] SPEC --> MOCK MOCK --> DEV DEV --> REVIEW REVIEW --> DEPLOY DEPLOY --> QA QA -->|"Issue"| BUG BUG --> DEV QA -->|"Pass"| RELEASE ``` _Mocks let screens move before the API was ready; review and QA decided when they were done._ ## Architecture The browser or tablet runs the web frontend, built with Vue and Vuetify, which calls the REST API. The API checks the API key or access token, then the role and permission, before the business services run; files go through the file service to Amazon S3. The backend framework, the database engine and the rest of the infrastructure are not named here: the API was built on the Japanese side, and the documents are not specific enough to state them. ```mermaid flowchart TB accTitle: Architecture at component level accDescr: Users on a browser or tablet use the web frontend, built with Vue and Vuetify UI components. The frontend calls the REST API, which checks the API key or access token, then the role and permission, before the business services run. The business services use the application database and a file service, which stores files in Amazon S3. USER["Browser / tablet"] WEB["Web frontend (Vue)"] UI["Vuetify UI components"] REST["REST API"] AUTH["API key / access token"] PERMISSION["Role / permission"] BUSINESS["Business services"] FILE["File service"] S3["Amazon S3"] DATA["Application database"] USER --> WEB UI --> WEB WEB --> REST REST --> AUTH AUTH --> PERMISSION PERMISSION --> BUSINESS BUSINESS --> DATA BUSINESS --> FILE FILE --> S3 ``` _A component-level view of what the project documents show — not a copy of the production infrastructure._ ## What the project covers | Concern in a large management system | How it shows up in Waroku Home-Visit Nursing | | --- | --- | | One entity at the centre | Information, home, records, files, orders, plans, visits, reports and assessments all hang off the patient | | Multi-organisation context | Organisation, office, staff and role set at sign-in; office switching; menus served by the API | | Variants of one product | Standard, research-partner and management accounts, with screens and reports that differ by account type | | A workflow that loops | Assessment, order, plan, schedule, visit, record, diary, report, and back to assessment | | Information passed between people | Case records with receivers, flags, tags and handover | | Files as part of the record | One file service on S3 for bedsores, prescriptions, homes, orders, records and stamps | | Security on every call | API key, bearer tokens, permission checks by role, organisation, office and account type | | Delivery under moving specifications | Mock data, shared components, review and QA while designs and APIs changed | The diagrams are reconstructed at component level from the project's specifications. They omit internal URLs, identifiers, API routes, proprietary code and real patient data. The screenshots are demo wireframes with sample data; the operator's name, the research partner's label, portrait photos and street addresses in them are blurred. ## Details - **Role:** Project Leader · Technical Lead · Frontend - **Website:** [nurse.waroku.net/](https://nurse.waroku.net/) ## Technology - Vue - Vuetify - REST API - AWS S3 ## Services this project shows - [Custom Business Systems](https://tmtuan.dev/en/services/business-systems) ## Related articles - [Docs-as-code Knowledge Base + Context Graph for a 15-project portfolio](https://tmtuan.dev/en/articles/knowledge-base-docs-as-code-context-graph) ## Structured data (JSON-LD) ```json {"@context":"https://schema.org","@graph":[{"@type":"WebPage","@id":"https://tmtuan.dev/en/projects/waroku-home-visit-nursing#webpage","url":"https://tmtuan.dev/en/projects/waroku-home-visit-nursing","name":"Waroku Home-Visit Nursing — Cloud Care Platform","description":"A cloud platform for home-visit nursing in Japan: patients and their homes, case records and handover, nursing orders and plans, visit schedules, reports and assessments.","inLanguage":"en","isPartOf":{"@id":"https://tmtuan.dev/#website"},"about":{"@id":"https://tmtuan.dev/#person"}},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://tmtuan.dev/en"},{"@type":"ListItem","position":2,"name":"Projects","item":"https://tmtuan.dev/en/projects"},{"@type":"ListItem","position":3,"name":"Waroku Home-Visit Nursing","item":"https://tmtuan.dev/en/projects/waroku-home-visit-nursing"}]}]} ```