NepWalk — Decision Log (MVP v2)
Authoritative for all NepWalk product, tech and business-direction decisions from 15 Sep 2026.
It overrides older docs (AGENTS.md sections, archived v0/v1 SRS/PRD/roadmap) wherever they conflict.
Rules for humans and AI agents:
- Read this file before planning or building anything.
- If a task conflicts with a decision here, stop and flag it. Don't silently follow the older doc.
- New decision → add a row here first (date, decision, why), then build on it.
- Items in "Open — look at further" are not decided. Don't implement a guess.
Related: scope.md (authoritative MVP scope) + tasks.md (build days), created 17 Sep 2026. Founder's full plan: personal-life/resources/company/NepWalk Bootstrap Plan (Sep 2026).md (founder-only).
Decisions
Business direction
| ID | Date | Decision | Why |
|---|---|---|---|
| B1 | 2026-09-15 | First revenue = vendor commission, collected post-stay. No listing fees. Agencies are not charged. | Matches how Prakash already earns; vendors pay for clients, not software. |
| B2 | 2026-09-15 | Later (2027): NepWalk collects traveller payment first and pays vendors after. Store paymentFlow on bookings from MVP. |
Makes the switch a feature, not a rewrite. |
| B3 | 2026-09-15 | A partner travel agency is merchant of record until NepWalk can legally sell packages. | Licensing. |
| B4 | 2026-09-15 | Agencies become customers in 2027. MVP data model is agency-ready; no agency UI now. | Focus; agencies adopt slowly in peak season. |
| B5 | 2026-09-15 | Beachhead (recommended, confirm 30 Oct): organised & faith-based groups from US/Europe. | Existing 10-year relationship, trust-sensitive, repeat yearly. |
| B6 | 2026-09-15 | Commission should be disclosed openly to travellers (wording open). | NepWalk's promise is "no hidden middlemen". |
| B7 | 2026-09-15 | One web app with roles. No separate vendor platform; vendors get a confirmation link (Oct) before any login portal. | Avoid building for a side with no demand yet. |
Product (MVP)
| ID | Date | Decision | Why |
|---|---|---|---|
| P1 | 2026-09-15 | MVP makes the real group-trip workflow easier (trip details are often open at first — only arrival date may be fixed): client context → work out dates and gaps → ask client questions → WhatsApp vendors → record confirmations → send "booked for you" summary. Vendor calls stay human. | Real, repeated pain; next church group arrives 28 Dec 2026. |
| P2 | 2026-09-15 | One itinerary is the baseline. Hotels, flights, transfers and van days are itinerary items (STAY, FLIGHT, TRANSFER, VEHICLE, PLACE, MEAL, FREE, CUSTOM). Rules, bookings, vendor sheets and the traveller view all come from it. Replaces the earlier idea of separate Stay/Move tables. |
Enter everything once; reuses existing Day/Itinerary models. |
| P3 | 2026-09-15 | Operator knowledge becomes tested rules (R1–R10: night coverage, city continuity, transfers, check-in timing, rooms & vehicle size, connection risk, winter fog, missing info, peak dates, headcount not final). Every real miss → new rule + test. | This is the product's advantage, not the forms. |
| P4 | 2026-09-15 | Questions panel is a core operator screen: rule questions + AI suggestions (labelled), with why, category, blocks-booking flag and status; tick → compose one WhatsApp message to the client. | Operator talks to the client; the tool tells him what to ask. |
| P5 | 2026-09-15 | Vendors and places are NepWalk-wide (not owned by an agency). Vendor status: unverified / verified / blocked. | All vendors connect through NepWalk; agencies' own vendors later join as unverified invites. |
| P6 | 2026-09-15 | WhatsApp via wa.me pre-filled links and monospace text blocks. No WhatsApp API in MVP. |
Zero cost, zero approval process. |
| P7 | 2026-09-15 | Acceptance test = an example church-group request (typical shape; the real 2026 trip is not planned yet — only its 28 Dec arrival is fixed): 28 Dec–10 Jan, KTM 5n → PKR 7n, flights 2 Jan and 9 Jan, 1 double + 5 single, van in KTM. Must flag the missing 9 Jan night, 6 rooms / 78 room-nights, 7 services. | Real case beats invented personas. |
| P8 | 2026-09-15 | Cut from MVP: reorder/duplicate/templates UI, agency screens, change approval, version history, push, vendor login, payments, WhatsApp API, AI itinerary generation, reviews, marketplace search, PWA offline, i18n, live alerts. | 2-week solo build. |
| P9 | 2026-09-15 | Headcount can change until enrolment closes. Trip stores pax enrolled / expected max / lock date. Services get an on hold status (range + release-by date) before requested. Rule R10: holds only until locked; lock date before earliest vendor release-by; re-run rooms and vehicle class on every pax change. |
People are still enrolling when trips are planned; peak-season rooms must be held early. |
| P10 | 2026-09-17 | Build day 1 was missed: days 1–2 share Thu 17, later days shift by one, F10 AI assist defaults to October (earlier only if ahead). Launch stays Wed 30 Sep. Scope lives in scope.md; build days in tasks.md. |
Protect launch date without cutting never-cut items. |
| P11 | 2026-09-17 | Frontend base = feat/mvp-base: origin/dev (trip pages, hooks, drag & drop, templates, settings, e2e) merged with design-system (Storybook, design docs, AGENTS.md). Merge, not rebuild. On conflicts dev's button/badge/avatar/input win (hardcoded hex; unify tokens in Oct, O7). Storybook stories excluded from type-check until updated. |
The trip pages already existed on dev; the merge built cleanly in ~40 min. |
| P12 | 2026-09-17 | Local dev DB is created from template0 (CREATE DATABASE nepwalk_db TEMPLATE template0) because the machine's Postgres templates have a collation-version mismatch. Seed logins: admin@nepwalk.com / password123. |
Unblocks local testing without changing system databases. |
| P13 | 2026-09-17 | Read rule: a trip and its days/itineraries are readable by its creator and members (active or invited); anyone else only when the trip is public; otherwise 404. Non-members never receive member/creator emails. Templates are visible/usable by their owner or when the trip is public. Reorder must list every itinerary of the day exactly once. Implemented in nepwalk-be/src/modules/trips/trip-access.ts. |
Closed the audit's data leaks without adding roles. |
| P14 | 2026-09-17 | One branch name across repos: feat/mvp-base in nepwalk-fe, nepwalk-be and nepwalk-docs (pushed and merged 17 Sep; later work continues on the same branch after syncing with main). Backend e2e tests run against nepwalk_test only. |
Easy to pair FE/BE work; tests never touch dev data. |
Design
| ID | Date | Decision | Why |
|---|---|---|---|
| D1 | 2026-09-15 | No Stitch/Figma redesign before real users. Build straight in code with existing components. Real design system in Jan 2027. | The problem is input and missing info, not looks. |
| D2 | 2026-09-15 | Traveller day view copies Visitacity's patterns: day buttons on top; photo card with time label, title, duration, one line; connector between cards ("🚐 25 min by van"). | Know today's plan in 3 seconds. |
| D3 | 2026-09-15 | Add for groups: "🌙 Tonight: Hotel X" at day end; call/WhatsApp buttons for driver/guide; "⏳ Pending" badge; light fun (countdown, Day X of Y, Nepali word of the day). | What Visitacity lacks and NepWalk needs. |
| D4 | 2026-09-15 | Operator builder: nights strip (whole trip on one line, empty night in red) → one-tap moves between cities → place picker per day. Delete the 7-field Add Activity form ("custom item" as fallback). Remove office wording ("ACTIVE PLAN", "Trip ID", "Publish") and duplicate time display. | Build a 13-day trip in 10 minutes. |
| D5 | 2026-09-15 | Keep the trips dashboard (photo cards) and the green brand. | Already works. |
| D6 | 2026-09-15 | Polish effort goes to the traveller day view; operator screens only need to work well. | The client sees it; it doubles as marketing. |
Tech & architecture
| ID | Date | Decision | Why |
|---|---|---|---|
| T1 | 2026-09-15 | Keep nepwalk-be (NestJS 11 + Fastify + Prisma 7 + Postgres) and nepwalk-fe (Next 15). No rewrite, no new repos. nepwalk_be_django is abandoned. |
~35% of MVP already exists. |
| T2 | 2026-09-15 | AI reads · code calculates · operator approves. Date math, gaps, rooms and money are never done by AI. | Bookings need the same answer every time. |
| T3 | 2026-09-15 | AI via OpenRouter free models (no Claude API). OpenAI-compatible client, key server-side only; AI_ENABLED, AI_MODEL_PRIMARY, AI_MODEL_FALLBACKS in env; schema-validate output, retry once, else fall back to the form. |
Cost; free models fail or disappear, so the app must work with AI off. |
| T4 | 2026-09-15 | Redact personal data before any AI call (names, phones, emails, passport numbers → placeholders). | Some free-model providers may log or train on prompts. |
| T5 | 2026-09-15 | Log every AI run (AiRun): input, model, output, operator corrections. |
Accuracy score + test cases; how NepWalk's AI improves. |
| T6 | 2026-09-15 | Organization + orgId on Trip, Service, Question, ShareToken, AiRun from Day 1; seed one org "NepWalk Ops"; scope every query. Vendor and Place have no orgId. |
Agencies in 2027 without rewriting queries; also enforces access control. |
| T7 | 2026-09-15 | New backend modules: organizations, planning (pure functions, no DB), questions, vendors, places, services, messages, share, ai. |
Clear boundaries; rules testable in isolation. |
| T8 | 2026-09-15 | Security before real data: guard all read endpoints, enforce isPublic, template ownership, revocable share tokens; traveller view and summaries never include prices, commissions or emails. |
Current endpoints leak private trips and member emails. |
| T9 | 2026-09-15 | Maps: Leaflet + OpenStreetMap. Weather: Open-Meteo. Place photos: own photos or Wikimedia Commons with stored credit. | Free, no billing accounts. |
| T10 | 2026-09-15 | TDD for auth, planning rules and money calculations. | Where mistakes cost the most. |
| T11 | 2026-09-17 | Secrets and CORS fail closed: the backend refuses to start without JWT_SECRET / JWT_REFRESH_SECRET (and with placeholder values in production); every JWT has a random jti; CORS allows only CORS_ORIGINS or FRONTEND_URL (required in production). |
Removes silent insecure defaults; production must set these env vars before deploy. |
Process & AI setup
| ID | Date | Decision | Why |
|---|---|---|---|
| A1 | 2026-09-15 | Department AI framework (agent_framework/nepwalk) and Forgeon (forgeblueflow) frozen until spring 2027. Revive the framework only when ≥3 people work in parallel. |
Process overhead for a solo build. |
| A2 | 2026-09-15 | Solo MVP AI setup = one CLAUDE.md per code repo + this folder (decisions.md, scope.md, tasks.md). |
Minimal, current, shareable with the team in Oct. |
| A3 | 2026-09-15 | Old planning docs archived: nepwalk-docs/archive/mvp-planning-2026/ (v0 SRS, v1 TEST ONLY docs). |
They conflicted with current direction. |
| A4 | 2026-09-15 | Team stays on other work until MVP (Tech Everest website, vendor research sheet); onboards in Oct via this folder. | Solo build; team learns the direction first. |
Open — look at further (NOT decided)
| # | Item | Decide by |
|---|---|---|
| O1 | Commission % per vendor type | Wed 30 Sep 2026 |
| O2 | Commission disclosure wording for traveller-facing pages | Before first public page (Nov 2026) |
| O3 | Confirm beachhead (B5) | Fri 30 Oct 2026 |
| O4 | Partner agency agreement terms | Fri 30 Oct 2026 |
| O5 | Which OpenRouter free models; their data policies and daily limits | Oct 2026 (with F10) |
| O6 | Place photo sources and credits | Wed 23 Sep 2026 |
| O7 | Brand colour token unification (#1B5E7B vs "Brand Green") |
Oct 2026 |
| O8 | Vendor confirmation link design | Oct 2026 |
| O9 | Agencies 2027: own vendors as unverified invites; NepWalk/agency commission split | Jan 2027 |
| O10 | Merchant-of-record switch (NepWalk collects and pays vendors) | Q1 2027 |
| O11 | Real design system / designer | Jan 2027 |
Review schedule
- Weekly: Friday review — skim open items, add new decisions.
- Formal revisits: Wed 30 Sep 2026 (post-MVP) · Fri 30 Oct 2026 · Thu 31 Dec 2026 · Mon 15 Feb 2027.