replit-architecture-variants

Replit Architecture Variants

Overview

Application architectures on Replit at three scales: single-file prototype, modular production app, and multi-service architecture. Each matches Replit's container model, built-in services, and deployment types.

Prerequisites

• Replit account
• Understanding of deployment types (Static, Autoscale, Reserved VM)
• Familiarity with Replit's storage options

Architecture Decision Matrix

Factor	Single-File	Modular App	Multi-Service
Users	Prototype, < 100/day	100-10K/day	10K+/day
Database	Replit KV (50 MiB)	PostgreSQL	PostgreSQL + cache
Storage	Local + KV	Object Storage	Object Storage + CDN
Persistence	Ephemeral OK	Durable required	Durable required
Deployment	Repl Run / Autoscale	Autoscale / Reserved VM	Multiple Reserved VMs
Cost	Free-$7/mo	$7-25/mo	$25+/mo
Always-on	No (free), Yes (deploy)	Yes (deployment)	Yes (deployment)

Instructions

Variant A: Single-File Script (Prototype)

Best for: Bots, scripts, learning, hackathon projects.

# main.py — everything in one file
from flask import Flask, request, jsonify
from replit import db
import os

app = Flask(__name__)

# KV Database for simple state
@app.route('/')
def home():
    count = db.get("visits") or 0
    db["visits"] = count + 1
    return f"Visit #{count + 1}"

@app.route('/api/notes', methods=['GET', 'POST'])
def notes():
    if request.method == 'POST':
        note = request.json
        notes = db.get("notes") or []
        notes.append(note)
        db["notes"] = notes
        return jsonify(note), 201
    return jsonify(db.get("notes") or [])

app.run(host='0.0.0.0', port=int(os.environ.get('PORT', 3000)))

# .replit
run = "python main.py"

[nix]
channel = "stable-24_05"

[deployment]
run = ["python", "main.py"]
deploymentTarget = "autoscale"

Limitations: 50 MiB data, files lost on restart, cold starts. Upgrade to Variant B when you need structured data or durability.

---

Variant B: Modular App with PostgreSQL (Production)

Best for: Web apps, APIs, SaaS MVPs with 100-10K daily users.

my-app/
├── .replit
├── replit.nix
├── package.json
├── src/
│   ├── index.ts          # Express entry point
│   ├── config.ts          # Environment + secrets validation
│   ├── routes/
│   │   ├── api.ts         # Business logic
│   │   ├── auth.ts        # Replit Auth integration
│   │   └── health.ts      # Health check
│   ├── services/
│   │   ├── db.ts          # PostgreSQL pool
│   │   ├── kv.ts          # KV for cache/sessions
│   │   └── storage.ts     # Object Storage for files
│   └── middleware/
│       ├── auth.ts        # Auth header extraction
│       └── rateLimit.ts   # Rate limiting
└── tests/

Architecture:
  Client → Replit Proxy (Auth) → Express Server
                                      │
                    ┌─────────────────┤
                    │                 │
              PostgreSQL         KV Database
              (structured)       (cache/sessions)
                    │
              Object Storage
              (file uploads)

Key decisions:

• PostgreSQL for all structured data (users, posts, orders)
• KV Database for cache and session data only
• Object Storage for user uploads and backups
• Single Deployment (Autoscale or Reserved VM)

---

Variant C: Multi-Service (Scale)

Best for: Production services with 10K+ daily users, background jobs, or real-time features.

Architecture:
  CDN (Cloudflare) → Replit Deployment 1: API Server
                            │
                      PostgreSQL (Replit)
                      Redis (Upstash — external)
                            │
                     Replit Deployment 2: Worker
                            │
                      Queue (Upstash Kafka — external)
                            │
                     Replit Deployment 3: Static Frontend

Implementation:

Repl 1: my-app-api
  - Express/Fastify API server
  - Reserved VM deployment (always-on)
  - Handles authentication, CRUD operations
  - Publishes events to queue

Repl 2: my-app-worker
  - Background job processor
  - Reserved VM deployment (always-on)
  - Consumes events from queue
  - Handles: email sending, image processing, reports

Repl 3: my-app-frontend
  - React/Next.js frontend
  - Static deployment (free, CDN-backed)
  - Calls API server for data

Communication:
  - API to Worker: Upstash Kafka/Redis queues
  - Frontend to API: REST/GraphQL over HTTPS
  - Shared state: PostgreSQL + Redis

When to use external services:

Service	Replit-native	External (Recommended at Scale)
Database	Replit PostgreSQL	Neon, Supabase, PlanetScale
Cache	Replit KV (50 MiB limit)	Upstash Redis
Queue	None built-in	Upstash Kafka, BullMQ
Storage	Object Storage	Cloudflare R2, AWS S3
Search	None built-in	Algolia, Meilisearch

---

Variant D: Static + API Split

Best for: Frontend-heavy apps with a lightweight API backend.

Architecture:
  Client → Replit Static Deployment (React/Vue/Svelte)
              │
              └──→ Replit Autoscale Deployment (API)
                        │
                   PostgreSQL

# Frontend Repl .replit
[deployment]
deploymentTarget = "static"
publicDir = "dist"
build = ["sh", "-c", "npm ci && npm run build"]

# API Repl .replit
[deployment]
deploymentTarget = "autoscale"
run = ["sh", "-c", "node dist/index.js"]
build = ["sh", "-c", "npm ci && npm run build"]

Benefit: Frontend is free (Static deployment), API only charges when receiving requests (Autoscale).

Growth Path

Single-File → Modular App → Multi-Service
   │                │              │
   │    Add PostgreSQL    Add Worker + Queue
   │    Add Auth          Add CDN
   │    Add Storage       Add Redis
   │                      Split frontend

Error Handling

Issue	Cause	Solution
KV database full	Over 50 MiB limit	Migrate to PostgreSQL
Container sleeping	Free plan / no deployment	Use Autoscale or Reserved VM
Cross-service latency	Multiple Repls communicating	Use external queue, not HTTP polling
Static deploy stale	Cache not cleared	Redeploy or add cache-busting

Resources

• Replit Deployments
• Replit Database Options
• Upstash (Redis/Kafka)
• Neon (PostgreSQL)

Next Steps

For known pitfalls at each scale, see replit-known-pitfalls.