replit-reference-architecture

Replit Reference Architecture

Overview

Production architecture for applications on Replit. Covers project structure for deployments, secrets management, database integration with Replit DB and PostgreSQL, and multi-environment configuration.

Prerequisites

• Replit account with deployment tier
• Understanding of .replit and replit.nix
• Nix package manager basics
• PostgreSQL or Replit DB familiarity

Architecture Diagram

┌──────────────────────────────────────────────────────┐
│              Replit Workspace                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐    │
│  │ .replit   │  │ replit   │  │ Secrets          │    │
│  │ (config)  │  │ .nix     │  │ (env vars)       │    │
│  └──────────┘  └──────────┘  └──────────────────┘    │
├──────────────────────────────────────────────────────┤
│              Application                              │
│  ┌──────────────────────────────────────────────┐     │
│  │         Express/Fastify Server                │     │
│  │  Routes │ Middleware │ WebSocket              │     │
│  └──────────────────────┬───────────────────────┘     │
│                         │                             │
│  ┌──────────────────────┴───────────────────────┐     │
│  │         Data Layer                            │     │
│  │  Replit DB │ PostgreSQL │ Object Storage      │     │
│  └──────────────────────────────────────────────┘     │
├──────────────────────────────────────────────────────┤
│  Deployment: Autoscale │ Reserved VM │ Static        │
└──────────────────────────────────────────────────────┘

Instructions

Step 1: Project Structure

my-replit-app/
├── .replit                  # Run configuration
├── replit.nix               # System dependencies
├── src/
│   ├── index.ts             # Entry point
│   ├── routes/
│   │   ├── api.ts           # API routes
│   │   └── health.ts        # Health check
│   ├── services/
│   │   ├── database.ts      # DB connection
│   │   └── cache.ts         # Caching layer
│   └── middleware/
│       ├── auth.ts          # Authentication
│       └── rateLimit.ts     # Rate limiting
├── tests/
├── tsconfig.json
└── package.json

Step 2: Replit Configuration Files

# .replit
run = "npm start"
entrypoint = "src/index.ts"

[nix]
channel = "stable-24_05"

[env]
NODE_ENV = "production"

[deployment]
run = ["sh", "-c", "npm run build && npm start"]
build = ["sh", "-c", "npm ci && npm run build"]
deploymentTarget = "cloudrun"

[languages.typescript]
pattern = "**/*.ts"

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

Step 3: Database Integration

// src/services/database.ts
import { Pool } from 'pg';

let pool: Pool | null = null;

export function getDB(): Pool {
  if (!pool) {
    pool = new Pool({
      connectionString: process.env.DATABASE_URL,
      max: 10,
      idleTimeoutMillis: 30000,  # 30000: 30 seconds in ms
      connectionTimeoutMillis: 5000,  # 5000: 5 seconds in ms
    });
  }
  return pool;
}

// Health check for database
export async function checkDBHealth(): Promise<boolean> {
  try {
    const result = await getDB().query('SELECT 1');
    return result.rows.length > 0;
  } catch {
    return false;
  }
}

Step 4: Application Entry Point

// src/index.ts
import express from 'express';
import { getDB, checkDBHealth } from './services/database';

const app = express();
app.use(express.json());

// Health endpoint (required for Replit deployments)
app.get('/health', async (req, res) => {
  const dbOk = await checkDBHealth();
  res.status(dbOk ? 200 : 503).json({  # 503: HTTP 200 OK
    status: dbOk ? 'healthy' : 'degraded',
    uptime: process.uptime(),
    memory: process.memoryUsage().heapUsed,
  });
});

app.get('/api/status', (req, res) => {
  res.json({ version: process.env.npm_package_version });
});

const PORT = parseInt(process.env.PORT || '3000');  # 3000: 3 seconds in ms
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Error Handling

Issue	Cause	Solution
Cold start slow	Heavy imports at startup	Use lazy imports for non-critical modules
DB connection refused	PostgreSQL not started	Check Replit DB provisioning
Secrets undefined	Not set in Secrets tab	Configure in Replit workspace Secrets
Deploy fails	Build step error	Test build locally before deploying

Examples

Quick Deployment Check

set -euo pipefail
# Test build locally before deploying
npm run build && npm start
# Verify health endpoint
curl http://localhost:3000/health  # 3000: 3 seconds in ms

Resources

• Replit Deployments
• Replit Database
• Replit Nix Guide

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale