# Jeremylongshore Claude Code Plugins Plus Skills Replit Reference Architecture > Replit Reference Architecture - Skill: `tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-replit-refer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-replit-refer` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-replit-refer/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/jeremylongshore-claude-code-plugins-plus-skills-replit-refer --- # 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 ``` ### Step 2: Configuration Files ```toml # .replit entrypoint = "src/index.ts" run = "npx tsx src/index.ts" modules = ["nodejs-20:v8-20230920-bd784b9"] [nix] channel = "stable-24_05" [env] NODE_ENV = "development" [deployment] run = ["sh", "-c", "npx tsx src/index.ts"] build = ["sh", "-c", "npm ci --production"] deploymentTarget = "autoscale" [unitTest] language = "nodejs" [languages.typescript] pattern = "**/*.ts" ``` ```nix # replit.nix { pkgs }: { deps = [ pkgs.nodejs-20_x pkgs.nodePackages.typescript-language-server ]; } ``` ### Step 3: Configuration Module ```typescript // src/config.ts — centralized configuration with validation export const config = { port: parseInt(process.env.PORT || '3000'), nodeEnv: process.env.NODE_ENV || 'development', isProduction: process.env.NODE_ENV === 'production', repl: { slug: process.env.REPL_SLUG || 'unknown', owner: process.env.REPL_OWNER || 'unknown', id: process.env.REPL_ID, }, db: { url: process.env.DATABASE_URL, kvUrl: process.env.REPLIT_DB_URL, }, } as const; // Validate required secrets at import time const REQUIRED_SECRETS = ['DATABASE_URL']; const missing = REQUIRED_SECRETS.filter(k => !process.env[k]); if (missing.length > 0 && config.isProduction) { console.error(`FATAL: Missing secrets: ${missing.join(', ')}`); process.exit(1); } ``` ### Step 4: Data Layer Strategy | Storage | Use When | Limits | |---------|----------|--------| | **PostgreSQL** | Structured data, relations, queries | Plan-dependent | | **Replit KV** | Simple cache, session data, counters | 50 MiB, 5K keys | | **Object Storage** | Files, images, backups, large blobs | Plan-dependent | ```typescript // src/services/postgres.ts import { Pool } from 'pg'; import { config } from '../config'; export const pool = new Pool({ connectionString: config.db.url, ssl: { rejectUnauthorized: false }, max: 5, idleTimeoutMillis: 30000, connectionTimeoutMillis: 5000, }); // src/services/kv.ts import Database from '@replit/database'; export const kv = new Database(); // src/services/storage.ts import { Client } from '@replit/object-storage'; export const storage = new Client(); ``` ### Step 5: Entry Point Pattern ```typescript // src/index.ts import express from 'express'; import { config } from './config'; import { pool } from './services/postgres'; import healthRouter from './routes/health'; import apiRouter from './routes/api'; import { requireAuth } from './middleware/auth'; import { errorHandler } from './middleware/errors'; const app = express(); app.use(express.json({ limit: '1mb' })); // Public routes app.use(healthRouter); // Protected routes app.use('/api', requireAuth, apiRouter); // Global error handler (must be last) app.use(errorHandler); // Start server — bind to 0.0.0.0 (required for Replit) app.listen(config.port, '0.0.0.0', () => { console.log(`[${config.repl.slug}] Running on port ${config.port}`); // Pre-connect database pool.query('SELECT 1').catch(err => { console.error('Database connection failed:', err.message); }); }); // Graceful shutdown process.on('SIGTERM', async () => { console.log('SIGTERM received, shutting down...'); await pool.end(); process.exit(0); }); ``` ## Platform Constraints | Constraint | Impact | Mitigation | |-----------|--------|------------| | Ephemeral filesystem | Files lost on restart | Use DB or Object Storage | | Cold starts (Autoscale) | 5-30s first request | Reserved VM or lazy loading | | Memory limits | OOM kills | Stream data, limit pool size | | Public Repls | Source visible | Never hardcode secrets | | Container restarts | State loss | External state (DB/Storage) | ## Error Handling | Issue | Cause | Solution | |-------|-------|----------| | Cold start slow | Heavy imports at startup | Lazy-load non-critical modules | | DB connection refused | PostgreSQL not provisioned | Create database in Database pane | | Secrets undefined | Not in Secrets tab | Add via sidebar lock icon | | Filesystem writes lost | Ephemeral container | Use Object Storage or PostgreSQL | ## Resources - [Replit App Configuration](https://docs.replit.com/replit-app/configuration) - [PostgreSQL on Replit](https://docs.replit.com/cloud-services/storage-and-databases/postgresql-on-replit) - [Object Storage](https://docs.replit.com/cloud-services/storage-and-databases/object-storage/overview) - [Replit Deployments](https://docs.replit.com/hosting/deployments) ## Next Steps For deployment, see `replit-deploy-integration`. For multi-environment, see `replit-multi-env-setup`. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/jeremylongshore) — claim your Tome and manage your conversions.