Skip to content

Local Development

The SMACKZ platform runs locally via Docker Compose, managed through the smackz-dev-environment repo. This provides a consistent development environment with all services, databases, and supporting infrastructure.

Prerequisites

Tool Version Notes
Docker Latest Docker Desktop or Docker Engine
Docker Compose v2+ Included with Docker Desktop
Node.js >= 20.18.1 For running services outside Docker
Python 3.12 For lakehouse services

One-Shot Setup

cd smackz-dev-environment
./setup.sh --env qa

The script clones every SMACKZ repo into the parent SMACKZ/ directory, configures Docker Compose, auto-detects SSH/HTTPS GitHub access, starts PostgreSQL, pushes schemas (yum / loyalty / pos-adapters via npm run db:push), starts all services, and creates a SuperAdmin.

Starting the Environment

cd smackz-dev-environment
docker compose up --build

This starts all core services:

Service Port URL
Yum Backend API 8080 http://localhost:8080/docs
Loyalty Service 3003 http://localhost:3003
Analytics AI Services 8000 http://localhost:8000
POS Adapters 3001 http://localhost:3001
MCP Server 8001 http://localhost:8001
MCP Gateway 3010 http://localhost:3010
Smackz-Admin 5173 http://localhost:5173
KDS-Web 5174 http://localhost:5174
Smackz-Websites 5175 http://localhost:5175
Payment Page 5172 http://localhost:5172
Restaurant Website 4444 http://localhost:4444
PostgreSQL 5432 yum_db / loyalty_db / adapter_db
Redis 6379 redis://localhost:6379
Verdaccio (npm) 4873 Local registry for shared packages
MinIO (S3) 9000 / 9001 http://localhost:9001 (console)
Lakehouse Writer 8090 http://localhost:8090/health
Lakehouse Query API 8091 http://localhost:8091/docs
Metabase 3200 http://localhost:3200

Optional Observability Profile

docker compose --profile observability up -d

Adds:

Service Port Purpose
Loki 3100 Log aggregation
Grafana 3200 LogQL queries + dashboards
Promtail -- Scrapes service stdout

Correlation IDs (x-correlation-id header) thread through all logs via AsyncLocalStorage and propagate over Redis Streams and webhooks.

Database

Local development uses the smackz_postgres container running PostgreSQL 14. Never connect to Neon or cloud databases during local development.

To use the local database:

# Connection string
POSTGRES_URL=postgresql://yumuser:password@localhost:5432/yum

# Push schema (run manually)
cd yum && npm run db:push

# Open Drizzle Studio
cd yum && npm run db:studio

Shared Packages

A local Verdaccio npm registry runs alongside the stack. Shared packages (shared-core, shared-ui, etc.) are auto-published on startup by a shared-packages-init step, and consumer services depend on the registry. Hot rebuilds are wired via the ./dc.sh publish-shared helper, which rebuilds the shared libraries and restarts dependents.

The dependency chain on startup is:

postgres / redis / verdaccio
       │
       ▼
shared-packages-init   (compiles & publishes shared libs)
       │
       ▼
backends + frontends

Backends (Node) hot-reload on .ts change via tsx watch; the analytics service uses uvicorn --reload; frontends use Vite HMR.

Image Storage

Locally, MinIO replaces Cloudflare R2 for S3-compatible storage. The MinIO console is at http://localhost:9001 (credentials: minioadmin/minioadmin).

Service-Specific Development

Running a single service outside Docker

If you prefer running a specific service directly (e.g., for debugging):

# Yum Backend
cd yum && npm install && cp .env.dev .env && npm run dev

# Smackz-Admin
cd Smackz-Admin && npm install && npm run dev

# Smackz-Websites
cd Smackz-Websites && npm install && npm run dev

Rebuilding after code changes

docker compose restart <service-name>
# or for full rebuild:
docker compose up --build <service-name>

First-Time Setup

  1. Start the Docker environment
  2. Create a SuperAdmin user: bash cd yum npm run create:superadmin John Doe john@example.com 1234567890 password123
  3. Get auth tokens: bash npm run get:tokens john@example.com password123
  4. Open Swagger UI at http://localhost:8080/docs to test APIs

Key Files

  • smackz-dev-environment/docker-compose.yml -- Full service definitions
  • smackz-dev-environment/.env.docker -- Environment variable template
  • yum/.env.dev -- Pre-configured dev environment for Yum
  • yum/scripts/start-local-db.sh -- Standalone PostgreSQL setup