Hermes Wiki
LocalzDocs/Localz-Required-Stack

Localz Required Stack

General: self-hosted full stack application (FastAPI + React) either on EC2 or EKS, and then worker, nginx/traefik, redis are also self-hosted. Then managed services like Postgres, object storage, CDN, Kafka, Elasticsearch stack. Then SaaS like Clerk, Stripe, OpenAI, Anthropic, Sentry, SendGrid, Twilio, FCM/APNs.

A) Your app stack (portable across clouds)

Frontend

  • Web: React (Vite or Next.js)
  • Mobile: React Native (Expo to start; bare RN later if needed)

Backend

  • API: FastAPI + Pydantic
  • DB access: SQLAlchemy/SQLModel + Alembic migrations
  • Async jobs: Celery/Dramatiq (Redis as broker) or Temporal (later)
  • Real-time: WebSockets (FastAPI) / SSE (for live updates)

Contracts & observability (vendor-neutral)

  • HTTP Contract: OpenAPI (FastAPI generated)
  • Telemetry standard: OpenTelemetry (metrics + traces + logs)

B) Required platform capabilities (and AWS/GCP equivalents)

1) Compute (where your containers run)

Phase 1: VMs | Phase 2: Kubernetes

  • AWS: Phase 1: EC2 | Phase 2: EKS
  • GCP: Phase 1: Compute Engine | Phase 2: GKE

2) Container registry

  • AWS: ECR
  • GCP: Artifact Registry

3) Relational database (transactions, marketplace core)

Recommended: Postgres (managed)

  • AWS: RDS for PostgreSQL
  • GCP: Cloud SQL for PostgreSQL

Use it for: users (your local profile table), listings, orders, subscriptions, payments metadata, permissions, audit records index.

4) Document database (MongoDB)

Managed SaaS (portable): MongoDB Atlas (runs multi-cloud)

Use MongoDB for: flexible seller profiles, drafts, content blocks, chat sessions, dynamic configuration, denormalized read models.

5) Object storage (images, videos, documents)

  • AWS: S3
  • GCP: Cloud Storage

Anti-lock-in tip: keep a StorageService wrapper and use S3-compatible APIs where possible.

6) CDN (fast delivery for media + frontend assets)

  • AWS: CloudFront
  • GCP: Cloud CDN

7) Kafka (event streaming)

AWS (managed Kafka): Amazon MSK

GCP (managed Kafka): Google Cloud Managed Service for Apache Kafka

SaaS (strongest portability): Confluent Cloud

When to use Kafka in Localz:

  • "listing_created", "order_paid", "subscription_renewed", "message_sent"
  • fan-out to: notifications, search indexing, analytics, moderation pipelines

8) Cache / rate limiting / job broker

  • Open-source: Redis
  • AWS managed: ElastiCache for Redis
  • GCP managed: Memorystore for Redis

If you want least lock-in early: run Redis yourself (EC2/Compute Engine or in k8s) and treat it as ephemeral.

9) Secrets management

  • AWS: Secrets Manager
  • GCP: Secret Manager

This stores: DB passwords, Clerk secret key, Stripe secret, OpenAI/Anthropic keys.

C) Open-source services you may run (self-host)

Search (for marketplace listings)

  • MVP-friendly: Meilisearch / Typesense
  • Heavier: OpenSearch (more ops)
  • Elasticsearch stack managed

Observability stack (if self-hosted)

  • Grafana + Prometheus
  • Optional: Loki (logs), Tempo/Jaeger (traces)

D) SaaS / Third-party services (recommended)

1) Auth

  • Clerk (hosted auth)
  • Your backend should verify JWT and store auth_provider_user_id in Postgres.
  • Keep an AuthProviderAdapter so you can migrate later.

2) Payments

  • Stripe (subscriptions + marketplace payments)

3) Email / SMS / Push

  • Email: Postmark / SendGrid
  • SMS: Twilio
  • Push: FCM/APNs (mobile)

4) Error tracking

  • Sentry

5) AI models

  • OpenAI API
  • Anthropic Claude API

How to integrate cleanly (anti-lock-in):

  • Create a ModelProvider interface: generate_text(), classify(), embed(), moderate()
  • Implement OpenAIProvider and AnthropicProvider
  • Store prompts + outputs in your DB for audit/debug

E) Minimal "Phase 1" blueprint

On EC2 / Compute Engine (Docker Compose):

  • api (FastAPI)
  • worker (Celery/Dramatiq)
  • nginx/traefik (routing + TLS)
  • optional: redis, meilisearch

Managed services:

  • Postgres managed (RDS/Cloud SQL)
  • Object storage (S3/GCS)
  • CDN (CloudFront/Cloud CDN)
  • Kafka (MSK / GCP managed Kafka / Confluent Cloud)

SaaS:

  • Clerk, Stripe, OpenAI, Anthropic, Sentry

F) Quick guidance: AWS vs GCP

  • If you want strong managed marketplace primitives and broad ecosystem: AWS (MSK/EKS/RDS/S3/CloudFront).
  • If you want excellent Kubernetes experience and clean platform ergonomics: GKE is very strong, and GCP now also has a first-party managed Kafka service.
Hermes Wiki