| name | replit-reference-architecture |
| description | Implement Replit reference architecture with best-practice project layout, data layer, and deployment.
Use when designing new Replit apps, reviewing project structure,
or establishing architecture standards for production Replit applications.
Trigger with phrases like "replit architecture", "replit best practices",
"replit project structure", "how to organize replit", "replit production layout".
|
| allowed-tools | Read, Grep |
| version | 1.12.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","replit","architecture","reference"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Replit Reference Architecture
Overview
Production architecture for applications on Replit. Covers project structure, configuration files, data layer (PostgreSQL + KV + Object Storage), authentication, deployment strategy, and the platform constraints that shape architectural decisions.
Architecture Diagram
┌──────────────────────────┐
│ Client (Browser) │
└──────────┬───────────────┘
│ HTTPS
┌──────────▼───────────────┐
│ Replit Proxy (TLS, Auth) │
│ Injects X-Replit-User-* │
└──────────┬───────────────┘
│
┌──────────────────────────────▼──────────────────────────────┐
│ Replit Deployment │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ .replit │ │ replit.nix │ │ Secrets (AES-256) │ │
│ │ (run/build) │ │ (Nix deps) │ │ (env vars) │ │
│ └─────────────┘ └──────────────┘ └───────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Express / Flask Server │ │
│ │ Routes │ Auth Middleware │ Error Handler │ Health │ │
│ └────────┬───────────────────────────────────┬─────────┘ │
│ │ │ │
│ ┌────────▼──────────┐ ┌───────────────────▼────────────┐ │
│ │ PostgreSQL │ │ Replit KV Database │ │
│ │ (DATABASE_URL) │ │ (REPLIT_DB_URL) │ │
│ │ Dev + Prod DBs │ │ 50 MiB, 5K keys │ │
│ └───────────────────┘ └────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Object Storage (App Storage) ││
│ │ File uploads, backups, large data ││
│ │ @replit/object-storage SDK ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ Deployment: Autoscale │ Reserved VM │ Static │
└──────────────────────────────────────────────────────────────┘
Instructions
Step 1: Project Structure
my-replit-app/
├── .replit # Run + deployment configuration
├── replit.nix # System-level Nix dependencies
├── package.json # npm dependencies + scripts
├── tsconfig.json # TypeScript config
├── src/
│ ├── index.ts # Entry point — Express setup
│ ├── config.ts # Secrets validation + env config
│ ├── routes/
│ │ ├── api.ts # Business logic endpoints
│ │ ├── auth.ts # Auth-related routes
│ │ └── health.ts # Health check (required for deploy)
│ ├── services/
│ │ ├── postgres.ts # PostgreSQL pool singleton
│ │ ├── kv.ts # Replit KV Database wrapper
│ │ └── storage.ts # Object Storage wrapper
│ ├── middleware/
│ │ ├── auth.ts # Replit Auth header extraction
│ │ ├── rateLimit.ts # Rate limiting
│ │ └── errors.ts # Global error handler
│ └── types/
│ └── index.ts # Shared type definitions
├── tests/
│ ├── api.test.ts # API integration tests
│ └── services.test.ts # Service unit tests
└── scripts/
└── migrate.ts # Database migration scripts
