Projects/Localz

Localz — Pre-Implementation Synthesis Report

Compiled from all 39 content files in LocalzDocs/ (plus README, skimmed as meta). Purpose: a single reference to drive concrete implementation decisions. Every fact below is cited to its source file.

1. Product Vision & Target Users

Localz is a local-business marketplace for the Canada/GTA area (explicit anchor: Markham) connecting service providers, product sellers, and consumers in their community — framed as a potential "super app" for local needs spanning plumbers, chefs, daycare, tiffin, and tutoring (Localz-Project-Marketplace-Synthesis.md, Localz-Broad-Outline.md). The founding insight: many local providers already have customers via Instagram/WhatsApp/e-transfer, but lack the "connective tissue" — a real calendar, a booking with a lifecycle, a payment tied to that booking, and a review provably attached to a real transaction — which is the one thing Meta/Google structurally cannot offer (Localz-Strategy-and-Architecture-Note.md, §0).

Three user types: consumer (search → book → pay → review), service provider (list → price → schedule → accept → chat → get paid), product seller (list products → set price/delivery/location → accept orders) (Localz-Broad-Outline.md). Positioning is explicitly not to out-build Shopify/Amazon, but to reduce friction ("too techie" barrier) for small local sellers who fail at marketing, not selling (Strengths-of-Your-Idea.md, Localz-Project-Marketplace-Synthesis.md §1).

Strategic bet structure (Localz-Strategy-and-Architecture-Note.md §1–2): Bet 1 (chosen path) = own discovery — Localz is where people go to find local services, competing with Google/Facebook for the start of the journey. Bet 2 (fallback/on-ramp) = optional transaction layer — providers can route payment through Localz or keep it off-platform (Instagram/e-transfer) and use Localz only for discovery/scheduling. Payment is optional; discovery is mandatory. Bet 2 earns the right to Bet 1 (near-zero cold-start, provider brings own customers first).

2. Service-Type Taxonomy

The taxonomy files are short, list-style catalogs organized by engagement cadence/commitment pattern. Each provider-side file has a nearly-identical -Consumer counterpart that simply reframes every list item as "want X" instead of offering X — i.e., the Consumer files are the demand-side mirror of the same catalog, not a functionally distinct spec. No file describes different fields, booking logic, or UI for consumer vs. provider variants beyond this framing; the differentiation is implicit (provider = "I offer," consumer = "I want").

Type	Distinguishing trait	Example services (source)
One-time Short	Single, brief engagement — usually hours, same-day	Plumbing, lawyer, barber, gardening, snow removal, tailoring, delivery, makeup artist, massage, pest control, chef, photography, mechanics, electrical, auto detailing, window washing, pool services, event management, locksmith, online medical consulting, rentals (clothes/camera/drones/hall/bike/etc.), "get-together" service, ML-powered virtual assistant (form-filling, passport/government applications, ticket booking) (`One-time-Short-Service.md`)
One-time Long	Single engagement but spans multiple days / longer duration	Renovation, carpentry, 3D printing, wall printing, t-shirt design, software services (Fiverr-style), digital design, marketing services, house/carpet/dry cleaning, HVAC, companionship (`One-time-Long-Service.md`)
Weekly Subscription	Recurring, weekly cadence	Tutoring (academic, music, arts, swimming, homeschooling), fitness trainer, tiffin, errand runner, pet sitting, machine rental (`Weekly-Subscription-Service.md`)
Monthly Subscription	Recurring, monthly cadence	Daycare, babysitting, doula service, nursing, bookkeeping, basement/house rental (`Monthly-Subscription-Service.md`)
Seasonal	Time-boxed to a season/short calendar window	Seasonal produce selling, garage sale, warehouse sale (`Seasonal-Service.md`)
Product-Service	Not a booked service at all — a purchasable good	Grocery selling, general product selling, food services (cloud kitchen, restaurants, food trucks) (`Product-Service.md`)
Uncategorized	Ceiling-of-ambition catalog, hundreds of entries, not cadence-sorted	Spans Legal, Creative/Artisan, Design & Digital, Hair & Beauty, Personal/Lifestyle, Pet, Photography, Repairs & IT, Events & Entertainment, Catering, Music, Wellness & Therapy, Sports Coaching, Trades & Construction, Home Services, Education, Weddings (`Uncategorized-Services.md`) — explicitly signals scope ceiling, not MVP scope (`Localz-Project-Marketplace-Synthesis.md` §2)

Open question flagged directly in the notes (Example-Persona.md): how to handle reviews/ratings for ultra-short-lived services — e.g., a weekend vegetable seller operating only Saturday–Sunday. This is unresolved in the taxonomy files themselves; the Strategy note's tiered-review model (§3 below) is the closest available answer but wasn't explicitly connected back to this case.

Persona-level cadence mapping confirms the taxonomy is used consistently across examples (Example-Persona.md): plumber = one-time short/long; basement rental = one-time; chef = one-time (tiffin = monthly); snow blower rental = annual (a cadence not otherwise named in the six-way taxonomy — see Gaps, §9); math tutor = monthly; software consultant/renovator/house cleaner/HVAC = "variable" (also not a named taxonomy bucket).

3. Functional Requirements

Source: Functional-Requirements.md (canonical list) and Localz-Broad-Outline.md/Localz-Project-Marketplace-Synthesis.md (restated with extra provider persona detail).

A. Service Provider

Registration & Verification — register as individual, contractor, or business/enterprise; submit ID / business registration / licenses; provide banking details (void cheque / direct deposit) for payouts; optional social media links.
Portfolio & Offerings — add services/products with title, description, category, subcategory; upload photos, videos, location; define pricing (fixed, hourly, subscription, custom packages); propose new subcategories if none fit.
Availability & Scheduling — set availability calendar (one-time, recurring, subscription-based); bookings dashboard (calendar + list view); enable emergency/instant booking.
Order Management — accept/decline requests; cash payments require OTP: service starts only when consumer gives provider the OTP, ends only when provider gives consumer the OTP; update status for ongoing/multi-day jobs.
Payments — accept cash, debit/credit card, digital wallet; earnings dashboard with invoices, payouts, history.
Customer Engagement — always-on chat; rate/review customers; customizable cancellation policy (free / partial refund / non-refundable).
Notifications — new bookings, messages, cancellations, payment events.

Additional persona-level detail (Localz-Project-Marketplace-Synthesis.md §3): custom plans require customer approval before charge; provider can set booking charges and travel charges (customer can accept/decline); provider can list documents requiring signature (important for rentals).

B. Consumer

Registration & Access — email / Google / social login; manage profile & history.
Discovery & Search — search by prompt, keyword, or structured filters; scope nearby → city → state → country; filters on location, price, availability, category, subcategory, size/quantity.
Booking & Payments — book per provider availability; choose cash / debit/credit / digital wallet; for cash, generate OTP to start and confirm OTP to end/complete transaction.
Engagement & Feedback — chat with providers; rate/review after completion.

C. Shared / Mixed

Verification Workflow — OTP start/end for cash payments only; online payments auto-track service start/end.
Communication — secure chat supporting text, media, documents; optional anonymized calls/emails via proxy system.
Contracts & Agreements — digital storage and sharing of rental agreements or service contracts.
Search & Discovery — advanced filters (category, subcategory, location, availability, price, size/quantity); supports both services and physical product rentals.

4. Non-Functional Requirements

Source: Non-functional-Requirements.md (canonical, terse) — restated identically in Localz-Project-Marketplace-Synthesis.md §5.

Scalability — handle growth across multiple cities.
Performance — quick search, booking, and chat responses.
Security — encrypted payments, secure document storage.
Privacy — anonymized communication, data protection.
Availability — high uptime to support real-time bookings.
Usability — simple onboarding, minimal learning curve.

Note on concreteness: as written, these are qualitative, not quantified (no explicit SLOs/SLAs, latency targets, or uptime percentages appear in this file). The only place numeric NFR-adjacent targets appear at all is Development-Setup-Resources-and-Capacity.md (dev-environment capacity, not production SLAs) and the MVP go/no-go metrics in MVP-to-Phase-2-Roadmap.md (business KPIs, not system NFRs) — see §8. This is a genuine specification gap (§9).

5. Confirmed Tech Stack Decisions

Three stack documents exist and are broadly consistent but not identical in emphasis: Tech-Stack.md (cloud/AWS-oriented full build), Localz-Required-Stack.md (parallel AWS/GCP-portable framing, introduces Clerk/Keycloak choice explicitly), and Anti-Lockin-Pattern-for-Startup-Stack.md (principles-first, cheapest/most-portable framing). Read together, they triangulate to one recommended stack; specific tensions are flagged in §9.

Architecture (all three agree)

Start as a modular monolith: FastAPI codebase with well-separated modules — auth, listings, booking, payments, chat, search, reviews (Tech-Stack.md; also Marketplace-System-Design-Reference.md "ports & adapters" pattern).
Introduce message-bus boundaries early; split into services later only if/when teams grow (Tech-Stack.md).
Cloud target: AWS, but explicitly deferred until after local MVP is proven (Tech-Stack.md, Localz-Project-Marketplace-Synthesis.md §7).
MVP-specific instruction: PostgreSQL from day one (Docker locally) — "skip SQLite except for unit tests" (Tech-Stack.md, "Database (MVP-specific)" section). This directly contradicts MVP-Development.md's Week-1 instruction to start with SQLite and "swap to Postgres later" — see Contradictions, §9.

Datastores

Store	Purpose	Source
PostgreSQL (RDS/Aurora) + PostGIS	System of record: bookings, payments, users, KYC, payouts, reviews, disputes, audit trails. Chosen over Mongo-only because money/booking lifecycle needs SQL transactions/constraints.	`Tech-Stack.md`, `Localz-Required-Stack.md`, `Anti-Lockin-Pattern-for-Startup-Stack.md`
MongoDB (Atlas)	Flexible content: provider profiles, service catalogs (rich JSON), chat threads/messages, portfolios, dynamic forms.	`Tech-Stack.md`, `Localz-Required-Stack.md`
Redis (ElastiCache)	Caching (search results, listing cards, availability snapshots), sessions + CSRF + OTP throttles, rate limiting, Pub/Sub for WebSocket fanout. Described as mandatory even at MVP.	`Tech-Stack.md`, `Anti-Lockin-Pattern-for-Startup-Stack.md`
Typesense / Meilisearch or OpenSearch (Serverless)	Search & discovery — geo-aware, typo-tolerant; index services, providers, geo, price, availability, rating.	`Tech-Stack.md`, `Localz-Required-Stack.md`
S3 + CloudFront	Media, ID docs, rental agreements, invoices/receipts; use pre-signed URLs.	`Tech-Stack.md`, `Localz-Required-Stack.md`, `Anti-Lockin-Pattern-for-Startup-Stack.md`
SNS/SQS (MVP) → Kafka/Redpanda/Kinesis (scale)	Async jobs and event fan-out. SQS = background jobs; SNS = fan-out.	`Tech-Stack.md`
Amazon MSK / GCP managed Kafka / Confluent Cloud	Named specifically as the Kafka option in `Localz-Required-Stack.md` (portability framing) — use for `listing_created`, `order_paid`, `subscription_renewed`, `message_sent` events fanned out to notifications/search/analytics/moderation.	`Localz-Required-Stack.md`
ClickHouse (Cloud) or Redshift Serverless	Analytics warehouse (Phase 2), with Metabase/Superset for BI, RudderStack for event piping.	`Tech-Stack.md`
pgvector (in Postgres) or OpenSearch k-NN	Vector/semantic search (Phase 2/3): NL search, FAQ auto-reply, price suggestions.	`Tech-Stack.md`

Backend

Python FastAPI (sync+async mixed), Pydantic v2, SQLAlchemy 2 (Postgres), Motor/PyMongo (Mongo), Alembic migrations (Tech-Stack.md, Localz-Required-Stack.md, Anti-Lockin-Pattern-for-Startup-Stack.md — all three agree).
Workers: Celery (broker: SQS or Redis) or Dramatiq (Redis/SQS); Temporal for complex orchestration later. MVP starts with FastAPI BackgroundTasks, graduates to RQ/Celery when retries/visibility are needed (Tech-Stack.md).
Payments: Stripe (Checkout + Billing + Identity if KYC needed there) — unanimous across all three stack files.
AuthZ: OPA/oso (optional) or simple RBAC via Postgres tables (Tech-Stack.md); JWT access + rotating refresh tokens (Localz-Project-Marketplace-Synthesis.md §7).
Real-time: Starlette/native FastAPI WebSockets, or Socket.IO client for reconnection logic; Redis Pub/Sub for fanout.

Frontend

Next.js 15 (App Router) — file-based routing, SSR/SSG for SEO-friendly listings (Tech-Stack.md). Note: Localz-Required-Stack.md more loosely says "React (Vite or Next.js)" without pinning the version — treat Next.js 15 App Router as the specific decision since it's the only version-pinned statement.
TypeScript strict mode — types generated from OpenAPI (FastAPI → openapi-typescript).
TailwindCSS + shadcn/ui.
TanStack Query (server state) + Zustand/Jotai (lightweight client state).
React Hook Form + Zod (aligned with Pydantic schemas for type parity).
Auth token storage: httpOnly cookies preferred.
Uploads: pre-signed S3 URLs, React Dropzone for progress.

Mobile

React Native (Expo to start; bare RN later if needed); push via FCM/APNs (Tech-Stack.md, Localz-Required-Stack.md).

Auth (specific product named, with caveat)

Clerk named explicitly as the MVP auth choice in Localz-Required-Stack.md and Anti-Lockin-Pattern-for-Startup-Stack.md — "start with Clerk" behind an Auth Adapter interface (get_current_user(), verify_token(), sync_user_profile()), storing a local users table keyed by auth_provider_user_id, so migration off Clerk later doesn't require an app rewrite. Alternative named: Keycloak (self-hosted, lowest lock-in, more ops burden) or Auth0 (similar tradeoffs to Clerk). However, Development-Setup-Resources-and-Capacity.md documents an actual running dev environment using Keycloak (marketplace-keycloak, dev mode) — not Clerk. This is a live discrepancy between the documented "recommended" stack and the stack apparently already stood up in dev; see Contradictions §9.

Platform & Ops (deferred until AWS phase)

EKS (managed node groups, Cluster Autoscaler, HPA/VPA, ALB/NGINX ingress) + Terraform (AWS) + Helm/Kustomize (K8s).
CI/CD: GitHub Actions → ECR → Argo CD (or GH Actions direct to EKS for simplicity).
Secrets: AWS Secrets Manager + External Secrets + IRSA.
CDN/WAF: CloudFront + AWS WAF.
Feature flags: Unleash (self-host) or LaunchDarkly (SaaS).
Testing: pytest + Playwright (web) + Pact (if/when services split).

Anti-Lock-In Principles (`Anti-Lockin-Pattern-for-Startup-Stack.md`, §5 — the 5 rules)

Everything runs in containers (even if deployed to VMs first).
Terraform for infra + minimal cloud-specific modules.
Abstraction layer for: Auth, Storage, Payments, Notifications, Search (named explicitly — e.g., StorageService, NotificationService, AuthProviderAdapter, ModelProvider interfaces).
Use open standards: OpenAPI, OpenTelemetry, SQL migrations.
Keep data model yours: users, billing, listings, orders live in Postgres under your control — never let a vendor own this data.

Companion architectural doctrine (Marketplace-System-Design-Reference.md): contracts over code coupling (OpenAPI for HTTP, AsyncAPI for events), one owner per data domain, "ports and adapters" so domain logic never imports Redis/Kafka/Postgres SDKs directly, transactional outbox pattern for reliable event publishing, idempotency keys everywhere. The 9 domains to separate early (even inside one monolith): Identity & Access, Catalog, Orders & Checkout, Payments, Fulfillment, Messaging & Notifications, Media, Search & Discovery, Analytics/Audit.

Minimal MVP Slice (`Tech-Stack.md`, explicit list)

Postgres (RDS), Mongo (Atlas), Redis (ElastiCache), Typesense (managed) or OpenSearch Serverless, S3 + CloudFront, SNS/SQS + Celery workers, FastAPI backend, Next.js web, Socket.IO, Stripe.

This is stated as sufficient to "launch bookings, payments, chat, search, reviews with reliable ops and clean upgrade paths" — but note this already assumes AWS managed services, which conflicts with the more locally-scoped MVP-Development.md plan (SQLite/Docker/local-only) — see §9.

6. Security & Observability Approach

Security — Minimal → Production Path (`Minimal-to-Production-Security-Implementation.md`)

A phased, cost-conscious plan explicitly avoiding premature AWS adoption:

Phase 0 (this week): In-app messaging only. Stack: FastAPI + JWT, MongoDB (messages/threads), Redis (rate limits/locks), WebSocket (Starlette). Includes concrete Pydantic models (Thread, Message — with an e2ee: bool flag reserved for future encryption) and a full endpoint list (POST /threads, GET /threads, GET /threads/{id}/messages, POST /threads/{id}/messages, WS /ws/threads/{id}, admin block/close). Security must-haves: rate limit ~20 msg/min per user, virus-scan uploads (temp store → scan → promote), server-side content filters (links, executables), audit log for every message/meta change.
Phase 0.5: Email relay via Postmark or SendGrid (explicitly "not AWS yet") — per-thread/role aliases (e.g., [email protected]), inbound webhook with HMAC signature verification, TTL aliases (14 days after last activity), SPF/DKIM/DMARC on the domain.
Phase 1: Proxy calls via Twilio (explicitly chosen as "simpler than Chime to start") — CallSession model, TwiML voice-bridge webhook, consent-based recording, time-based routing (business hours → voicemail/IVR), max duration caps, number-pooling for cost control.
Phase 2: Harden & unify — moderation (block phone/email leakage in chat), user controls (mute/block/export transcript), compliance (consent logs, retention policies), observability (delivery metrics, alerting).
AWS swap-in table (capability-preserving, same interfaces): Postmark/SendGrid → SES; Twilio Proxy/Voice → Amazon Chime SDK + Voice Connector; Redis → ElastiCache; RQ/Celery → SQS + Lambda/Fargate; .env secrets → AWS Secrets Manager + IRSA; Mongo audit collection → CloudWatch Logs + S3 Lake.
This week (10 hrs) action list: scaffold endpoints + WS for Phase 0 messaging; add Redis rate limits + basic moderation + audit log; integrate Postmark outbound + inbound webhook; alias TTL job + admin UI for blocks; unit tests for alias resolution, rate limiting, webhook verification.

Secure Communication Design (`Secure-Communication-Design.md`) — the target-state design (paired with the phased plan above)

Proxy call setup — virtual numbers per session/provider, call tracking/recording with consent, time-based routing to voicemail/IVR off-hours.
Email anonymization — app-managed aliases (e.g., [email protected]), temporary/expiring aliases, spam/phishing filters.
In-app messaging — secure chat/inbox (notes aspire to end-to-end encryption), rich media with virus/malware scanning, provider quick-replies for FAQs, AI or human-in-the-loop moderation hooks.
Secure contact forms — predefined templates, auto-responses, rate limiting + CAPTCHA.
Time-limited contact links — expiring phone/email links (short duration or limited uses), callback requests, audit logging.
Communication gateways — unified layer for calls/SMS/email, AI-based routing/prioritization, compliance archiving.
Consent-based sharing — opt-in disclosure of real contact details only after trust/contract formation, reversible consent, audit trails.

Cross-cutting technical enhancements repeated across both security docs: CAPTCHA, rate limiting, moderation, malware scanning, encryption, consent, reversibility, audit/compliance trails for disputes and regulatory needs.

Observability Stack (`Observability-Stack.md`)

Mental model: only 4 observability questions exist — (1) Is it alive? → Metrics, (2) Why did it break? → Logs, (3) Where did it break? → Traces, (4) How much money? → Business analytics. One tool should answer exactly one question; using two tools for the same question = overkill.

Question	Tool (recommended for Localz)	Explicit verdict
Metrics	Prometheus (+ Grafana)	✅ mandatory; ❌ Datadog metrics = optional luxury
Logs	Elasticsearch/OpenSearch	✅ yes, but short retention only (hot: 7–14 days, warm: 30–90 days, then delete/archive); ❌ multi-year ES retention = never
Traces	OpenTelemetry + Tempo/Jaeger	✅ later/optional; ❌ Dynatrace = overkill
Errors	Sentry	✅ high ROI; ❌ don't replace with logs alone
Business KPIs	Postgres + batch aggregates now, warehouse later	❌ Snowflake/Redshift now = too early

Explicitly-skip list: Datadog (too expensive), Dynatrace (enterprise APM), Snowflake (premature), Redshift (premature) — until specific triggers hit (warehouse when MRR > $20–30k; APM when latency debugging hurts; Datadog when SREs are hired; Dynatrace only if a regulated enterprise customer demands it).

Minimal Localz implementation plan: Week 1 (must-have) = Prometheus + Grafana, Fluent Bit → OpenSearch (7–14 days retention), Sentry SDK. Week 2–3 (high ROI) = OpenTelemetry SDK + Collector + Tempo/Jaeger. Later = business KPIs to warehouse.

Architecture pattern: apps emit to metrics endpoint + stdout/stderr JSON logs + OTel SDK + Sentry SDK; an OTel Collector acts as the single internal endpoint / "reverse proxy for observability" that fans out to the right backend so apps never need to know about 10 vendors directly. Logs pipeline: Pods → Fluent Bit/Vector → OpenSearch (hot 7–30d) → S3 (archive 90–365d) → Glacier (optional, years).

7. Monetization Plan Summary

Source: Monetization-Plan.md. Structured across 6 tiers, MVP-first:

Core Revenue Streams (MVP)

Transaction fee (take rate): flat 10–15% per booking/order on confirmed online payments. Cash payments get an optional 2–5% "confirmation fee". Example given: tiffin at $200/month → platform earns $20.
Freemium → Subscription for Providers: free tier limited to ~5 listed items; paid tier unlocks unlimited listings + analytics + marketing tools at $10–$50/month depending on category.
Booking/Convenience Fee (consumer-side): flat $1–$3 per booking, framed as "platform protection" (insurance, OTP verification, support) — scales better than raising percentage fees.

Marketing Add-Ons (Phase 2, provider-side)

Sponsored listings (pay-to-rank): $20–$200/month by location/category demand.
Homepage carousels: rotating banner packages, fixed weekly/monthly rate (example: $100/month).
Promotional badges ("Top Rated," "Fast Responder," "Discounted Today"): $10–$30/month.

Growth-Driven Incentives (Phase 2–3)

Referral rewards: consumers get $10 credit after 3 successful referrals; providers get a free month or ad credits per referral.
Loyalty points (app-wide): earned on bookings, redeemable across any service; funded by a small % of the platform's take rate.

Data-Driven Insights (Phase 3, premium)

Business dashboard: free tier = bookings/earnings only; paid tier ($20–$50/month) = peak-hour heatmaps, customer demographics, competitor pricing.

Seasonal/Event Campaigns

Thematic promotions ($30 entry into campaigns like "Diwali Specials"); geo-targeted marketing packs ($50–$300 to target a postal code/city).

Long-Term Optional Lines (100K+ users/providers)

Insurance/guarantee fees ($1–2/booking); API/integration fees (Shopify/Amazon merge-ins); B2B aggregated/anonymized demand data; financing/BNPL for costly services (renovations, daycare).

Note on completeness/priority: Monetization-Plan.md was explicitly and intentionally excluded from the Localz-Project-Marketplace-Synthesis.md compilation "per request," and the synthesis flags a standing open research question that gates monetization work: identifying the most painful problem a local business already pays for (or loses money over) that Localz can solve better. This means the monetization numbers above are a drafted menu, not yet validated against real willingness-to-pay — treat as directional, not committed pricing.

8. MVP Scope

Two MVP documents exist at different altitudes and are complementary, not duplicative: MVP-Development.md (tactical week-by-week local build plan) and MVP-to-Phase-2-Roadmap.md (strategic scope/exit-criteria plan). Localz-Strategy-and-Architecture-Note.md §13 adds one refinement on top of both.

IN — MVP (per `MVP-to-Phase-2-Roadmap.md`)

Geography: 1–2 cities (Markham/GTA).
Verticals (exactly 3): Home services (plumber/electrician/handyman), Tiffin/Chef, Tutoring.
User types: Consumer, Provider, Admin.
Provider onboarding: account creation → KYC/ID upload → bank/payout setup → profile (bio, service areas); service listing with category, fixed/estimate pricing, photos/videos, availability time slots, cancellation policy.
Consumer journey: search + filters (category, distance, price, availability, rating) → listing details → slot selection → checkout (online card escrow, or cash with OTP start/end codes) → booking lifecycle: Requested → Accepted → In-progress (start OTP) → Completed (end OTP) → Review.
Payments (lightweight but real): platform fee on online transactions; escrow-style capture on completion; refunds for disputes; scheduled payouts to providers.
In-app chat: text + images, tied to a booking — no direct phone/email exposure.
Ratings & reviews: post-completion only, 1–5 + comment, anti-spam guardrails.
Dashboards: Provider (today's jobs, monthly earnings, upcoming calendar, rating summary); Admin (GMV, take rate, active providers, bookings by category/city, dispute queue).
Baseline NFRs: SSO, audit logs, error tracking, basic rate limiting, nightly backups.

OUT — explicitly skipped for MVP (`MVP-to-Phase-2-Roadmap.md`)

Subscriptions/recurring billing, coupons, wallet/gift cards, advanced analytics, multi-city expansion, marketplace ads, complex inventory.

(Note: this "skip subscriptions" instruction sits in tension with the taxonomy's Weekly/Monthly Subscription service types and with tiffin being an MVP anchor vertical that the taxonomy files categorize as a subscription service — see Contradictions §9.)

Go/No-Go Exit Criteria (before expanding past MVP)

Activation: ≥40% of onboarded providers list ≥1 service with availability.
Liquidity: ≥30% of consumer searches result in a booking within 7 days.
Quality: dispute rate ≤3%; on-time completion ≥90%.
Revenue fit: online payments share ≥70% (vs. cash).
Added by the Strategy note (Localz-Strategy-and-Architecture-Note.md §13): a meaningful share of bookings reaching Tier 1 (proof the on-platform-payment incentive is working).

Risks flagged for MVP

Category sprawl (hold to 3 verticals); no-shows (mitigate with holds/deposits, reminders); trust gaps (push verification badges, fast dispute handling).

Tactical 8-Week Local Build Plan (`MVP-Development.md` — ~10 hrs/week, ~80 hrs total)

Deliberately local-only first (SQLite/Postgres + Docker + one FastAPI app + Next.js UI) — infra scaling (Redis, SQS, S3, EKS, Terraform) is explicitly deferred until this loop feels solid.

Week	Focus	Deliverable
1	Setup & skeleton — FastAPI + Pydantic + routers, SQLite + SQLAlchemy, JWT auth, Next.js + Tailwind starter, Dockerfiles	`docker-compose up` → `/api/health` + frontend loads
2	Providers & Services — provider CRUD, service CRUD, local media storage	Provider signs up + adds ≥1 service
3	Consumer Journey — SQL search filter, bookings table with lifecycle states, search UI, booking form	Search → request → provider sees booking
4	Payments (stub) — Stripe test mode checkout, transaction storage, cash-option flag	Pay via Stripe test or select cash
5	Booking Lifecycle + OTP — OTP start/end codes, status transitions, email/SMS stub (console log)	Requested → in-progress → completed via OTP
6	Reviews & Ratings — reviews table, average rating computed, post-completion form	Review after completion
7	Chat (local) — messages table, FastAPI WebSocket endpoint, booking-tied chat window	Consumer & provider chat on booking page
8	Polish & Demo — analytics endpoints, seed data, landing page + nav, full Docker Compose	Full walkthrough: sign up → search → book → pay → OTP → chat → review

Refinement from the Strategy Note (`Localz-Strategy-and-Architecture-Note.md` §13) — the one schema decision that must land early

Booking provenance fields — where discovery happened, whether payment was verified, how service was confirmed — must exist from the moment bookings exist, even though review tiers aren't computed until the reviews feature is built. "Cheap to add up front; expensive to retrofit." This is presented as the single highest-leverage MVP schema decision, feeding the Tier 1/2/3 trust-review model (§5 of that note).

Suggested First Launch Slice (both roadmap docs agree)

Markham/GTA; plumbing + tiffin/chef + tutoring; online escrow + cash OTP; one promo — "first booking, 0% platform fee."

9. Contradictions, Open Questions, and Gaps

A. Database choice for MVP — direct contradiction

MVP-Development.md Week 1: "Database: Start with SQLite (swap to Postgres later)."
Tech-Stack.md "Database (MVP-specific)" section: "PostgreSQL from day one (Docker locally). Skip SQLite except for unit tests."
Resolution needed: these cannot both be followed literally. Given Tech-Stack.md is the more architecture-focused document and Postgres is needed early for PostGIS/geo-search and money-transaction integrity anyway, recommend following Tech-Stack.md's instruction (Postgres from day one, SQLite only in unit tests) — but flag to the user that this is a real conflict, not a rounding difference.

B. Auth provider — documented plan vs. apparent running environment

Localz-Required-Stack.md and Anti-Lockin-Pattern-for-Startup-Stack.md both recommend Clerk (hosted, fast time-to-market) as the MVP auth choice, behind an adapter interface.
Development-Setup-Resources-and-Capacity.md documents a live dev container named marketplace-keycloak (Keycloak, dev mode) already provisioned, with capacity/bottleneck notes written as if it's the actual running component.
This is either: (a) a stale/exploratory dev setup that predates the Clerk decision, or (b) a live decision to self-host Keycloak that hasn't been back-written into the stack docs. Needs a decision — they are not the same product (Clerk = SaaS/managed; Keycloak = self-hosted, more ops burden per Anti-Lockin-Pattern-for-Startup-Stack.md's own tradeoff table).

C. Subscriptions — taxonomy says "core," MVP roadmap says "skip"

The service taxonomy dedicates two entire categories to subscriptions (Weekly-Subscription-Service and Monthly-Subscription-Service), and tiffin (categorized as a monthly/weekly subscription service in Product-Service.md/Weekly-Subscription-Service.md/Example-Persona.md) is one of the three MVP anchor verticals.
MVP-to-Phase-2-Roadmap.md explicitly lists "Subscriptions/recurring billing" under Skip (for now) in the MVP.
Practical read: this likely means "list tiffin as a one-time-bookable-per-instance offering in MVP, defer true recurring-billing/auto-renewal infrastructure to Phase 2" — but the docs don't say this explicitly. Worth confirming with the user before building, since it affects whether Stripe Billing (subscriptions product) is needed at MVP or whether one-off PaymentIntents suffice.

D. Taxonomy cadence gaps — "annual" and "variable" are used but never defined as top-level categories

Example-Persona.md describes the snow-blower-rental persona as "annual service" and describes software consultant / renovator / house cleaner / HVAC as "variable service" (may take more than one day) — neither "annual" nor "variable" appears as a named category among the six formal taxonomy files (One-time-Short, One-time-Long, Weekly-Subscription, Monthly-Subscription, Seasonal, Product-Service). These personas seem to map loosely to One-time-Long or Seasonal, but the fit isn't clean — this is a taxonomy gap, not just a wording slip.

E. Non-functional requirements are not quantified

Non-functional-Requirements.md gives qualitative goals only ("high uptime," "quick search," "encrypted payments") with no numeric SLOs (no p95 latency target, no uptime %, no RTO/RPO for backups). The closest numeric anchors live in unrelated documents: Development-Setup-Resources-and-Capacity.md (dev-container capacity, e.g., "500–1,000 concurrent users: acceptable"/"1,000+: will struggle") and the MVP go/no-go business metrics in MVP-to-Phase-2-Roadmap.md. None of these are framed as system SLAs. Before building production infra, this needs explicit numeric targets (even placeholder ones).

F. Two different "minimal MVP stack" prescriptions at different altitudes

Tech-Stack.md's "Minimal MVP slice" already assumes AWS-managed services (RDS, Atlas, ElastiCache, Typesense/OpenSearch Serverless, S3+CloudFront, SNS/SQS) — i.e., it's an MVP for the cloud phase.
MVP-Development.md and Localz-Required-Stack.md's "Phase 1 blueprint" describe a fully local/self-hosted MVP (Docker Compose, single VM/EC2, SQLite→Postgres, no managed AWS services yet).
These aren't contradictory in principle (one is "MVP inside the 8-week local build," the other is "MVP once you're ready for AWS") but the docs don't explicitly sequence them relative to each other — a reader could reasonably build either one first thinking it's the MVP stack. Recommend treating MVP-Development.md's local-first plan as the actual Week 1–8 build, and Tech-Stack.md's "Minimal MVP slice" as the next step after local validation, not a parallel option.

G. Cost-analysis documents assume a scale/architecture well beyond MVP

Service-Based-Cost-Analysis.md and How-My-Day-Looks-Like.md both model Phase 2 production Kubernetes (DEV+UAT+PROD×2 clusters, Kafka, managed Postgres+Mongo replicas) at "500 sellers / 10k buyers / 50k listings" scale (~$2,700/month, ~$32–36K/year), and Development-Setup-Resources-and-Capacity.md documents a fully-provisioned Docker Compose dev stack already including Keycloak and MinIO — both are far more infrastructure than the MVP roadmap or the 8-week local plan calls for. This is not a contradiction per se (both docs frame themselves as "later" planning), but it's worth flagging: the user has apparently already stood up (or at least documented) a heavier dev environment than the "prove it locally first, SQLite/Docker/single FastAPI app" doctrine recommends. Worth confirming whether the Keycloak/MinIO dev containers are legacy scaffolding to be replaced, or the actual intended local dev stack (in which case MVP-Development.md's "SQLite Week 1" plan is already superseded in practice).

H. Search engine choice is left as an explicit either/or, unresolved

Tech-Stack.md and Localz-Required-Stack.md both present Typesense/Meilisearch or OpenSearch as alternatives without picking one, though Localz-Strategy-and-Architecture-Note.md §5 adds useful sequencing guidance not present in the stack docs: don't add a dedicated search engine at all until query volume/faceting needs justify it — start with DB full-text + geo filtering. This effectively resolves the "which search engine" question for MVP (answer: none yet), but that resolution lives in a different document than the stack recommendation itself.

I. Data-platform ambition vs. "don't build it yet" — resolved, but only in one file

Extended-Feature-Data-Platform.md directly answers a question the user apparently raised (Airflow/Flink/Redshift/Athena for analytics) with a clear phased answer: Phase 1 = Postgres analytics tables + Kafka consumers + cron jobs only; no Airflow/Flink/warehouse. This is good, concrete guidance, but it isn't cross-referenced from Tech-Stack.md's own "Analytics warehouse" section (which lists ClickHouse/Redshift as "Phase 2" without the same explicit "don't build this yet" framing) — a reader skimming only Tech-Stack.md could reasonably start building warehouse infra prematurely.

J. Monetization pricing is explicitly unvalidated

Monetization-Plan.md's numbers (10–15% take rate, $10–50/month tiers, etc.) and the "~$10/month" provider price point repeated in Why-Service-Provider-Will-Use-Your-App.md are marked with "(hopefully!!)" in the source persona notes and are flagged by Localz-Project-Marketplace-Synthesis.md itself as resting on a gating research question that hasn't been answered: what's the most painful problem a local business already pays for that Localz solves better? Treat all monetization numbers as a draft menu, not committed pricing.

K. Minor — competitor list contains items unrelated to local services

Competitors.md lists LinkedIn, Indeed, and Udemy alongside Bark/Fiverr/Upwork/Etsy/Airbnb — LinkedIn/Indeed (job boards) and Udemy (course marketplace) don't obviously belong in a local-services-marketplace competitive set. Likely just a brainstorm dump; doesn't affect implementation but worth a cleanup pass if this file is used for external-facing competitive analysis later. Similarly, Localzz-Alternatives.md is a two-line stub (Base64, Replit) whose purpose is unclear from content alone — likely a dev-tooling/hosting-alternatives note rather than a business-competitor note, and probably needs a rename or expansion to be useful.

Quick-Reference: Source File Map

Topic	Primary file(s)
Vision/strategy	`Localz-Strategy-and-Architecture-Note.md`, `Localz-Project-Marketplace-Synthesis.md`, `Strengths-of-Your-Idea.md`
Taxonomy	`One-time-Short/Long-Service(-Consumer).md`, `Weekly/Monthly-Subscription-Service(-Consumer).md`, `Seasonal-Service(-Consumer).md`, `Product-Service.md`/`Products-Service-Consumer.md`, `Uncategorized-Services.md`, `Example-Persona.md`
Requirements	`Functional-Requirements.md`, `Non-functional-Requirements.md`
Stack	`Tech-Stack.md`, `Localz-Required-Stack.md`, `Anti-Lockin-Pattern-for-Startup-Stack.md`, `Marketplace-System-Design-Reference.md`
Security	`Minimal-to-Production-Security-Implementation.md`, `Secure-Communication-Design.md`
Observability	`Observability-Stack.md`
Monetization	`Monetization-Plan.md`
MVP scope	`MVP-Development.md`, `MVP-to-Phase-2-Roadmap.md`
Cost/capacity	`Service-Based-Cost-Analysis.md`, `Development-Setup-Resources-and-Capacity.md`, `Extended-Feature-Data-Platform.md`, `How-My-Day-Looks-Like.md`
Competitive landscape	`Competitors.md`, `Localzz-Alternatives.md`
Analytics/insights	`Data-Analysis-and-Insights.md`

Current Focus

MVP 8-week local build (Week 1: FastAPI + PostgreSQL skeleton)
Resolve auth decision: Clerk vs Keycloak (contradiction §B)
Resolve DB contradiction: PostgreSQL from day one (follow Tech-Stack.md, not MVP-Development.md Week 1)

Recent Activity (auto-updated)

AgentStack (unresolved)
FastAPI (unresolved)
PostgreSQL
Redis
Stripe (unresolved)