P

Platypus Platform

System Architecture v2.0

Domain
On-Demand Dog Walking
Market
Mumbai, India
Last Updated
March 2026
Real-Time Geospatial Marketplace
Platypus Platform
On-demand dog walking marketplace with live GPS tracking, intelligent guardian assignment, and multi-pet support for urban India (Mumbai)
Flutter NestJS PostgreSQL + PostGIS Redis Socket.io Firebase Razorpay
Real-time WebSocket Infrastructure 45 Database Models 30 API Modules 90 Screens across 4 Client Apps
Sub-200ms real-time GPS updates with geospatial matching across 43 Mumbai neighborhoods
1Problem
Dog walking in Indian cities lacks trust, visibility, and safety. Pet parents need real-time tracking, verified walkers, and platform-mediated communication. Uber-style reliability for dog walks.
2Solution
Built a full-stack marketplace with Flutter mobile apps (Parent + Guardian), NestJS API with 30 modules, real-time GPS tracking via WebSocket/Socket.io, PostGIS geospatial hub matching, intelligent auto-assignment, dynamic surge pricing, and gamification to drive engagement.
3Outcome
Production-ready platform with 4 client apps, Apple Watch + Wear OS companions, 45 database models, real-time walk monitoring dashboard, and comprehensive admin panel with 29 pages.
Key Engineering Decisions
PostGIS for geospatial hub radius matching instead of application-level distance calculation
Database-level spatial indexing
Socket.io WebSocket gateway for sub-200ms real-time GPS streaming
Live location infrastructure
Prisma $transaction for wallet race condition mitigation on concurrent bookings
Financial data integrity
IST timezone handling with todayIST() to prevent @db.Date off-by-one scheduling bugs
India-specific date safety
Firebase Phone Auth + JWT dual strategy for 7-day access / 90-day refresh
Auth resilience
Platform-mediated messaging to prevent disintermediation (no direct phone exposure)
Business model protection
Provider pattern in Flutter for lightweight state management across 90 screens
Scalable mobile architecture
Redis for OTP storage, weather cache, token blacklisting, and rate limiting
Multi-purpose in-memory layer
4
Client
Applications
30
API Modules
Across 5 Categories
45
Database Models
17 Enums
90
Total Screens
38 + 23 + 29
43
Mumbai
Neighborhoods
7
External Service
Integrations
My Role
System architecture & technical strategy
Database schema design (45 models with PostGIS)
API architecture (30 NestJS modules)
Mobile app architecture (Flutter, Provider pattern)
Real-time infrastructure (WebSocket, Redis)
DevOps & deployment pipeline (Docker, CI/CD, staging)
4
Client Apps
30
API Modules
45
DB Models
90
Total Screens
7
Integrations
Live
GPS Tracking
01
Client Applications
Parent App
Flutter 3.10.3 / Dart
+
38 Screens Provider go_router
Key Flows
  • Book Walk, pet select, slot picker, guardian browse, payment
  • Live Tracking, real-time GPS breadcrumb, status bar, walk events
  • Self Walk, parent-initiated GPS walk with auto-pause
  • Pet Health, vaccinations, medications, reminders, vet contact
  • Chat, platform-mediated guardian messaging
  • Gamification, badges, streaks, weekly digest, achievements
Services
API Service
Socket Service
Weather Service
Notification Service
Watch Service
Widget Service
Guardian App
Flutter 3.10.3 / Dart
+
23 Screens Provider Training
Key Flows
  • Active Walk. OTP verify, GPS streaming, poop/mood tracking, photos
  • Assignments, accept/decline bookings, schedule management
  • Training, 6 modules, 18 lessons, progress tracking, nudges
  • KYC. Aadhaar, PAN, selfie, police verification upload
  • Earnings, payout history, tips, monthly breakdown
  • Fitness, personal km/pace/calories from walk GPS data
Unique Services
Location Service
Speech Service
TTS Service
Training Provider
Admin Dashboard
Next.js 14 / React 18
+
29 Pages Shadcn UI Recharts
Page Groups
Dashboard & Analytics
Walk Monitoring
Guardian Management
Parent & Pet Registry
Bookings & Payments
Incidents & SOS
KYC Verification
Gamification & Badges
Stack
  • React Query for data fetching & caching
  • Radix UI + CVA for component primitives
  • Leaflet for GPS walk playback on maps
  • Socket.io-client for real-time updates
Wearable Apps
watchOS + Wear OS
+
SwiftUI Compose MethodChannel
Apple Watch
  • Walk status, weather, quick start, SOS (Parent)
  • Active walk, assignments, SOS (Guardian)
  • WatchSessionManager.swift + Flutter bridge
Wear OS
  • Jetpack Compose UI modules for both apps
  • WearDataService.kt + Data Layer API
REST / JWT
WebSocket / Socket.io
02
API & Services
NestJS 10
Platypus API
Port 3000 · /api/v1 · 30 Modules · TypeScript
+
Core
Auth
Firebase Phone Auth, JWT, register, refresh
Core
Booking
Create, cancel, reschedule, refund flows
Core
Walk
State machine, GPS, OTP, completion
Core
Payment
Razorpay orders, webhooks, wallet, tips
Core
Guardian
Profile, KYC, availability, browse
Core
Parent
Profile, wallet, address management
Core
Pet
CRUD, health records, vaccinations
Core
Hub
Service areas, PostGIS radius queries
Core
Self Walk
Start, GPS, pause/resume, complete
Core
Subscription
Plans, quotas, auto-renewal, pause
Comm
Chat
Conversations, messages, typing, archive
Comm
Notification
Firebase FCM push, in-app, device tokens
Comm
SOS
Emergency alerts, GPS, admin broadcast
Comm
Support
Tickets, categories, resolution flow
Comm
Email
Transactional emails via Brevo
Intel
Weather
Open-Meteo, walk safety, paw burn risk
Intel
Breed Intel
Breed-specific walk guidance & care
Intel
Pricing
Surge, multi-pet discount, dynamic pricing
Intel
Assignment
Auto-assign guardians by hub/availability
Intel
Geocoding
Google Maps reverse geocode & autocomplete
Engage
Gamification
Badges, streaks, leaderboards, tiers
Engage
Referral
Codes, wallet rewards, tracking
Engage
Promo
Discount codes, validation, usage limits
Engage
Digest
Weekly/monthly activity summaries
Engage
Meet & Greet
Guardian-parent introductions
Admin
Admin
Dashboard, stats, KYC review, reports
Admin
Analytics
Revenue, retention, hub performance
Infra
Health
Service health check endpoint
Infra
Upload
File storage abstraction (S3/MinIO)
Infra
Cron
Scheduled jobs, reminders, cleanup
JWT Auth Guard
Role-Based Access
Rate Limiting 3/1s
Validation Pipe
Helmet
Exception Filter
Transform Interceptor
WebSocket Gateway
gps:update
walk:status
walk:gps
walk:completed
message:send
typing:start
admin:join-all
join:walk
Prisma ORM
ioredis / S3 SDK
03
Data Layer & External Services
PostgreSQL 15 + PostGIS
45 Models · 17 Enums · Prisma 5.22
+
Geospatial $transaction Composite Indexes
Core Tables
User (4 roles)
Parent + Pet
Guardian + Hub
GuardianDocument
Booking
Walk + GpsPoint
Transaction
Subscription
ChatConversation
Badge + Streak
PostGIS Features
  • Hub center point + radius matching
  • Walk GPS trail storage & playback
  • Guardian current location tracking
  • Address geocoding with geography type
Redis 7
Cache · State · Real-time
+
128MB Max allkeys-lru AOF
Use Cases
  • OTP storage with TTL expiry
  • Weather API response cache (30min)
  • Token blacklisting on logout
  • Rate limiting counters
  • Real-time walk state
MinIO / AWS S3
Object Storage
+
Pet Photos KYC Docs Walk Photos
Storage Buckets
  • Pet profile photos
  • Guardian KYC documents (Aadhaar, PAN, selfie)
  • Walk photos (start, poop, completion)
  • Incident evidence (photos, audio)
🔥
Firebase
Phone Auth
FCM Push Notifications
💳
Razorpay
INR Payments
Subscriptions · Refunds
🗺
Google Maps
Geocoding
Address Autocomplete
⛅
Open-Meteo
Weather Data
Walk Safety Scoring
🛡
Sentry
Error Tracking
Performance Monitoring
04
Architecture Patterns
Controller → Service → Prisma
Strict 3-layer separation. Controllers dispatch, services orchestrate, Prisma handles data access.
Provider Pattern
Flutter state management via ChangeNotifier. Auth, ActiveWalk, Chat, and Training providers.
$transaction Guards
Prisma interactive transactions for wallet debits, refunds, and concurrent booking race conditions.
IST Timezone Safety
todayIST() + midnight UTC for @db.Date queries. Prevents off-by-one scheduling bugs.
PostGIS Geospatial
Hub radius matching, guardian proximity, address location with geography(Point, 4326) type.
Dual Auth Strategy
Firebase Phone Auth for mobile + JWT bearer tokens. 7-day access, 90-day refresh lifetime.
Platform-Mediated Contact
No direct Parent-Guardian phone exposure. All communication via in-app chat to prevent disintermediation.
Safe Decimal Parsing
Prisma Decimal fields serialize as strings. All API values pass through safe parse helpers.
05
Infrastructure & Deployment
📦
Turborepo
Monorepo · pnpm 8.15
🐳
Docker Compose
postgres · redis · minio
⚙
GitHub Actions
CI/CD · Test · Deploy
🌐
Nginx Proxy
Let's Encrypt SSL
🚀
Staging
v2-*.theplatypus.in
Explore Other Systems
→
Q-Invoice
Multi-Tenant Financial Billing Platform
→
Satshrut
Distributed Content & Live Streaming Platform
→
Relokate HR
Immigration Workflow Management Platform
→
Q-Studio
Coworking Space SaaS Platform
→
Numerology CMS
AI-Enhanced Knowledge Platform
← Back to Portfolio