Platform Operations

Start, stop, monitor, and validate the NaaP platform services.

Service Architecture#

The NaaP platform consists of these services:

Service	Port	Description
Next.js Shell	3000	Main web application (hosts plugins)
Base Service	4000	Core API (auth, teams, plugin registry)
Plugin Server	3100	Plugin asset server + CDN proxy
PostgreSQL	5432	Unified database (Docker)
Plugin Backends	4001-4012	Per-plugin Express APIs

Starting Services#

Shell + Core (Default)#

Terminal

$./bin/start.sh

Starts: Database, Base Service, Plugin Server, Next.js Shell. Plugins are served as static UMD bundles -- no plugin backends needed for basic operation.

Everything#

Terminal

$./bin/start.sh --all

Starts all of the above plus all 11 plugin backends.

Dev Mode (Single Plugin)#

Terminal

$./bin/start.sh dev my-dashboard

Starts shell + core + one plugin with hot-reload frontend and live backend.

Services Only (No Frontend)#

Terminal

$./bin/start.sh --services

Starts core services and all plugin backends without the Next.js shell.

Stopping Services#

Terminal

# Graceful shutdown of everything

$./bin/stop.sh

# Stop a specific plugin

$./bin/stop.sh my-dashboard

# Restart (stop + start)

$./bin/start.sh restart

All services receive SIGTERM simultaneously for parallel shutdown. Services get 5 seconds for graceful shutdown before force-kill. Set GRACEFUL_TIMEOUT=<seconds> environment variable to customize (e.g., GRACEFUL_TIMEOUT=15 ./bin/stop.sh).

Monitoring#

Status Dashboard#

Terminal

$./bin/start.sh status

Shows all running services with PID, uptime, and port information.

Live Watch#

Terminal

$./bin/start.sh watch

Auto-refreshing status dashboard (default: every 5 seconds). Press Ctrl+C to exit.

Tail Logs#

Terminal

# Tail a specific service log

$./bin/start.sh logs base-svc

$./bin/start.sh logs shell-web

$./bin/start.sh logs my-dashboard-svc

Log files are stored in the logs/ directory.

Validation#

Terminal

$./bin/start.sh validate

Runs a comprehensive health check covering:

Core Services -- HTTP health endpoints for Base Service, Plugin Server, Shell
Plugin Backends -- Health endpoints for each running plugin backend
Plugin CDN Assets -- Verifies all 11 UMD bundles are accessible via CDN
Plugin .env Files -- Ensures all DATABASE_URLs point to the unified database
Database Schemas -- Checks all PostgreSQL schemas exist
Core API Endpoints -- Verifies auth, feature flags, plugins, marketplace, health APIs

Interpreting Results#

Status	Meaning
PASS	Service or check is healthy
SKIP	Service not running (expected if not started)
FAIL	Something is broken (action needed)

A clean validation shows: 38 passed, 0 failed.

Database Operations#

Prisma Studio (Visual DB Editor)#

Terminal

$cd packages/database

$npx prisma studio

Opens a visual database editor at http://localhost:5555.

Reset Database#

Terminal

# Drop all data and re-create tables

$cd packages/database

$DATABASE_URL="postgresql://postgres:postgres@localhost:5432/naap" npx prisma db push --force-reset

# Re-seed initial data

$cd apps/web-next

$npx tsx prisma/seed.ts

View Schemas#

Terminal

$docker exec naap-db psql -U postgres -d naap -c "\dn"

Plugin Build Operations#

Terminal

# Build all plugins

$npm run build:plugins

# Build a single plugin

$cd plugins/my-dashboard/frontend && npm run build

Plugin UMD bundles are output to plugins/<name>/frontend/dist/production/<name>.js and served via CDN at http://localhost:3000/cdn/plugins/<name>/1.0.0/<name>.js.

Common Workflows#

Fresh Start (Clean Slate)#

Terminal

$./bin/stop.sh

$docker rm -f naap-db # Remove database container

$docker volume rm naap-db-data # Remove database data

$./bin/start.sh # Full re-setup + start (setup is automatic)

Update After Git Pull#

Terminal

$git pull

$npm install

$npm run build:plugins

$./bin/start.sh restart

Port Conflicts#

Terminal

# Find what's using a port

$lsof -i :3000

# Force-kill all NaaP processes

$./bin/stop.sh

Service Architecture#

The NaaP platform consists of these services:

Service	Port	Description
Next.js Shell	3000	Main web application (hosts plugins)
Base Service	4000	Core API (auth, teams, plugin registry)
Plugin Server	3100	Plugin asset server + CDN proxy
PostgreSQL	5432	Unified database (Docker)
Plugin Backends	4001-4012	Per-plugin Express APIs

Starting Services#

Shell + Core (Default)#

Terminal

$./bin/start.sh

Starts: Database, Base Service, Plugin Server, Next.js Shell. Plugins are served as static UMD bundles -- no plugin backends needed for basic operation.

Everything#

Terminal

$./bin/start.sh --all

Starts all of the above plus all 11 plugin backends.

Dev Mode (Single Plugin)#

Terminal

$./bin/start.sh dev my-dashboard

Starts shell + core + one plugin with hot-reload frontend and live backend.

Services Only (No Frontend)#

Terminal

$./bin/start.sh --services

Starts core services and all plugin backends without the Next.js shell.

Stopping Services#

Terminal

# Graceful shutdown of everything

$./bin/stop.sh

# Stop a specific plugin

$./bin/stop.sh my-dashboard

# Restart (stop + start)

$./bin/start.sh restart

Monitoring#

Status Dashboard#

Terminal

$./bin/start.sh status

Shows all running services with PID, uptime, and port information.

Live Watch#

Terminal

$./bin/start.sh watch

Auto-refreshing status dashboard (default: every 5 seconds). Press Ctrl+C to exit.

Tail Logs#

Terminal

# Tail a specific service log

$./bin/start.sh logs base-svc

$./bin/start.sh logs shell-web

$./bin/start.sh logs my-dashboard-svc

Log files are stored in the logs/ directory.

Validation#

Terminal

$./bin/start.sh validate

Runs a comprehensive health check covering:

Core Services -- HTTP health endpoints for Base Service, Plugin Server, Shell
Plugin Backends -- Health endpoints for each running plugin backend
Plugin CDN Assets -- Verifies all 11 UMD bundles are accessible via CDN
Plugin .env Files -- Ensures all DATABASE_URLs point to the unified database
Database Schemas -- Checks all PostgreSQL schemas exist
Core API Endpoints -- Verifies auth, feature flags, plugins, marketplace, health APIs

Interpreting Results#

Status	Meaning
PASS	Service or check is healthy
SKIP	Service not running (expected if not started)
FAIL	Something is broken (action needed)

A clean validation shows: 38 passed, 0 failed.

Database Operations#

Prisma Studio (Visual DB Editor)#

Terminal

$cd packages/database

$npx prisma studio

Opens a visual database editor at http://localhost:5555.

Reset Database#

Terminal

# Drop all data and re-create tables

$cd packages/database

$DATABASE_URL="postgresql://postgres:postgres@localhost:5432/naap" npx prisma db push --force-reset

# Re-seed initial data

$cd apps/web-next

$npx tsx prisma/seed.ts

View Schemas#

Terminal

$docker exec naap-db psql -U postgres -d naap -c "\dn"

Plugin Build Operations#

Terminal

# Build all plugins

$npm run build:plugins

# Build a single plugin

$cd plugins/my-dashboard/frontend && npm run build

Plugin UMD bundles are output to plugins/<name>/frontend/dist/production/<name>.js and served via CDN at http://localhost:3000/cdn/plugins/<name>/1.0.0/<name>.js.

Common Workflows#

Fresh Start (Clean Slate)#

Terminal

$./bin/stop.sh

$docker rm -f naap-db # Remove database container

$docker volume rm naap-db-data # Remove database data

$./bin/start.sh # Full re-setup + start (setup is automatic)

Update After Git Pull#

Terminal

$git pull

$npm install

$npm run build:plugins

$./bin/start.sh restart

Port Conflicts#

Terminal

# Find what's using a port

$lsof -i :3000

# Force-kill all NaaP processes

$./bin/stop.sh