replit-reference-architecture

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".

Ir a la instalación

Repositorio: jeremylongshore/claude-code-plugins-plus-skills
Última actividad en el origen: 17 de julio de 2026 a las 22:18
Idioma detectado de SKILL.md: inglés
Estrellas: 2604
Forks: 378

Opciones de instalación

De forma predeterminada está seleccionado el prompt que primero revisa el origen. Puedes cambiar a un comando directo o descargar una copia local.

Revisa los archivos de origen

Lee SKILL.md y los archivos complementarios que muestra SkillsMP antes de decidir si quieres instalarlo.

Volver a la búsqueda Volver a la instalación

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

# .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"

# replit.nix
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
  ];
}

Step 3: Configuration Module

// 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.();
  process.();
}

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

// 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

// 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.);
  });
});


process.(,  () => {
  .();
   pool.();
  process.();
});

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

Next Steps

For deployment, see replit-deploy-integration. For multi-environment, see replit-multi-env-setup.