LocalzDocs/Tech-Stack

Tech Stack

Core approach

Architecture: start modular monolith (FastAPI codebase with well-separated modules: auth, listings, booking, payments, chat, search, reviews). Introduce message bus boundaries early. Split to services later if/when teams grow.
Cloud: AWS
Orchestration: EKS (Terraform) + IRSA + External Secrets
IaC: Terraform for AWS + Helm/Kustomize for K8s
CI/CD: GitHub Actions → ECR → Argo CD (or GH Actions direct to EKS if you want simpler)

PostgreSQL (RDS/Aurora) Bookings, payments, users, KYC, payouts, reviews/ratings, disputes, audit trails. Add PostGIS for geospatial (distance search, bounding boxes).
Why not only Mongo for everything? You'll want SQL constraints/transactions for money + bookings lifecycle.

MongoDB (Atlas) Provider profiles, service catalogs (rich JSON), chat threads/messages, provider portfolios, dynamic forms. (Append-heavy, variable schema, easy denormalization.)

Redis (ElastiCache)
- Hot caching (search results, listing cards, provider availability snapshots)
- Session + CSRF + OTP throttles
- Rate limiting buckets
- Pub/Sub for WebSocket fanout (chat/notifications)

Pick one:

Typesense/Meilisearch (simplicity, great UX)
or OpenSearch Serverless (AWS native, geo + aggregations) (index: services, providers, geo, price, availability, rating)

S3 + CloudFront Provider photos/videos, ID docs, rental agreements, invoices/receipts PDFs, export zips. Use S3 pre-signed URLs.

MVP (simple + reliable): SNS/SQS
- SQS: background jobs (email/SMS, invoice generation, refunds, indexing, push notifications)
- SNS: fan-out (booking-created → notify search indexer, analytics, provider push)
Scale/analytics later: Kafka/Redpanda (or Kinesis) for high-volume event streams, real-time dashboards, recommendations.

ClickHouse (Cloud) or Redshift Serverless Ingest from SNS/SQS or Kafka via connectors; drive funnels, retention, supply/demand heatmaps, LTV/CAC, search-to-booking conversion, etc. Add Metabase/Superset for self-serve BI; RudderStack (open-source Segment) to pipe events.

pgvector (in Postgres) for small/medium scale, or OpenSearch k-NN. Use for: NL search ("plumber under $200 tonight in Markham"), FAQ/auto-reply, price suggestions by area.

SQS (work queues): emails/SMS, receipt/invoice, refunds, subscription renewals, search reindex, image thumbnails, dispute workflows.
SNS (pub/sub): booking lifecycle events, provider state changes, payout events → multiple subscribers (analytics, notifications, ML features).
Redis Pub/Sub: low-latency fanout to WebSocket nodes for chat/notifications.
(Later) Kafka: event sourcing/analytics/reco pipelines when volumes justify.

Auth & KYC: Cognito/Auth0 (MVP: Cognito) + custom KYC (Stripe Identity or Persona) → Postgres (users, roles).
Providers & Services: Mongo (profiles/catalog) + S3 (media) + Search index (Typesense/OpenSearch).
Geo & availability search: PostGIS (distance prefilter) + Search engine for facets/sorting.
Bookings & Payments: Postgres (ACID) + Stripe (PaymentIntent, capture on completion) + webhooks → SQS.
Subscriptions (tiffin/tutoring): Stripe Billing (schedules, proration) → Postgres.
Chat (per booking): Mongo (messages) + WebSockets (Socket.IO or native FastAPI websockets) + Redis Pub/Sub.
Reviews/ratings: Postgres (to keep anti-fraud constraints) with nightly denorm view in Mongo/Search.
Coupons/Promos: Postgres (rules) + Redis cache.
Notifications: SES (email), SNS+Pinpoint or Twilio (SMS), FCM/APNs (mobile push).
Documents (agreements, invoices): S3 + pre-signed URLs; metadata in Postgres.
Search: Typesense/OpenSearch with nightly + near-real-time updates via SQS workers.
Analytics: Event SDK → SNS/Kafka → ClickHouse; dashboards in Metabase.
AI assists (later): embeddings in pgvector; model calls via Bedrock/OpenAI; RAG over FAQs/listings.

Language/Framework: Python FastAPI (sync+async mixed), Pydantic v2, SQLAlchemy 2 for Postgres, Motor/PyMongo for Mongo.
Workers: Celery (broker: SQS or Redis; result backend: Redis/Postgres) or Dramatiq (Redis/SQS). (If you want robust orchestrations later: Temporal.)
Search client: typesense-python / OpenSearch Python client.
Payments: Stripe (Checkout + Billing + Identity if you add KYC there).
AuthZ: OPA/oso (optional) or simple RBAC via Postgres tables.
File processing: image/video thumbnailer with ffmpeg in worker pods; store to S3.

Framework: Next.js 15 (App Router) — File-based routing, SSR/SSG for SEO-friendly service listings.
Language: TypeScript (strict mode) — Generate TS types directly from OpenAPI schema (FastAPI → openapi-typescript).
Styling/UI: TailwindCSS + shadcn/ui — Utility-first styling with composable pre-built components.
State/Data:
- TanStack Query (React Query) → handles server state (bookings, chats).
- Zustand or Jotai → optional for lightweight client state (theme, auth tokens).
Forms/Validation: React Hook Form + Zod (align with Pydantic schemas for type safety).
Auth Handling: Token storage in httpOnly cookies (preferred) or memory.
Realtime Messaging: Native WebSockets or Socket.IO client for reconnection logic.
File/Media Uploads: Pre-signed URLs from backend (S3/MinIO). Progress bars with React Dropzone.

EKS: managed node groups, Cluster Autoscaler, HPA/VPA, Ingress (ALB/NGINX).
Secrets: AWS Secrets Manager + External Secrets + IRSA.
CDN/WAF: CloudFront + AWS WAF.
Observability:
- Logs: Loki or CloudWatch;
- Metrics: Prometheus + Grafana;
- Traces: OpenTelemetry + Tempo/X-Ray;
- Error tracking: Sentry.
Feature flags: Unleash (self-host) or LaunchDarkly (saas).
Testing: pytest + Playwright (web) + Pact (if/when services split).
Backups/DR: automated RDS snapshots, Mongo Atlas backups, S3 versioning + Glacier.

PostgreSQL from day one (Docker locally). Skip SQLite except for unit tests.
Extensions: pg_trgm (fuzzy), unaccent (optional)
Indexes: GIN on FTS vectors; BTREE on common filters (city, category, price)

Redis (mandatory): per-IP/per-user rate limits, idempotency keys, short-lived locks, ephemeral session state for WS presence.

This combo lets you launch bookings, payments, chat, search, reviews with reliable ops and clean upgrade paths.