From replit-pack
Implements Replit production architecture: project layout, PostgreSQL/KV/object storage data layer, Express/Flask servers, Replit auth, secrets, and deployment.
How this skill is triggered — by the user, by Claude, or both
Slash command
/replit-pack:replit-reference-architectureThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
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.
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.
┌──────────────────────────┐
│ 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 │
└──────────────────────────────────────────────────────────────┘
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
# .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
];
}
// 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);
}
| 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();
// 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);
});
| 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) |
| 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 |
For deployment, see replit-deploy-integration. For multi-environment, see replit-multi-env-setup.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin replit-packSelect Replit app architectures: single-file prototype, modular PostgreSQL app, multi-service. Decision matrix and code configs for scaling from prototype to production.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.