Architecture & Data

The spine

Everything in the six modules reduces to one shared set of objects. Get these right and the modules are small; get them wrong and every module carries a workaround.

Property ──┬── Unit ──┬── Reservation ── Guest
           │          │        │
           │          │        ├── Message ── Draft ── Approval
           │          │        └── StayRegister  (compliance, isolated)
           │          │
           │          ├── Task ──── ChecklistItem ── Photo
           │          ├── Ticket ── (maintenance history)
           │          └── RatePlan ── RateRecommendation ── Decision
           │
           ├── LegalRegime  (minpaku | ryokan | PT PMA | residential)
           ├── Licence ──── expiry, document
           └── Location ─── StockLevel ── Movement ── PurchaseOrder

Staff ── Role ── Assignment          AuditLog (append-only, everything)

Five decisions inside that diagram are worth arguing about now rather than later.

Property versus Unit. A Property is a building or licence-holding entity; a Unit is a sellable space. In Japan a machiya is one property, one unit. A 26-unit Bali development is one property, 26 units. A hotel is one property with room types. Model both from day one even where they are 1:1 — retrofitting it when the first hotel arrives means touching every module.

LegalRegime as a first-class attribute, not a tag. It determines whether the 180-day counter applies, which register format is required, what reporting cadence exists, and which tax applies. Japan minpaku, Japan 旅館業法, Indonesia PT PMA villa, Indonesia Pondok Wisata, plain residential — five values, and the system behaves differently for each.

The guest register is a separate store. This is the one hard boundary in the architecture. The operational Guest record holds what operations need: name, language, channel, stay dates, contact. The StayRegister holds what the law requires and nothing touches it casually: address, occupation, nationality, ID verification, passport reference where applicable. Different access control, different retention, different audit. It is never joined into a prompt, never sent to a model, never exported to a spreadsheet. It exists to satisfy 宿泊者名簿 obligations and inspection, and to be exportable for the bi-monthly 民泊制度運営システム filing. Keeping it separate limits blast radius and makes both the compliance and the AI stories dramatically simpler.

RateRecommendation and Decision are separate rows. The recommendation is what the system proposed, with its inputs frozen. The Decision is what the human did. Both immutable. This pair is the entire evidential basis for later deciding whether autonomy is warranted, and you cannot reconstruct it retrospectively.

Point-in-time everywhere it matters. Comp availability snapshots, on-books-at-days-to-arrival, stock counts, and knowledge-base versions all need history, not current state. Design these as append-only fact tables from the start; the alternative is discovering in month nine that you cannot answer "what did we know then."

The audit log

One append-only log for the whole system, written on every state change and every AI-influenced action: actor (human or system), action, object, before and after, and for AI actions the model, prompt version, retrieved sources and confidence.

Three reasons this is not optional. It is how you prove — to yourself, to owners, and if it comes to it to a regulator — what the system did and who approved it. It is the dataset that decides which intents graduate to autonomy. And it is the only practical way to debug a distributed operation across two countries and three languages six weeks after the fact.

Build order, and why

0  DATA SPINE + connector           weeks 1-3     unblocks everything
   ├─ PMS connector, reservation sync, reconciliation
   ├─ property/unit/reservation/guest model, legal regime
   └─ audit log

1  ADR RECOMMENDER                  weeks 2-6     read-only, zero risk
   ├─ comp data vendor integration + nightly snapshots
   ├─ scoring layers, floors/ceilings
   └─ approval screen  ← first visible win

   (start in parallel, no engineering: write the property
    knowledge base; export message history)

2  TASK ENGINE + LINE               weeks 5-12    biggest ops saving
   ├─ LINE OA, LIFF, staff onboarding
   ├─ reservation-driven task generation
   └─ manager board, photo verification

3  GUEST CO-PILOT                   weeks 9-20    highest value, most care
   ├─ unified inbox via PMS
   ├─ RAG over knowledge base + answer library
   ├─ confidence gate, approval screen, eval harness
   └─ loop into task engine  ← the AC scenario closes here

4  INVENTORY                        weeks 16-20   smallest build
   ├─ items, kits, implicit deduction from turnovers
   └─ par/ROP forecasting, order approval

5  SUPERVISOR + OWNER REPORT        weeks 20-24   nearly free by now
   ├─ deterministic digest, rule-based triage
   ├─ narrative + weekly pattern engine
   └─ monthly owner report per property

   COMPLIANCE runs alongside from week 1:
   180-day counter, register export, licence expiry tracking

Weeks are shape, not commitment — they assume one focused engineer plus your ops input, and they overlap deliberately. Three things about this order are load-bearing:

The spine is first and it is not negotiable. Every module reads reservations. Building any module before the spine means building a private, wrong copy of the spine inside it.

Pricing is second because it is read-only. It proves the approach to your team, produces a number management can see, and cannot damage the operation if it is wrong. Nothing else has that property.

The knowledge base starts in week one and is not an engineering task. It is the critical path for the guest co-pilot and it is a person writing facts down, one unit at a time. If it starts when the co-pilot build starts, the co-pilot ships two months late.

Platform

The operations layer is a web application plus a LINE front end, with scheduled jobs. Nothing here is exotic.

• Application — a single web app serving three audiences with role-based views: a manager console, an owner report view, and the LIFF mini-app rendered inside LINE.
• Database — Postgres. Relational, because the spine is relational, and every query in this handbook is a join.
• Scheduled work — nightly comp snapshots, nightly reconciliation, morning digest, weekly patterns, inventory recalculation. Boring, essential, and the first thing to instrument.
• AI — server-side only, through a gateway, with model choice as configuration rather than code. Prompts versioned in the repository and referenced by version in the audit log, so a change in output can always be traced to a change in input.
• Files — operational photos in one bucket, ID documents in a separate restricted one. Never the same bucket.

Deliberate non-goals: no mobile app (LINE is the mobile app), no separate staff portal, no microservices at this scale, no data warehouse until the reporting genuinely outgrows Postgres.

Security and privacy

The boundaries, in one place:

Redact before inference. Names, phone numbers, ID numbers and payment references are tokenised before any message reaches a model. Identity documents never reach a model, under any circumstance.

Contract for no-training. Enterprise data-processing terms with opt-out of training, and treat overseas inference as an APPI cross-border transfer requiring proper handling — adequacy, contractual safeguards, or consent by data class. Japan's PPC guidance on entering personal data into generative AI services is operative and specific; this is a live compliance area with corporate penalties up to ¥100M for mishandling personal data.

Least privilege by role. A cleaner sees their own tasks and unit access notes for today. They do not see guest names, other cleaners' work, rates, or anything in the register. This is not distrust; it is scope reduction, and it makes a lost phone a non-event.

Access notes are time-bounded. Door codes visible to staff only within the window they need them, and never in a persisted chat message. The same rule that protects guests protects you.

Retention with purpose. Registers retained as long as the relevant law requires and no longer. Operational photos on a defined schedule. Message history as long as it is useful for the answer library, with PII stripped once it is.

Separate stores for separate purposes. Operational data, compliance register, and identity documents. Three stores, three access policies. The single most valuable structural decision in this section.

What deliberately is not built

Worth stating, because scope creep in a project like this is the main failure mode:

• A PMS. Chapter 5.
• A CRM. Chapter 0 — you need a unified inbox, a guest profile and messaging automation, all of which are parts of the operations layer, not a licensed product.
• Direct OTA integrations. Chapter 5 — not available, and not worth wanting.
• An accounting system. Export to whatever the accountants use. Owner statements are a report, not a ledger.
• A mobile app. LINE.
• Autonomous anything, initially. The gates exist; they stay closed until the audit log says otherwise.
• A dark-mode toggle, a chat interface for management, a workflow builder. Every operations project accumulates these. They serve the builder, not the operator.